chrome.declarativeContent

Description

Permissions

Usage

The Declarative Content API allows you to enable your extension's action depending on the URL of a web page, or if a CSS selector matches an element on the page, without needing to add host permissions or inject a content script.

Use the activeTab permission to interact with a page after the user clicks on the extension's action.

Rules

Rules consists of conditions and actions. If any of the conditions is fulfilled, all actions are executed. The actions are setIcon and showAction.

The PageStateMatcher matches web pages if and only if all listed criteria are met. It can match a page url, a css compound selector or the bookmarked state of a page. The following rule enables the extension's action on Google pages when a password field is present:

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

To also enable the extension's action for Google sites with a video, you can add a second condition, as each condition is sufficient to trigger all specified actions:

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

The onPageChanged event tests whether any rule has at least one fulfilled condition and executes the actions. Rules persist across browsing sessions; therefore, during extension installation time you should first use removeRules to clear previously installed rules and then use addRules to register new ones.

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

With the activeTab permission, your extension will not display any permission warnings and when the user clicks the extension action, it will only run on relevant pages.

Page URL Matching

The PageStateMatcher.pageurl matches when the URL criteria are fulfilled. The most common criteria are a concatenation of either host, path, or url, followed by Contains, Equals, Prefix, or Suffix. The following table contains a few examples:

Criteria	Matches
{ hostSuffix: 'google.com' }	All Google URLs
{ pathPrefix: '/docs/extensions' }	Extension docs URLs
{ urlContains: 'developer.chrome.com' }	All chrome developers docs URLs

All criteria are case sensitive. For a complete list of criteria, see UrlFilter.

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.

Compound Selectors (OK)	Complex Selectors (Not OK)
a	div p
iframe.special[src^='http']	p>span.highlight
ns|*	p + ol
#abcd:checked	p::first-line

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.