Welcome What's new in Chrome extensions Getting started API Reference Samples

chrome.action

  • Description

    Use the chrome.action API to control the extension's icon in the Google Chrome toolbar.

  • Manifest Keys

    The following keys must be declared in the manifest to use this API.

    action
  • Availability
    Chrome 88+ MV3+

You can use the chrome.action API to control the toolbar button for your extension in Chrome's UI. The action icons are displayed in the browser toolbar, to the right of the omnibox (on left-to-right devices). After installation, by default, these appear in the extensions menu (the puzzle piece). Users can choose to pin your extension icon to the toolbar.

Note that every extension will have an icon in the toolbar in Chrome, even if the action key is not specified.

Manifest

In order to use the chrome.action API, you need to specify a "manifest_version" of 3 or higher and include the action key in your manifest file.

{
"name": "Action Extension",
...
"action": {
"default_icon": { // optional
"16": "images/icon16.png", // optional
"24": "images/icon24.png", // optional
"32": "images/icon32.png" // optional
},
"default_title": "Click Me", // optional, shown in tooltip
"default_popup": "popup.html" // optional
},
...
}

Each of these values is optional; an empty dictionary is technically allowed.

These properties are described more below.

Parts of the UI

Icon

The icon is the main image used in the toolbar button. Icons are 16 DIPs (device-independent pixels) wide and tall. The icon is initially set by the default_icon key in the action entry in the manifest.json file. This key is a dictionary of sizes to image paths. Chrome will use these icons to choose which image scale to use. If an exact match is not found, Chrome will select the closest available and scale it to fit the image. However, this scaling can cause the icon to lose detail or look fuzzy.

Since devices with less-common scale factors like 1.5x or 1.2x are becoming more common, you are encouraged to provide multiple sizes for your icons. This also ensures that if the icon display size is ever changed, you don't need to do any more work to provide different icons.

The icon can also be set programmatically using the action.setIcon() method. This can be used to specify a different image path or to provide a dynamically-generated icon using the HTML canvas element, or, if setting from an extension service worker, the offscreen canvas API.

const canvas = new OffscreenCanvas(16, 16);
const context = canvas.getContext('2d');
context.clearRect(0, 0, 16, 16);
context.fillStyle = '#00FF00'; // Green
context.fillRect(0, 0, 16, 16);
const imageData = context.getImageData(0, 0, 16, 16);
chrome.action.setIcon({imageData: imageData}, () => { /* ... */ });

The action.setIcon() API is intended to set a static image. It should not be used to simulate animation.

Formats

For packed extensions (installed from a .crx file), images can be in most formats that the Blink rendering engine can display, including PNG, JPEG, BMP, ICO, and others (SVG is not supported). Unpacked extensions must use images in the PNG format.

Tooltip (title)

The tooltip, or title, appears when the user hovers the mouse on the extension's icon in the toolbar. It is also included in the accessible text spoken by screenreaders when the button gets focus.

The default tooltip is set from the default_title field of the action object in manifest.json. You can also set it programmatically with the action.setTitle() method.

Badge

Actions can optionally display a "badge" — a bit of text layered over the icon. This makes it easy to update the action to display a small amount of information about the state of the extension, such as a counter. The badge has a text component and a background color.

Note that the badge has limited space, and should typically use four characters or fewer.

The badge does not have a default taken from the manifest; you can set it programmatically with action.setBadgeBackgroundColor() and action.setBadgeText(). When setting the color, the values can be either an array of four integers between 0 and 255 that make up the RGBA color of the badge or a string with a CSS color value.

chrome.action.setBadgeBackgroundColor(
{color: [0, 255, 0, 0]}, // Green
() => { /* ... */ },
);

chrome.action.setBadgeBackgroundColor(
{color: '#00FF00'}, // Also green
() => { /* ... */ },
);

chrome.action.setBadgeBackgroundColor(
{color: 'green'}, // Also, also green
() => { /* ... */ },
);

An action's popup will be shown when the user clicks on the extension's action button in the toolbar. The popup can contain any HTML contents you like, and will be automatically sized to fit its contents. The popup cannot be smaller than 25x25 and cannot be larger than 800x600.

The popup is initially set from the default_popup property in the action key in the manifest.json file. If present, this should point to a relative path within the extension directory. It can also be updated dynamically to point to a different relative path using the action.setPopup() method.

The action.onClicked event will not be dispatched if the extension action has specified a popup to show on click on the current tab.

Per-tab state

Extension actions can have different states for each tab. For instance, you could set the badge text to be different on each tab (to show tab-specific state). You can set the value for an individual tab using the tabId property in the various setting methods on the action API. For instance, to set the badge text on a specific tab, you would do something like the following:

function getTabId() { /* ... */}
function getTabBadge() { /* ... */}

chrome.action.setBadgeText(
{
text: getTabBadge(tabId),
tabId: getTabId(),
},
() => { ... }
);

If the tabId property is omitted, the setting is treated as a global setting. Tab-specific settings take priority over any global settings.

Enabled state

By default, toolbar actions are enabled (clickable) on every tab. You can control this using the action.enable() and action.disable() methods. This only affects whether the popup (if any) or action.onClicked event is dispatched to your extension; it does not affect the action's presence in the toolbar.

Examples

The following examples show some common ways that actions are used in extensions. For a more robust demonstration of action capabilities, see the Action API example in the chrome-extension-samples repository.

Show a popup

It's common for an extension to display a popup when the user clicks the extension's action. To implement this in your own extension, declare the popup in your manifest.json and specify the content that Chrome should display in the popup.

// manifest.json
{
"name": "Action popup demo",
"version": "1.0",
"manifest_version": 3,
"action": {
"default_title": "Click to view a popup",
"default_popup": "popup.html"
}
}
<!-- popup.html -->
<!DOCTYPE html>
<html>
<head>
<style>
html {
min-height: 5em;
min-width: 10em;
background: salmon;
}
</style>
</head>
<body>
<p>Hello, world!</p>
</body>
</html>

Injecting a content script on click

A common pattern for extensions is to expose their primary functionality using the extension's action. The example below demonstrates this pattern. When the user clicks the action, the extension injects a content script into the current page. The content script then displays an alert to verify that everything worked as expected.

// manifest.json
{
"name": "Action script injection demo",
"version": "1.0",
"manifest_version": 3,
"action": {
"default_title": "Click to show an alert"
},
"permissions": ["activeTab", "scripting"],
"background": {
"service_worker": "background.js"
}
}
// background.js
chrome.action.onClicked.addListener((tab) => {
chrome.scripting.executeScript({
target: {tabId: tab.id},
files: ['content.js']
});
});
// content.js
alert('Hello, world!');

Emulating pageActions with declarativeContent

The chrome.action API replaced the browserAction and pageAction APIs in Manifest V3. By default, actions are similar to browser actions, but it is possible to emulate the behavior of a page action using the action API.

This example shows how an extension's background logic can (a) disable the action by default and (b) use declarativeContent to enable the action on specific sites.

// background.js

// Wrap in an onInstalled callback in order to avoid unnecessary work
// every time the background script is run
chrome.runtime.onInstalled.addListener(() => {
// Page actions are disabled by default and enabled on select tabs
chrome.action.disable();

// Clear all rules to ensure only our expected rules are set
chrome.declarativeContent.onPageChanged.removeRules(undefined, () => {
// Declare a rule to enable the action on example.com pages
let exampleRule = {
conditions: [
new chrome.declarativeContent.PageStateMatcher({
pageUrl: {hostSuffix: '.example.com'},
})
],
actions: [new chrome.declarativeContent.ShowAction()],
};

// Finally, apply our new array of rules
let rules = [exampleRule];
chrome.declarativeContent.onPageChanged.addRules(rules);
});
});

Summary

Types

OpenPopupOptions

Chrome 99+

Properties

  • windowId

    number optional

    The id of the window to open the action popup in. Defaults to the currently-active window if unspecified.

TabDetails

Properties

  • tabId

    number optional

    The ID of the tab to query state for. If no tab is specified, the non-tab-specific state is returned.

UserSettings

Chrome 91+

The collection of user-specified settings relating to an extension's action.

Properties

  • isOnToolbar

    boolean

    Whether the extension's action icon is visible on browser windows' top-level toolbar (i.e., whether the extension has been 'pinned' by the user).

Methods

disable

chrome.action.disable(
  tabId?: number,
  callback?: function,
)
Promise

Disables the action for a tab.

Parameters

  • tabId

    number optional

    The id of the tab for which you want to modify the action.

  • callback

    function optional

    The callback parameter looks like: () => void

Returns

  • Promise<void>

    Pending

    This only returns a Promise when the callback parameter is not specified, and with MV3+. The type inside the Promise is the same as the 1st argument to callback.

enable

chrome.action.enable(
  tabId?: number,
  callback?: function,
)
Promise

Enables the action for a tab. By default, actions are enabled.

Parameters

  • tabId

    number optional

    The id of the tab for which you want to modify the action.

  • callback

    function optional

    The callback parameter looks like: () => void

Returns

  • Promise<void>

    Pending

    This only returns a Promise when the callback parameter is not specified, and with MV3+. The type inside the Promise is the same as the 1st argument to callback.

getBadgeBackgroundColor

chrome.action.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)
Promise

Gets the background color of the action.

Parameters

Returns

  • Pending

    This only returns a Promise when the callback parameter is not specified, and with MV3+. The type inside the Promise is the same as the 1st argument to callback.

getBadgeText

chrome.action.getBadgeText(
  details: TabDetails,
  callback?: function,
)
Promise

Gets the badge text of the action. If no tab is specified, the non-tab-specific badge text is returned. If displayActionCountAsBadgeText is enabled, a placeholder text will be returned unless the declarativeNetRequestFeedback permission is present or tab-specific badge text was provided.

Parameters

  • details
  • callback

    function optional

    The callback parameter looks like: (result: string) => void

    • result

      string

Returns

  • Promise<string>

    Pending

    This only returns a Promise when the callback parameter is not specified, and with MV3+. The type inside the Promise is the same as the 1st argument to callback.

getPopup

chrome.action.getPopup(
  details: TabDetails,
  callback?: function,
)
Promise

Gets the html document set as the popup for this action.

Parameters

  • details
  • callback

    function optional

    The callback parameter looks like: (result: string) => void

    • result

      string

Returns

  • Promise<string>

    Pending

    This only returns a Promise when the callback parameter is not specified, and with MV3+. The type inside the Promise is the same as the 1st argument to callback.

getTitle

chrome.action.getTitle(
  details: TabDetails,
  callback?: function,
)
Promise

Gets the title of the action.

Parameters

  • details
  • callback

    function optional

    The callback parameter looks like: (result: string) => void

    • result

      string

Returns

  • Promise<string>

    Pending

    This only returns a Promise when the callback parameter is not specified, and with MV3+. The type inside the Promise is the same as the 1st argument to callback.

getUserSettings

chrome.action.getUserSettings(
  callback?: function,
)
Promise Chrome 91+

Returns the user-specified settings relating to an extension's action.

Parameters

  • callback

    function optional

    The callback parameter looks like: (userSettings: UserSettings) => void

Returns

  • Promise<UserSettings>

    Pending

    This only returns a Promise when the callback parameter is not specified, and with MV3+. The type inside the Promise is the same as the 1st argument to callback.

openPopup

chrome.action.openPopup(
  options?: OpenPopupOptions,
  callback?: function,
)
Promise Chrome 99+

Opens the extension's popup.

Parameters

  • options

    Specifies options for opening the popup.

  • callback

    function optional

    The callback parameter looks like: () => void

Returns

  • Promise<void>

    Pending

    This only returns a Promise when the callback parameter is not specified, and with MV3+. The type inside the Promise is the same as the 1st argument to callback.

setBadgeBackgroundColor

chrome.action.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)
Promise

Sets the background color for the badge.

Parameters

  • details

    object

    • color

      string | ColorArray

      An array of four integers in the range [0,255] that make up the RGBA color of the badge. For example, opaque red is [255, 0, 0, 255]. Can also be a string with a CSS value, with opaque red being #FF0000 or #F00.

    • tabId

      number optional

      Limits the change to when a particular tab is selected. Automatically resets when the tab is closed.

  • callback

    function optional

    The callback parameter looks like: () => void

Returns

  • Promise<void>

    Pending

    This only returns a Promise when the callback parameter is not specified, and with MV3+. The type inside the Promise is the same as the 1st argument to callback.

setBadgeText

chrome.action.setBadgeText(
  details: object,
  callback?: function,
)
Promise

Sets the badge text for the action. The badge is displayed on top of the icon.

Parameters

  • details

    object

    • tabId

      number optional

      Limits the change to when a particular tab is selected. Automatically resets when the tab is closed.

    • text

      string

      Any number of characters can be passed, but only about four can fit in the space.

  • callback

    function optional

    The callback parameter looks like: () => void

Returns

  • Promise<void>

    Pending

    This only returns a Promise when the callback parameter is not specified, and with MV3+. The type inside the Promise is the same as the 1st argument to callback.

setIcon

chrome.action.setIcon(
  details: object,
  callback?: function,
)
Promise

Sets the icon for the action. The icon can be specified either as the path to an image file or as the pixel data from a canvas element, or as dictionary of either one of those. Either the path or the imageData property must be specified.

Parameters

  • details

    object

    • imageData

      ImageData | object optional

      Either an ImageData object or a dictionary {size -> ImageData} representing icon to be set. If the icon is specified as a dictionary, the actual image to be used is chosen depending on screen's pixel density. If the number of image pixels that fit into one screen space unit equals scale, then image with size scale * n will be 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}'

    • path

      string | object optional

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

    • tabId

      number optional

      Limits the change to when a particular tab is selected. Automatically resets when the tab is closed.

  • callback

    function optional

    The callback parameter looks like: () => void

Returns

  • Promise<void>

    Pending

    This only returns a Promise when the callback parameter is not specified, and with MV3+. The type inside the Promise is the same as the 1st argument to callback.

setPopup

chrome.action.setPopup(
  details: object,
  callback?: function,
)
Promise

Sets the HTML document to be opened as a popup when the user clicks on the action's icon.

Parameters

  • details

    object

    • popup

      string

      The relative path to the HTML file to show in a popup. If set to the empty string (''), no popup is shown.

    • tabId

      number optional

      Limits the change to when a particular tab is selected. Automatically resets when the tab is closed.

  • callback

    function optional

    The callback parameter looks like: () => void

Returns

  • Promise<void>

    Pending

    This only returns a Promise when the callback parameter is not specified, and with MV3+. The type inside the Promise is the same as the 1st argument to callback.

setTitle

chrome.action.setTitle(
  details: object,
  callback?: function,
)
Promise

Sets the title of the action. This shows up in the tooltip.

Parameters

  • details

    object

    • tabId

      number optional

      Limits the change to when a particular tab is selected. Automatically resets when the tab is closed.

    • title

      string

      The string the action should display when moused over.

  • callback

    function optional

    The callback parameter looks like: () => void

Returns

  • Promise<void>

    Pending

    This only returns a Promise when the callback parameter is not specified, and with MV3+. The type inside the Promise is the same as the 1st argument to callback.

Events

onClicked

chrome.action.onClicked.addListener(
  callback: function,
)

Fired when an action icon is clicked. This event will not fire if the action has a popup.

Parameters

  • callback

    function

    The callback parameter looks like: (tab: tabs.Tab) => void