How to access the webpage DOM rather than the extension page DOM?

Question

I'm writing a Chrome extension and trying to overlay a <div> over the current webpage as soon as a button is clicked in the popup.html file.

When I access the document.body.insertBefore method from within popup.html it overlays the <div> on the popup, rather than the current webpage.

Do I have to use messaging between background.html and popup.html in order to access the web page's DOM? I would like to do everything in popup.html, and to use jQuery too, if possible.

Answer 1

Extension pages/scripts such as the browser_action popup or background script have their own DOM, document, window, and a chrome-extension:// URL (use devtools for that part of the extension to inspect it).

You need a content script to access DOM of web pages and interact with a tab's contents. Content scripts will execute in the tab as a part of that page, not as a part of the extension.

Method 1. Declarative

manifest.json:

"content_scripts": [{
  "matches": ["*://*.example.com/*"],
  "js": ["contentScript.js"]
}],

It will run once when the page loads. After that happens, use messaging but note, it can't send DOM elements, Map, Set, ArrayBuffer, classes, functions, and so on - it can only send JSON-compatible simple objects and types so you'll need to manually extract the required data and pass it as a simple array or object.

Method 2. Programmatic

• ManifestV2:

  Use chrome.tabs.executeScript to inject a content script on demand.

  The callback of this method receives results of the last expression in the content script so it can be used to extract data which must be JSON-compatible, see method 1 note above.

  Required permissions in manifest.json:

  • Best case: "activeTab", suitable for a response to a user action (usually a click on the extension icon in the toolbar). Doesn't show a permission warning when installing the extension.

  • Usual: "*://*.example.com/" plus any other sites you want.

  • Worst case: "<all_urls>" or "*://*/", "http://*/", "https://*/" - when submitting into Chrome Web Store all of these put your extension in a super slow review queue because of broad host permissions.

• ManifestV3 differences to the above:

  Use chrome.scripting.executeScript.

  Required permissions in manifest.json:

  • "scripting" - mandatory
  • "activeTab" - ideal scenario, see notes for ManifestV2 above.

  If ideal scenario is impossible add the allowed sites to host_permissions in manifest.json.

Answer 2

To illustrate programmatic injection let's add that div when a browser action is clicked.

ManifestV2

• Simple call:

  chrome.tabs.executeScript({ code: `(${ inContent1 })()` });
  
  function inContent1() {
    const el = document.createElement('div');
    el.style.cssText = 'position:fixed; top:0; left:0; right:0; background:red';
    el.textContent = 'DIV';
    document.body.appendChild(el);
  }
  

• Calling with parameters and receiving a result:

  chrome.tabs.executeScript({
    code: `(${ inContent2 })(${ JSON.stringify({ foo: 'bar' }) })`
  }, ([result] = []) => {
    if (!chrome.runtime.lastError) {
      console.log(result); // shown in devtools of the popup window
    }
  });
  
  function inContent2(params) {
    const el = document.createElement('div');
    el.style.cssText = 'position:fixed; top:0; left:0; right:0; background:red';
    el.textContent = params.foo;
    document.body.appendChild(el);
    return {
      success: true,
      html: document.body.innerHTML,
    };
  }
  

  This example uses automatic conversion of inContent function's code to string, the benefit here is that IDE can apply syntax highlight and linting. The obvious drawback is that the browser wastes time to parse the code, but usually it's less than 1 millisecond thus negligible.

ManifestV3

Don't forget to the permissions in manifest.json, see the other answer for more info.

• Simple call:

  async function tabAddDiv() {
    const [tab] = await chrome.tabs.query({active: true, currentWindow: true});
    await chrome.scripting.executeScript({
      target: {tabId: tab.id},
      function: inContent1, // see inContent1 in ManifestV2 example above
    });
  }
  

• Calling and receiving a result:

  async function tabAddDiv() {
    const [tab] = await chrome.tabs.query({active: true, currentWindow: true});
    let res;
    try {
      res = await chrome.scripting.executeScript({
        target: {tabId: tab.id},
        function: inContent2, // see inContent2 in ManifestV2 example above
      });
    } catch (e) {
      // handle the error if necessary or just ignore it
      return;
    }
    // res[0] contains results for the main page of the tab 
    document.body.textContent = JSON.stringify(res[0].result);
  }
  

• Calling with parameters and receiving a result:

  In the future executeScript will have args parameter, see https://crbug.com/1166720, meanwhile you'll have to use messaging.