How to Use Tampermonkey to Detect Multiple Words with Scripts

Tampermonkey allows you to detect multiple words on a webpage by injecting JavaScript that monitors the Document Object Model (DOM) for changes. By using the MutationObserver API, your script can watch for new elements being added to the page and check their text content against a list of target keywords. This approach ensures that even dynamically loaded content is scanned in real-time without requiring manual page refreshes or complex event listeners for every possible user interaction.

Setting Up Your Tampermonkey Script

Before writing the detection logic, you must configure the script metadata to ensure it runs on the correct pages. Open your Tampermonkey dashboard and create a new script. The header section defines where and how your code executes. You need to specify the @match directive to limit the script’s scope to specific domains or patterns, which improves performance and security.

// ==UserScript==
// @name         Multi-Word Detector
// @namespace    http://tampermonkey.net/
// @version      1.0
// @description  Detect multiple words on a webpage
// @author       You
// @match        https://example.com/*
// @grant        none
// ==/UserScript==

Replace https://example.com/* with the actual URL pattern of the site you are targeting. Using a wildcard at the end allows the script to run on all subpages, while specifying an exact domain prevents conflicts on other websites. Ensure that the @grant is set to none unless your script requires access to specific Tampermonkey APIs, as this keeps the execution context clean and faster.

Defining the Target Words

The core of the detection mechanism relies on a list of words or phrases you want to monitor. Storing these in an array makes it easy to add, remove, or modify the search terms without changing the logic of the observer. It is best practice to normalize these words to lowercase to ensure case-insensitive matching. This handles variations like "Error", "ERROR", and "error" uniformly.

const targetWords = [
    "urgent",
    "warning",
    "critical error",
    "success"
].map(word => word.toLowerCase());

By mapping over the array immediately, you avoid repeated calls to .toLowerCase() during the scanning process, which reduces computational overhead. If your target phrases contain spaces, such as "critical error", ensure they are treated as single strings rather than individual words. This distinction is crucial because splitting by space would break multi-word phrase detection.

Implementing the MutationObserver

Webpages often load content asynchronously via AJAX or JavaScript frameworks. A static scan upon page load will miss these updates. The MutationObserver API is the standard solution for watching DOM changes. It notifies you when nodes are added, removed, or when attributes change. In this scenario, we primarily care about child nodes being added to the document body or specific containers.

function checkNode(node) {
    if (node.nodeType === Node.TEXT_NODE) {
        const text = node.textContent.toLowerCase();
        targetWords.forEach(word => {
            if (text.includes(word)) {
                console.log(`Found "${word}" in:`, node.parentNode);
                // Add custom action here
            }
        });
    }
}

const observer = new MutationObserver((mutations) => {
    mutations.forEach((mutation) => {
        mutation.addedNodes.forEach(checkNode);
    });
});

observer.observe(document.body, {
    childList: true,
    subtree: true
});

This code sets up an observer on document.body with subtree: true, meaning it watches all descendants, not just direct children. When a mutation occurs, the callback iterates through each addedNode. The checkNode function verifies if the node is a text node. Checking nodeType === Node.TEXT_NODE is critical because iterating over element nodes would cause duplicate detections and potential errors when trying to read text content from non-text elements.

Handling Performance and Edge Cases

Watching the entire document subtree can be resource-intensive. If the page generates many rapid mutations, your script might trigger too frequently. To mitigate this, consider limiting the observation to specific container elements rather than the entire body. Identify the ID or class of the main content area and observe that element instead. Additionally, be aware that some websites obfuscate text or use shadow DOMs. Standard MutationObserver does not penetrate Shadow DOM boundaries by default. If your target site uses Web Components, you may need to attach observers to individual shadow roots. For most standard HTML5 sites, however, observing the body subtree is sufficient. If you find that your script is missing words that appear instantly, ensure that the content is actually inserted into the DOM before the observer fires. Sometimes, scripts inject HTML strings and parse them later. In such cases, you might need to hook into the framework’s rendering cycle, but for vanilla DOM manipulation, the above observer strategy is robust. For more advanced scenarios involving form interactions, you might also want to look at how to handle temporary state changes. See How to Temporarily Disable a JavaScript Check When Submitting a Form on a Webpage for techniques on managing dynamic UI states that might interfere with text detection. Another common issue is ensuring your script runs reliably across different environments. If your detection fails unexpectedly, verify that your selectors and match patterns are correct. Reviewing Tampermonkey Script to Toggle Between Posts No Longer Works can help troubleshoot general script execution failures that might stem from permission or loading order issues.

Frequently Asked Questions

Why is my script detecting words multiple times?

This usually happens because the MutationObserver triggers for every single node addition, including parent containers. Ensure you are checking nodeType === Node.TEXT_NODE to only process raw text. You should also implement a deduplication mechanism if you need to log each unique occurrence only once per page session.

Can I detect words inside input fields?

Yes, but input values are stored in the value attribute, not as text nodes within the DOM tree. You will need to modify your checkNode function to specifically inspect HTMLInputElement instances and read their .value property instead of .textContent.

Does this work on Single Page Applications (SPAs)?

It works well for SPAs because they continuously update the DOM, triggering mutations. However, heavy SPAs may generate thousands of mutations per second. Consider throttling your detection logic or observing only the specific route-container element to maintain performance.

What if the text is generated by CSS pseudo-elements?

Text defined in CSS ::before or ::after content properties is not part of the DOM text nodes. The MutationObserver cannot see this text. You would need to use getComputedStyle(element).content to retrieve it, which adds significant complexity and performance cost.

How do I stop the script from running on unwanted pages?

Refine your @match directive in the UserScript header. Use specific domain patterns like *://www.example.com/blog/* instead of broad wildcards. You can also add a conditional check at the start of your script to exit early if the current URL does not meet your criteria.