Text Replacer example (#1718)

* Text Replacer example

* Addressing feedback from PR #612

* Fix issues identified in #1718 review

* Add more icon options to the manifest

* Add README

* Update copyright and license headers

* Iterating on feedback in #1718

* Simplify regex creation logic

* Fix ESLint errors and warnings

Author: dotproto

functional-samples/sample.text-replacer/README.md

@@ -0,0 +1,18 @@
+# Text Replacer
+
+This sample demonstrates how an extension can replace text on a page in response to user invocation.
+
+## Overview
+
+Users can use the extension's popup to define up to 5 pairs of text replacements. Text is replaced when the user clicks the "Replace" button in the popup, when they select the "Replace text" context menu option on a page, or when they use the extension's keyboard shortcut (command).
+
+## Compatibility
+
+`"minimum_chrome_version"` is set to 148 because that version adds support for returning a promise from an `onMessage` event handler ([docs](https://developer.chrome.com/docs/extensions/develop/concepts/messaging#:~:text=call%20it%20later.-,Return%20a%20promise,-From%20Chrome%20148)) to respond to a message asynchronously.
+
+## Running this extension
+
+1. Clone this repository.
+2. Load this directory in Chrome as an [unpacked extension](https://developer.chrome.com/docs/extensions/mv3/getstarted/development-basics/#load-unpacked).
+3. Navigate to any page (make sure that the URL doesn't start with `chrome://`).
+4. Click the extension icon.

functional-samples/sample.text-replacer/background.js

@@ -0,0 +1,70 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+const REPLACE_TEXT_MENUITEM_ID = 'replace-text-menuitem';
+const REPLACE_TEXT_COMMAND_ID = 'replace-text-command';
+const GET_REPLACEMENTS_MESSAGE_ID = 'get-replacements';
+const SET_REPLACEMENTS_MESSAGE_ID = 'set-replacements';
+
+chrome.runtime.onInstalled.addListener(async () => {
+  // Remove any previously registered context menus to avoid conflicts
+  await chrome.contextMenus.removeAll();
+
+  // Register the new set of context menus
+  await chrome.contextMenus.create({
+    id: REPLACE_TEXT_MENUITEM_ID,
+    title: 'Replace text'
+  });
+});
+
+chrome.commands.onCommand.addListener((command, tab) => {
+  if (command == REPLACE_TEXT_COMMAND_ID) {
+    replaceText(tab.id);
+  } else {
+    throw new Error(`Unknown command executed with ID "${command}"`);
+  }
+});
+
+chrome.contextMenus.onClicked.addListener((info, tab) => {
+  if (info.menuItemId == REPLACE_TEXT_MENUITEM_ID) {
+    replaceText(tab.id);
+  } else {
+    throw new Error(
+      `Unknown context menu option clicked with ID "${info.menuItemId}"`
+    );
+  }
+});
+
+// Route all storage reads/writes through the background so we have a single
+// source of truth
+chrome.runtime.onMessage.addListener((message) => {
+  switch (message.id) {
+    case GET_REPLACEMENTS_MESSAGE_ID:
+      // Fall back to an empty array 'patterns' is not set
+      return chrome.storage.sync.get({ patterns: [] });
+
+    case SET_REPLACEMENTS_MESSAGE_ID:
+      return chrome.storage.sync.set({ patterns: message.data });
+
+    default:
+      throw new Error(`Unknown message received with ID "${message.id}"`);
+  }
+});
+
+function replaceText(tabId) {
+  chrome.scripting.executeScript({
+    target: { tabId },
+    files: ['content.js']
+  });
+}

functional-samples/sample.text-replacer/content.js

@@ -0,0 +1,65 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Wrap the in an immediately invoked function expression (IIFE) in order to
+// prevent local variables from polluting global scope
+(function () {
+  const GET_REPLACEMENTS_MESSAGE_ID = 'get-replacements';
+
+  function buildReplacementRegex(source = []) {
+    const output = source
+      .filter(([find] = []) => find)
+      .map(([find, replace]) => {
+        const sanitizedMatch = escapeRegExp(find);
+        const findExp = new RegExp(`\\b${sanitizedMatch}\\b`, 'gi');
+        return [findExp, replace];
+      });
+    return output;
+  }
+
+  // For example purposes only. This may not cover all special characters used
+  // in regular repressions.
+  const REGEXP_SPECIAL_CHARACTERS = /[.(){}^$*+?[\]\\]/g;
+
+  /** Sanitize user input to prevent unexpected behavior during RegExp execution */
+  function escapeRegExp(pattern) {
+    return pattern.replace(REGEXP_SPECIAL_CHARACTERS, '\\$&');
+  }
+
+  /** Iterate through all text nodes and replace  */
+  function replaceText(replacements) {
+    const nodeIterator = document.createNodeIterator(
+      document.body,
+      NodeFilter.SHOW_TEXT
+    );
+
+    let node;
+    while ((node = nodeIterator.nextNode())) {
+      for (let [find, replace] of replacements) {
+        // Guard against nullish replacement values
+        replace ??= '';
+        node.nodeValue = node.nodeValue.replace(find, replace);
+      }
+    }
+  }
+
+  // Get the patterns to replace from storage, then build a regex from them and
+  // replace all text on the page.
+  chrome.runtime
+    .sendMessage({ id: GET_REPLACEMENTS_MESSAGE_ID })
+    .then((data) => {
+      const replacementPatterns = buildReplacementRegex(data.patterns);
+      replaceText(replacementPatterns);
+    });
+})();

functional-samples/sample.text-replacer/icons/icon128.png

@@ -0,0 +1,45 @@
+{
+  "name": "Text Replacer",
+  "version": "1.0.0",
+  "manifest_version": 3,
+  "description": "Replace any line of text on a page with another line of text.",
+  "minimum_chrome_version": "148",
+  "icons": {
+    "16": "icons/icon16.png",
+    "24": "icons/icon24.png",
+    "32": "icons/icon32.png",
+    "48": "icons/icon48.png",
+    "64": "icons/icon64.png",
+    "128": "icons/icon128.png"
+  },
+  "action": {
+    "default_title": "Manage text replacements",
+    "default_icon": {
+      "16": "icons/icon16.png",
+      "24": "icons/icon24.png",
+      "32": "icons/icon32.png",
+      "48": "icons/icon48.png",
+      "64": "icons/icon64.png"
+    },
+     "default_popup": "popup.html"
+  },
+  "permissions": [
+    "scripting",
+    "activeTab",
+    "storage",
+    "commands",
+    "contextMenus"
+  ],
+  "background": {
+    "service_worker": "background.js"
+  },
+  "commands": {
+    "replace-text-command": {
+      "description": "Replace text on the current page.",
+      "suggested_key": {
+        "default": "Alt+R",
+        "mac": "MacCtrl+R"
+      }
+    }
+  }
+}