Greasemonkey/ Tampermonkey @match for a page with parameters

Mastering @match for Greasemonkey/Tampermonkey with URL Parameters

Learn how to effectively use the @match directive in Greasemonkey and Tampermonkey userscripts to target web pages that include dynamic URL parameters, ensuring your scripts run exactly where and when you need them.

Greasemonkey and Tampermonkey userscripts are incredibly powerful tools for customizing your web browsing experience. A crucial part of writing effective userscripts is ensuring they execute on the correct web pages. The @match directive in your userscript's metadata block is designed for this purpose. However, matching URLs that contain dynamic parameters (like ?id=123&action=edit) can sometimes be tricky. This article will guide you through the nuances of using @match to handle such URLs, leveraging wildcards and understanding their behavior.

Understanding @match Basics

The @match directive specifies the URLs on which your userscript should run. It supports a simplified wildcard syntax, which is often sufficient for basic URL patterns. The most common wildcard is *, which matches zero or more characters. When dealing with URLs that have query parameters, it's important to understand how @match interprets these. By default, @match patterns do not directly match the query string part of a URL unless explicitly included with a wildcard.

// ==UserScript==
// @name         My Basic Script
// @namespace    http://tampermonkey.net/
// @version      0.1
// @description  A simple script
// @author       You
// @match        https://example.com/page
// @grant        none
// ==/UserScript==

(function() {
    'use strict';
    console.log('Script running on example.com/page');
})();

A basic userscript targeting a specific URL without parameters.

Matching URLs with Query Parameters

When a URL contains query parameters, such as https://example.com/page?id=123&action=view, the standard @match pattern https://example.com/page will not match it. This is because the query string ?id=123&action=view is considered part of the URL, and the pattern needs to account for it. To match pages with any query parameters, you need to use a wildcard after the path.

// ==UserScript==
// @name         Script for Pages with Parameters
// @namespace    http://tampermonkey.net/
// @version      0.1
// @description  Matches pages with any query parameters
// @author       You
// @match        https://example.com/page*
// @grant        none
// ==/UserScript==

(function() {
    'use strict';
    console.log('Script running on example.com/page with or without parameters');
})();

Using a wildcard to match URLs with any query parameters.

In the example above, https://example.com/page* will match:

• https://example.com/page
• https://example.com/page?id=123
• https://example.com/page?id=123&action=view
• https://example.com/page/subpath (Note: the wildcard matches path segments too)

Targeting Specific Parameters or Values

What if you only want your script to run when a specific parameter exists, or when a parameter has a certain value? The @match directive's wildcard capabilities are limited here. While you can use * to match the presence of any query string, you cannot directly specify a pattern like ?id=123 within @match itself. For such granular control, you typically need to combine @match with @include and regular expressions, or perform checks within your script's code.

flowchart TD
    A[Page Load] --> B{URL Matches @match?}
    B -- No --> E[Script Not Run]
    B -- Yes --> C{URL Matches @include (RegEx)?}
    C -- No --> E
    C -- Yes --> D[Script Runs]
    D --> F{Check URL in Script?}
    F -- No --> G[Perform Action]
    F -- Yes --> H{Specific Parameter/Value Found?}
    H -- No --> I[Do Nothing/Alternative]
    H -- Yes --> G

Decision flow for userscript execution with URL matching and in-script checks.

The diagram illustrates that @match provides the initial broad filter. For more specific parameter-based matching, you either rely on @include (which supports full regular expressions) or implement conditional logic directly within your JavaScript code using window.location.search or URLSearchParams.

// ==UserScript==
// @name         Script for Specific Parameter Value
// @namespace    http://tampermonkey.net/
// @version      0.1
// @description  Matches pages with 'action=edit' parameter
// @author       You
// @match        https://example.com/page*
// @grant        none
// ==/UserScript==

(function() {
    'use strict';

    const urlParams = new URLSearchParams(window.location.search);
    if (urlParams.get('action') === 'edit') {
        console.log('Script running because action=edit is present!');
        // Your script logic for edit pages goes here
    } else {
        console.log('Script ran, but action=edit was not found or had a different value.');
    }
})();

Using URLSearchParams within the script to check for specific parameter values.