Welcome Getting started API Reference Samples
Welcome Getting started API Reference Samples

chrome.declarativeContent

  • Description

    Use the chrome.declarativeContent API to take actions depending on the content of a page, without requiring permission to read the page's content.

  • Permissions
    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() ]
};

Note: All conditions and actions are created via a constructor as shown in the example above.

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]);
});
});

Note: You should always register or unregister rules in bulk rather than individually because each of these operations recreates internal data structures. This re-creation is computationally expensive but facilitates a faster matching algorithm.

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.

Compound Selectors (OK)Complex Selectors (Not OK)
adiv p
iframe.special[src^='http']p>span.highlight
ns|*p + ol
#abcd:checkedp::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

Summary

Types

PageStateMatcher

Matches the state of a web page based on various criteria.

Properties

  • css
    string[] optional

    Matches if all of the CSS selectors in the array match displayed elements in a frame with the same origin as the page's main frame. All selectors in this array must be compound selectors to speed up matching. Note: Listing hundreds of CSS selectors or listing CSS selectors that match hundreds of times per page can slow down web sites.

  • isBookmarked
    boolean optional

    Matches if the bookmarked state of the page is equal to the specified value. Requres the bookmarks permission.

  • pageUrl

    Matches if the conditions of the UrlFilter are fulfilled for the top-level URL of the page.

RequestContentScript

Declarative event action that injects a content script.

WARNING: This action is still experimental and is not supported on stable builds of Chrome.

Properties

  • allFrames
    boolean optional

    Whether the content script runs in all frames of the matching page, or in only the top frame. Default is false.

  • css
    string[] optional

    Names of CSS files to be injected as a part of the content script.

  • js
    string[] optional

    Names of JavaScript files to be injected as a part of the content script.

  • matchAboutBlank
    boolean optional

    Whether to insert the content script on about:blank and about:srcdoc. Default is false.

SetIcon

Declarative event action that sets the n-dip square icon for the extension's page action or browser action while the corresponding conditions are met. This action can be used without host permissions, but the extension must have a page or browser action.

Exactly one of imageData or path must be specified. Both are dictionaries mapping a number of pixels to an image representation. The image representation in imageData is an ImageData object; for example, from a canvas element, while the image representation in path is the path to an image file relative to the extension's manifest. If scale screen pixels fit into a device-independent pixel, the scale * n icon is used. If that scale is missing, another image is resized to the required size.

Properties

  • imageData
    ImageDataType | object optional

    Either an ImageData object or a dictionary {size -> ImageData} representing an icon to be set. If the icon is specified as a dictionary, the image used is chosen depending on the screen's pixel density. If the number of image pixels that fit into one screen space unit equals scale, then an image with size scale * n is selected, where n is the size of the icon in the UI. At least one image must be specified. Note that details.imageData = foo is equivalent to details.imageData = {'16': foo}.

ShowPageAction

Declarative event action that shows the extension's page action while the corresponding conditions are met. This action can be used without host permissions, but the extension must have a page action. If the extension has the activeTab permission, clicking the page action grants access to the active tab.

ImageDataType

Type

ArrayBuffer

PageStateMatcherInstanceType

Enum

"declarativeContent.PageStateMatcher"

RequestContentScriptInstanceType

Enum

"declarativeContent.RequestContentScript"

SetIconInstanceType

Enum

"declarativeContent.SetIcon"

ShowPageActionInstanceType

Enum

"declarativeContent.ShowPageAction"

Events

onPageChanged

chrome.declarativeContent.onPageChanged.addListener(listener: function)

Event

  • listener
    function

    The listener parameter should be a function that looks like this:

    () => {...}
We serve cookies on this site to analyze traffic, remember your preferences, and optimize your experience.