Skip to content

action.md

Latest commit

 

History

History
289 lines (189 loc) · 7.57 KB

action.md

File metadata and controls

289 lines (189 loc) · 7.57 KB
Raw

action

Documentation: Chrome Action API

A unified, promise-based wrapper around the Chrome Action API. It transparently uses chrome.action on Manifest V3 and falls back to chrome.browserAction on Manifest V2.

Methods

Events

isAvailableAction

isAvailableAction(method?: ApiMethodName<typeof chrome.action | typeof chrome.browserAction>): boolean

The optional method is a native function name, for example isAvailableAction("isEnabled"). Import the public ApiMethodName type from @addon-core/browser for your own typed helpers. This checks callable presence without invoking the method; permissions and argument support still require handling.

Checks the same API selected by action methods and events: action for Manifest V3 and browserAction for Manifest V2. Does not fall back to the other namespace if the selected one is missing. Returns false if the namespace or WebExtension environment is absent, or if accessing it throws. The check is synchronous, does not log, and reads the current API on every call without caching. Without an argument, it checks namespace presence only. Pass a native method name to also check that it is callable. Neither form verifies permissions, argument support, or a successful operation. See method availability.

import {isAvailableAction} from "@addon-core/browser";

if (isAvailableAction()) {
    // The namespace is present; handle operation-specific failures when using it.
}

disableAction

disableAction(tabId: number): Promise<void>

Disables the extension action for the specified tab. Falls back to chrome.browserAction.disable in MV2.

enableAction

enableAction(tabId: number): Promise<void>

Enables the extension action for the specified tab. Falls back to chrome.browserAction.enable in MV2.

getBadgeBgColor

getBadgeBgColor(tabId?: number): Promise<[number, number, number, number]>

Retrieves the badge background color for a given tab.

getBadgeText

getBadgeText(tabId?: number): Promise<string>

Retrieves the badge text for a given tab.

getBadgeTextColor [MV3]

getBadgeTextColor(tabId?: number): Promise<[number, number, number, number]>

Retrieves the badge text color for a given tab (Manifest V3 only).

getActionPopup

getActionPopup(tabId?: number): Promise<string>

Retrieves the popup URL set for the action in a given tab.

getActionTitle

getActionTitle(tabId?: number): Promise<string>

Retrieves the title set for the action in a given tab.

getActionUserSetting [MV3]

getActionUserSetting(): Promise<chrome.action.UserSettings>

Retrieves the user settings for the action (Manifest V3 only).

isActionEnabled

isActionEnabled(tabId: number): Promise<boolean>

Checks whether the action is enabled for the specified tab.

openActionPopup [MV3]

openActionPopup(windowId?: number): Promise<void>

Programmatically opens the action popup (Manifest V3 only).

setBadgeBgColor

setBadgeBgColor(color: string | [number, number, number, number], tabId?: number): Promise<void>

Sets the badge background color for a given tab.

setBadgeText

setBadgeText(text: string | number, tabId?: number): Promise<void>

Sets the badge text for a given tab.

setBadgeTextColor [MV3]

setBadgeTextColor(color: string | [number, number, number, number], tabId?: number): Promise<void>

Sets the badge text color for a given tab (Manifest V3 only).

setActionIcon

setActionIcon(details: chrome.action.TabIconDetails): Promise<void>

Sets the action icon for a tab or globally.

setActionPopup

setActionPopup(popup: string, tabId?: number): Promise<void>

Sets the popup URL for the action in a given tab.

setActionTitle

setActionTitle(title: string, tabId?: number): Promise<void>

Sets the title for the action in a given tab.

getDefaultPopup

getDefaultPopup(): string | undefined

Reads the manifest once and returns its default popup setting: action.default_popup in MV3 or browser_action.default_popup in MV2, using that snapshot's manifest_version.

Manifest configuration Result
default_popup: "popup.html" The exact configured string, "popup.html"
default_popup: "" The empty string, ""
default_popup is absent undefined
The selected action or browser_action section is absent undefined

Errors reading the manifest propagate unchanged. The helper reads the manifest default; it does not query a popup set dynamically or for a specific tab. Use getActionPopup(tabId) for the current action popup.

import {getDefaultPopup} from "@addon-core/browser";

const popup = getDefaultPopup();

if (popup !== undefined) {
    // The configured string is available, including an explicit empty string.
    console.log(popup);
} else {
    console.log("No default popup is configured in the manifest.");
}

Compatibility note: the return type changed from string to string | undefined. With strictNullChecks, callers must narrow the result before assigning it to a required string or calling string methods. Check against undefined when an explicit empty string must remain distinguishable from a missing setting. An absent action section now returns undefined instead of causing a property-access error.

clearBadgeText

clearBadgeText(tabId?: number): Promise<void>

Clears the badge text for a given tab.

onActionClicked

onActionClicked(callback: (tab: chrome.tabs.Tab) => void): () => void

Adds a listener for the action clicked event. Returns an unsubscribe function.

onActionUserSettingsChanged [MV3]

onActionUserSettingsChanged(callback: (settings: chrome.action.UserSettings) => void): () => void

Adds a listener for user settings changes on the action (Manifest V3 only). Returns an unsubscribe function.