ExtensionsAPI reference

connect.action

The toolbar button — badge, icon, title, enable/disable, and onClicked.

The toolbar button is your own surface, so the whole namespace needs no capability. Use it to show a badge, swap the icon, set the tooltip, enable/disable the button, and react to clicks.

  • Capability: none (your own surface)
  • Namespace: connect.action

Declare the button (and optionally its popup) in the manifest:

"ui": { "action": { "entry": "popup.html", "defaultTitle": "My Extension" } }

Omit entry for a popup-less button that fires action.onClicked instead.

The toolbar button with a badge. Capture the extension's toolbar action showing a badge count.
The toolbar button with a badge. Capture the extension's toolbar action showing a badge count.

Walkthrough

Show an unread count on the button.

  1. Declare the action in ui.action (no capability needed).
  2. Set the badge from your background as state changes:
    await connect.action.setBadgeText(String(unread || ''));
    await connect.action.setBadgeBackgroundColor('#16a34a');
  3. Clear it by setting ''.
  4. For a popup-less button, handle onClicked instead of declaring entry.

Methods

action.setBadgeText(text)

How to use it

  1. Pass a short string to show, or '' to hide the badge.

Signature — connect.action.setBadgeText(text | { text })

Parameters

ParameterTypeRequiredDescription
textstringyesThe badge label. '' hides the badge.

Returns — Promise<void>.

action.setBadgeBackgroundColor(color)

How to use it

  1. Pass a CSS color for the badge background.

Signature — connect.action.setBadgeBackgroundColor(color | { color }) · Returns Promise<void>.

action.getBadgeText() · action.getBadgeBackgroundColor()

Read the current badge text / color.

How to use it

  1. Call to read the current value (e.g. to toggle or increment).

Returns — Promise<string>.

action.setIcon(path)

Swap the button icon.

How to use it

  1. Pass an extension-relative asset path, or '' to revert to the manifest icon.

Signature — connect.action.setIcon(path | { path })

Parameters

ParameterTypeRequiredDescription
pathstringyesAn extension-relative asset. '' reverts to the manifest icon.

Returns — Promise<void>.

action.setTitle(title) · action.getTitle()

Tooltip override; '' reverts to the manifest defaultTitle.

How to use it

  1. setTitle(text) to override the tooltip; '' to revert. getTitle() reads it.

Signature — connect.action.setTitle(title | { title }) / action.getTitle()

Returns — Promise<void> / Promise<string>.

action.enable() · action.disable() · action.isEnabled()

Grey / ungrey the button.

How to use it

  1. disable() to grey it out (clicks ignored); enable() to restore; isEnabled() to read state.

Returns — Promise<void> / Promise<void> / Promise<boolean>.

action.openPopup()

Programmatically open the popup — or fire onClicked for a popup-less action.

How to use it

  1. Call it to open the popup from code (e.g. after a background event).

Returns — Promise<void>.

Events

action.onClicked(cb)

Fires when the button is clicked — only when the action declares no popup (ui.action without entry); a declared popup opens instead.

How to use it

  1. Omit entry in ui.action so the button has no popup.
  2. Subscribe to onClicked and do your thing (open a tab, toggle state).

Payload — none. Sticky, and wakes a suspended background.

connect.action.onClicked(() => connect.tabs.create('https://example.com'));

Notes

  • The badge/title/icon setters are live — call them from the background or popup as state changes.
  • For a popup that resizes with its content, see connect.ui → setPopupSize.