connect.action

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.

📷

Screenshot

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

drop the image at public/docs-img/extensions/action-badge.png

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

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

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.