chrome.declarativeContent

Usage #

The Declarative Content API allows you to show your extension's page action depending on the URL of a web page and the CSS selectors its content matches, without needing to take a host permission or inject a content script. Use the activeTab permission in order to be able to interact with a page after the user clicks on your page action.

If you need more precise control over when your page action appears or you need to change its appearance to match the current tab before the user clicks on it, you'll have to keep using the pageAction API.

Rules #

As a declarative API, this API lets you register rules on the onPageChanged event object which take an action (ShowPageAction and SetIcon) when a set of conditions, represented as a PageStateMatcher, are met.

The PageStateMatcher matches web pages if and only if all listed criteria are met. The following rule would show a page action for pages on "https://www.google.com/" when a password field is present on it:

var rule1 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostEquals: 'www.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowPageAction() ]
};

In order to also show a page action for sites with a video, you can add a second condition, as each condition is sufficient to trigger all specified actions:

var rule2 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostEquals: 'www.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    }),
    new chrome.declarativeContent.PageStateMatcher({
      css: ["video"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowPageAction() ]
};

Added rules are saved across browser restarts, so register them as follows:

chrome.runtime.onInstalled.addListener(function(details) {
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    chrome.declarativeContent.onPageChanged.addRules([rule2]);
  });
});

Combine the above rule with the activeTab permission to create an extension that doesn't need any install-time permissions but can invite the user to click its page action on relevant pages and can run on those pages when the user clicks the page action.

CSS Matching #

PageStateMatcher.css conditions must be compound selectors, meaning that you can't include combinators like whitespace or ">" in your selectors. This helps Chrome match the selectors more efficiently.

CSS conditions only match displayed elements: if an element that matches your selector is display:none or one of its parent elements is display:none, it doesn't cause the condition to match. Elements styled with visibility:hidden, positioned off-screen, or hidden by other elements can still make your condition match.

Bookmarked State Matching #

The PageStateMatcher.isBookmarked condition allows matching of the bookmarked state of the current URL in the user's profile. To make use of this condition the "bookmarks" permission must be declared in the extension manifest