Chrome Action API Complete Reference

4 min read

Chrome Action API Reference

The chrome.action API controls the extension’s toolbar icon in Chrome. It replaces the deprecated chrome.browserAction API from Manifest V2.

Overview

MV3 replacement for chrome.browserAction (MV2)
Controls toolbar icon, badge, popup, and click behavior
Enable via manifest key: "action": { ... }
No permission required

Manifest Declaration

{
  "action": {
    "default_icon": { "16": "icon16.png", "32": "icon32.png" },
    "default_title": "My Extension",
    "default_popup": "popup.html"
  }
}

Without a popup, clicks fire onClicked.

Icon Methods

chrome.action.setIcon(details)

await chrome.action.setIcon({ path: "icon.png" });
await chrome.action.setIcon({ path: { "16": "16.png", "32": "32.png" }, tabId: 123 });

chrome.action.getIcon(details)

const icon = await chrome.action.getIcon({ tabId: 123 });

chrome.action.setTitle(details)

await chrome.action.setTitle({ title: "My Extension", tabId: 123 });

chrome.action.getTitle(details)

const title = await chrome.action.getTitle({ tabId: 123 });

Badge

chrome.action.setBadgeText(details)

await chrome.action.setBadgeText({ text: "5" });
await chrome.action.setBadgeText({ text: "" }); // Clear

chrome.action.getBadgeText(details)

const text = await chrome.action.getBadgeText({ tabId: 123 });

chrome.action.setBadgeBackgroundColor(details)

await chrome.action.setBadgeBackgroundColor({ color: [255, 0, 0, 255] });
await chrome.action.setBadgeBackgroundColor({ color: "#FF0000" });

chrome.action.getBadgeBackgroundColor(details)

const color = await chrome.action.getBadgeBackgroundColor({ tabId: 123 });

chrome.action.setBadgeTextColor(details) — Chrome 110+

await chrome.action.setBadgeTextColor({ color: "#FFF" });

chrome.action.getBadgeTextColor(details)

chrome.action.setPopup(details)

await chrome.action.setPopup({ popup: "popup.html" });
await chrome.action.setPopup({ popup: "" }); // Disable

chrome.action.getPopup(details)

const popup = await chrome.action.getPopup({ tabId: 123 });

chrome.action.openPopup() — Chrome 127+, user gesture required

await chrome.action.openPopup();

Enable/Disable

chrome.action.enable(tabId?)

await chrome.action.enable(123);

chrome.action.disable(tabId?)

await chrome.action.disable(123);

chrome.action.isEnabled(tabId?)

const isEnabled = await chrome.action.isEnabled(123);

Events

chrome.action.onClicked

Fires when icon clicked. Only when NO popup is set.

chrome.action.onClicked.addListener((tab) => {
  console.log("Clicked tab:", tab.id);
});

Per-Tab vs Global

All setters accept optional tabId for per-tab overrides. Values reset when tab navigates to new origin.

Code Examples

Badge: chrome.action.setBadgeText({ text: "5" }); chrome.action.setBadgeBackgroundColor({ color: [255, 0, 0, 255] });

Toggle icon: await chrome.action.setIcon({ path: isActive ? "on.png" : "off.png" });

Dynamic popup:

chrome.tabs.onActivated.addListener(async ({ tabId }) => {
  const tab = await chrome.tabs.get(tabId);
  await chrome.action.setPopup({ popup: tab.url?.startsWith("https://") ? "popup.html" : "", tabId });
});

onClicked:

chrome.action.onClicked.addListener(async (tab) => {
  await chrome.scripting.executeScript({ target: { tabId: tab.id }, func: () => console.toggle() });
});

Cross-References

MV3 Action API
Badge Action UI Pattern
Popup Patterns
Frequently Asked Questions

What is the chrome.action API?

chrome.action controls the extension’s toolbar icon in Chrome, replacing the deprecated browserAction API. It manages icons, badges, popups, and click handling.

Do I need a permission for chrome.action?

No, the action API doesn’t require any permissions. You configure it through the “action” key in manifest.json.

Can I change the icon dynamically?

Yes, use chrome.action.setIcon() to change icons programmatically based on extension state or tab context.

Part of the Chrome Extension Guide by theluckystrike. Built at zovo.one.

← Previous webRequestBlocking Next → alarms-api