chrome.action
Description
Use thechrome.action API to control the extension's icon in the Google Chrome toolbar.
Availability
Manifest
To use thechrome.action API, specify a"manifest_version" of3 and includethe"action" key in yourmanifest file.
"action" key isn't added to the manifest.{"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 inyour 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 iconsto choose which image scale to use. If an exact match is not found, Chrome selects the closestavailable and scales it to fit the image, which might affect image quality.
Because devices with less-common scale factors like 1.5x or 1.2x are becoming morecommon, we encourage you to provide multiple sizes for your icons. This alsofutureproofs your extension against potential icon display size changes. However,if only providing a single size, the"default_icon" key can also be set to astring with the path to a single icon instead of a dictionary.
You can also callaction.setIcon() to set your extension's icon programmaticallyby specifying a different image path or providing a dynamically-generated icon using theHTML canvaselement, or, if setting from an extension service worker, theoffscreencanvas API.
constcanvas=newOffscreenCanvas(16,16);constcontext=canvas.getContext('2d');context.clearRect(0,0,16,16);context.fillStyle='#00FF00';// Greencontext.fillRect(0,0,16,16);constimageData=context.getImageData(0,0,16,16);chrome.action.setIcon({imageData:imageData},()=>{/* ... */});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 file), images can be in most formats that the Blinkrendering 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 thetoolbar. It's also included in the accessible text spoken by screen readers when the button getsfocus.
The default tooltip is set using the"default_title" field of the"action" key inmanifest.json.You can also set it programmatically by callingaction.setTitle().
Badge
Actions can optionally display a "badge" — a bit of text layered over the icon. This lets youupdate 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 callingaction.setBadgeBackgroundColor() andaction.setBadgeText(). There isn't a default badge setting in the manifest. Badge color valuescan be either an array of four integers between 0 and 255 that make up the RGBA color of thebadge or a string with aCSS 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 button in thetoolbar. The popup can contain any HTML contents you like, and will be automatically sized to fitits 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 themanifest.json file. If present, this property should point to a relative path within the extensiondirectory. It can also be updated dynamically to point to a different relative path using theaction.setPopup() method.
action.onClicked event won't be sent if the extension action has specified a popup toshow on click of the current tab.Use cases
Per-tab state
Extension actions can have different states for each tab. To set a value for an individualtab, use thetabId property in theaction API's setting methods. For example, toset the badge text for a specific tab, do something like the following:
functiongetTabId(){/* ... */}functiongetTabBadge(){/* ... */}chrome.action.setBadgeText({text:getTabBadge(tabId),tabId:getTabId(),},()=>{...});If thetabId property is left out, the setting is treated as a global setting. Tab-specificsettings take priority over global settings.
Enabled state
By default, toolbar actions are enabled (clickable) on every tab. You can change this defaultby setting thedefault_state property in theaction key of the manifest. Ifdefault_state is set to"disabled", the action is disabled by default and must be enabledprogrammatically to be clickable. Ifdefault_state is set to"enabled" (the default),the action is enabled and clickable by default.
You can control the state programmatically using theaction.enable() andaction.disable()methods. This only affects whether the popup (if any) oraction.onClicked event is sentto your extension; it doesn't affect 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 theAction API example from thechrome-extension-samplesrepository.
Show a popup
It's common for an extension to display a popup when the user clicks the extension's action. Toimplement this in your own extension, declare the popup in yourmanifest.json and specify thecontent 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 pattern for extensions is to expose their primary feature using the extension'saction. The following example demonstrates this pattern. When the user clicks the action, the extensioninjects a content script into the current page. The content script then displays an alert to verifythat 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.jschrome.action.onClicked.addListener((tab)=>{chrome.scripting.executeScript({target:{tabId:tab.id},files:['content.js']});});// content.jsalert('Hello, world!');Emulate actions with declarativeContent
This example shows how an extension's background logic can (a) disable an action by default and (b)usedeclarativeContent to enable the action on specific sites.
// service-worker.js// Wrap in an onInstalled callback to avoid unnecessary work// every time the service worker is runchrome.runtime.onInstalled.addListener(()=>{// Page actions are disabled by default and enabled on select tabschrome.action.disable();// Clear all rules to ensure only our expected rules are setchrome.declarativeContent.onPageChanged.removeRules(undefined,()=>{// Declare a rule to enable the action on example.com pagesletexampleRule={conditions:[newchrome.declarativeContent.PageStateMatcher({pageUrl:{hostSuffix:'.example.com'},})],actions:[newchrome.declarativeContent.ShowAction()],};// Finally, apply our new array of rulesletrules=[exampleRule];chrome.declarativeContent.onPageChanged.addRules(rules);});});Types
OpenPopupOptions
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
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).
UserSettingsChange
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()
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
callbackparameter 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()
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
callbackparameter 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()
chrome.action.getBadgeBackgroundColor(
details: TabDetails,
callback?: function,
)
Gets the background color of the action.
Parameters
- details
- callback
function optional
The
callbackparameter looks like:(result: ColorArray) => void
- result
Returns
Promise<extensionTypes.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()
chrome.action.getBadgeText(
details: TabDetails,
callback?: function,
)
Gets the badge text of the action. If no tab is specified, the non-tab-specific badge text is returned. IfdisplayActionCountAsBadgeText is enabled, a placeholder text will be returned unless thedeclarativeNetRequestFeedback permission is present or tab-specific badge text was provided.
Parameters
- details
- callback
function optional
The
callbackparameter 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()
chrome.action.getBadgeTextColor(
details: TabDetails,
callback?: function,
)
Gets the text color of the action.
Parameters
- details
- callback
function optional
The
callbackparameter looks like:(result: ColorArray) => void
- result
Returns
Promise<extensionTypes.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()
chrome.action.getPopup(
details: TabDetails,
callback?: function,
)
Gets the html document set as the popup for this action.
Parameters
- details
- callback
function optional
The
callbackparameter 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()
chrome.action.getTitle(
details: TabDetails,
callback?: function,
)
Gets the title of the action.
Parameters
- details
- callback
function optional
The
callbackparameter 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.
getUserSettings()
chrome.action.getUserSettings(
callback?: function,
)
Returns the user-specified settings relating to an extension's action.
Parameters
- callback
function optional
The
callbackparameter looks like:(userSettings: UserSettings) => void
- userSettings
Returns
Promise<UserSettings>
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()
chrome.action.isEnabled(
tabId?: number,
callback?: function,
)
Indicates whether the extension action is enabled for a tab (or globally if notabId is provided). Actions enabled using onlydeclarativeContent always return false.
Parameters
- tabId
number optional
The ID of the tab for which you want check enabled status.
- callback
function optional
The
callbackparameter 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()
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
Specifies options for opening the popup.
- callback
function optional
The
callbackparameter 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()
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#FF0000or#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
callbackparameter 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()
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 fit in the space. If an empty string (
'') is passed, the badge text is cleared. IftabIdis specified andtextis null, the text for the specified tab is cleared and defaults to the global badge text.
- callback
function optional
The
callbackparameter 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()
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#FF0000or#F00. Not setting 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
callbackparameter 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()
chrome.action.setIcon(
details: object,
callback?: function,
)
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 thepath or theimageData 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 sizescale* 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 sizescale* 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
callbackparameter 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()
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 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
callbackparameter 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()
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
callbackparameter 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 fire if the action has a popup.
onUserSettingsChanged
chrome.action.onUserSettingsChanged.addListener(
callback: function,
)
Fired when user-specified settings relating to an extension's action change.
Parameters
- callback
function
The
callbackparameter looks like:(change: UserSettingsChange) => void
- change
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-06-04 UTC.