Chrome Extensions  Reference  API

Get inspired Blog Docs

 New in Chrome
 Search /  Sign in

Overview Get Started Develop How To AI Reference

 Samples Chrome Web Store


 Filter On this page

Description

Manifest V3 Availability
Home  Docs  Chrome Extensions  Reference  API Was this helpful?
➡ Manifest V2  Manifest

accessibilityFeatures chrome.action  Concepts and usage

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

alarms
The action icons are displayed in the browser toolbar next to the omnibox. A er installation, these appear in the Use cases
extensions menu (the puzzle piece icon). Users can pin your extension icon to the toolbar.
audio
Per-tab state

bookmarks Availability Enabled state

browsingData
Examples
Chrome 88+ MV3+

certi cateProvider
Show a popup

commands
Manifest
Inject a content script on click

contentSe ings The following keys must be declared in the manifest to use this API. Emulate actions with declarativeContent

contextMenus "action" Types

cookies To use the chrome.action API, specify a "manifest_version" of 3 and include the "action" key in your manifest
OpenPopupOptions
le.
debugger
TabDetails

declarativeContent
UserSe ings
 Note: Every extension has an icon in the Chrome toolbar, even if the "action" key isn't added to the manifest.
declarativeNetRequest
UserSe ingsChange

desktopCapture    Methods
{
"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
},
...
}

The "action" key (along with its children) is optional. When it isn't included, your extension is still shown in the toolbar
to provide access to the extension's menu. For this reason, we recommend that you always include at least the
"action" and "default_icon" keys.

Concepts and usage

Parts of the UI

Icon

The icon is the main image on the toolbar for your extension, and is set by the "default_icon" key in your manifest's
"action" key. Icons must be 16 device-independent pixels (DIPs) wide and tall.

The "default_icon" key is a dictionary of sizes to image paths. Chrome uses these icons to choose which image
scale to use. If an exact match is not found, Chrome selects the closest available and scales it to t the image, which
might a ect image quality.

Because devices with less-common scale factors like 1.5x or 1.2x are becoming more common, we encourage you to
provide multiple sizes for your icons. This also futureproofs your extension against potential icon display size changes.
However, if only providing a single size, the "default_icon" key can also be set to a string with the path to a single
icon instead of a dictionary.

You can also call action.setIcon() to set your extension's icon programmatically by specifying a di erent image path
or providing a dynamically-generated icon using the HTML canvas element, or, if se ing from an extension service
worker, the o screen 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}, () => { /* ... */ });

 Note: The action.setIcon() API is intended to set a static image. Don't use animated images for your icons.

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

Tooltip (title)

The tooltip, or title, appears when the user holds their mouse pointer over the extension's icon in the toolbar. It's also
included in the accessible text spoken by screen readers when the bu on gets focus.

The default tooltip is set using the "default_title" eld of the "action" key in manifest.json . You can also set it
programmatically by calling action.setTitle() .

Badge

Actions can optionally display a "badge" — a bit of text layered over the icon. This lets you 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. Because space is limited, we recommend that badge text use four or fewer characters.

To create a badge, set it programmatically by calling action.setBadgeBackgroundColor() and

action.setBadgeText() . There isn't a default badge se ing in the manifest. Badge color 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
() => { /* ... */ },
);

Popup

An action's popup is shown when the user clicks on the extension's action bu on in the toolbar. The popup can contain
any HTML contents you like, and will be automatically sized to t its contents. The popup's size must be between 25x25
and 800x600 pixels.

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

 Note: The action.onClicked event won't be sent if the extension action has speci ed a popup to show on click of the current tab.

Use cases

Per-tab state

Extension actions can have di erent states for each tab. To set a value for an individual tab, use the tabId property in
the action API's se ing methods. For example, to set the badge text for a speci c tab, do something like the
following:

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

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

If the tabId property is le out, the se ing is treated as a global se ing. Tab-speci c se ings take priority over global
se ings.

Enabled state

By default, toolbar actions are enabled (clickable) on every tab. You can change this default by se ing the
default_state property in the action key of the manifest. If default_state is set to "disabled" , the action is
disabled by default and must be enabled programmatically to be clickable. If default_state is set to "enabled" (the
default), the action is enabled and clickable by default.

You can control the state programmatically using the action.enable() and action.disable() methods. This only
a ects whether the popup (if any) or action.onClicked event is sent to your extension; it doesn't a ect the action's
presence in the toolbar.

Examples

The following examples show some common ways that actions are used in extensions. To try this API, install the Action
API example from 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>

Inject a content script on click

A common pa ern for extensions is to expose their primary feature using the extension's action. The following example
demonstrates this pa ern. 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!');

Emulate actions with declarativeContent

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

 
// service-worker.js

// Wrap in an onInstalled callback to avoid unnecessary work

// every time the service worker 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);
});
});

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 unspeci ed.

TabDetails

PROPERTIES

tabId

number optional

The ID of the tab to query state for. If no tab is speci ed, the non-tab-speci c state is returned.

UserSe ings

Chrome 91+

The collection of user-speci ed se ings 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).

UserSe ingsChange

Chrome 130+

PROPERTIES

isOnToolbar

boolean optional

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()

Promise

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

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>

Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use
both on the same function call. The promise resolves with the same type that is passed to the callback.

enable()

Promise

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

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>

Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use
both on the same function call. The promise resolves with the same type that is passed to the callback.

getBadgeBackgroundColor()

Promise

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

Gets the background color of the action.

PARAMETERS

details

TabDetails

callback

function optional

The callback parameter looks like:

 
(result: ColorArray) => void

result

ColorArray

RETURNS

Promise<browserAction.ColorArray>

Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use
both on the same function call. The promise resolves with the same type that is passed to the callback.

getBadgeText()

Promise

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

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

PARAMETERS

details

TabDetails

callback

function optional

The callback parameter looks like:

 
(result: string) => void

result

string

RETURNS

Promise<string>

Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use
both on the same function call. The promise resolves with the same type that is passed to the callback.

getBadgeTextColor()

Promise Chrome 110+

 
chrome.action.getBadgeTextColor(
details: TabDetails,
callback?: function,
)

Gets the text color of the action.

PARAMETERS

details

TabDetails

callback

function optional

The callback parameter looks like:

(result: ColorArray) => void

result

ColorArray

RETURNS

Promise<browserAction.ColorArray>

Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use
both on the same function call. The promise resolves with the same type that is passed to the callback.

getPopup()

Promise

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

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

PARAMETERS

details

TabDetails

callback

function optional

The callback parameter looks like:

(result: string) => void

result

string

RETURNS

Promise<string>

Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use
both on the same function call. The promise resolves with the same type that is passed to the callback.

getTitle()

Promise

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

Gets the title of the action.

PARAMETERS

details

TabDetails

callback

function optional

The callback parameter looks like:

(result: string) => void

result

string

RETURNS

Promise<string>

Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use
both on the same function call. The promise resolves with the same type that is passed to the callback.

getUserSe ings()

Promise Chrome 91+

chrome.action.getUserSettings(
callback?: function,
)

Returns the user-speci ed se ings relating to an extension's action.

PARAMETERS

callback

function optional

The callback parameter looks like:

(userSettings: UserSettings) => void

userSe ings

UserSe ings

RETURNS

Promise<UserSe ings>

Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use
both on the same function call. The promise resolves with the same type that is passed to the callback.

isEnabled()

Promise Chrome 110+

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

Indicates whether the extension action is enabled for a tab (or globally if no tabId is provided). Actions enabled using
only declarativeContent always return false.

PARAMETERS

tabId

number optional

The ID of the tab for which you want check enabled status.

callback

function optional

The callback parameter looks like:

(isEnabled: boolean) => void

isEnabled

boolean

True if the extension action is enabled.

RETURNS

Promise<boolean>

Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use
both on the same function call. The promise resolves with the same type that is passed to the callback.

openPopup()

Promise Chrome 127+

chrome.action.openPopup(
options?: OpenPopupOptions,
callback?: function,
)

Opens the extension's popup. Between Chrome 118 and Chrome 126, this is only available to policy installed extensions.

PARAMETERS

options

OpenPopupOptions optional

Speci es options for opening the popup.

callback

function optional

The callback parameter looks like:

() => void

RETURNS

Promise<void>

Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use
both on the same function call. The promise resolves with the same type that is passed to the callback.

setBadgeBackgroundColor()

Promise

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

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>

Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use
both on the same function call. The promise resolves with the same type that is passed to the callback.

setBadgeText()

Promise

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

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 optional

Any number of characters can be passed, but only about four can t in the space. If an empty string ( '' ) is
passed, the badge text is cleared. If tabId is speci ed and text is null, the text for the speci ed tab is cleared
and defaults to the global badge text.

callback

function optional

The callback parameter looks like:

() => void

RETURNS

Promise<void>

Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use
both on the same function call. The promise resolves with the same type that is passed to the callback.

setBadgeTextColor()

Promise Chrome 110+

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

Sets the text 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 . Not
se ing this value will cause a color to be automatically chosen that will contrast with the badge's background color
so the text will be visible. Colors with alpha values equivalent to 0 will not be set and will return an error.

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>

Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use
both on the same function call. The promise resolves with the same type that is passed to the callback.

setIcon()

Promise

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

Sets the icon for the action. The icon can be speci ed either as the path to an image le 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 speci ed.

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 speci ed
as a dictionary, the actual image to be used is chosen depending on screen's pixel density. If the number of image
pixels that t 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 speci ed. 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
speci ed as a dictionary, the actual image to be used is chosen depending on screen's pixel density. If the number
of image pixels that t 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 speci ed. 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>

Chrome 96+

Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use
both on the same function call. The promise resolves with the same type that is passed to the callback.

setPopup()

Promise

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

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 le 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>

Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use
both on the same function call. The promise resolves with the same type that is passed to the callback.

setTitle()

Promise

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

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>

Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use
both on the same function call. The promise resolves with the same type that is passed to the callback.

Events

onClicked

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

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

PARAMETERS

callback

function

The callback parameter looks like:

(tab: tabs.Tab) => void

tab

tabs.Tab

onUserSe ingsChanged

Chrome 130+

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

Fired when user-speci ed se ings relating to an extension's action change.

PARAMETERS

callback

function

The callback parameter looks like:

(change: UserSettingsChange) => void

change

UserSe ingsChange

Was this helpful?

Except as otherwise noted, the content of this page is licensed under the Creative Commons A ribution 4.0 License, and code samples are licensed under the
Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its a liates.

Last updated 2024-12-12 UTC.

Contribute Related content Follow

File a bug Chromium updates @ChromiumDev on X

See open issues Case studies YouTube

Archive Chrome for Developers on LinkedIn

Podcasts & shows RSS

Terms | Privacy