Chrome API Exploration: Action API

Introduction

The Chrome Action API is a versatile tool for creating visually appealing and interactive elements within your extensions. In this blog post, we'll explore the key features of the Action API and provide practical examples to help you enhance your extension's user experience.

What is the Action API?

The Action API provides a way to control your extension's icon in the Chrome toolbar. There are 3 parts of your extension UI that relate to the Action API:

Icon - the icon that appears in the Chrome toolbar for your extension and is set by the action.default_icon property in your manifest.json file
Tooltip - the text that appears when hovering over the extension icon
Badge - the badge text that appears next to the extension icon (optional)
Popup - a popup that appears when the user clicks the extension icon and is defined by the action.default_popup property in your manifest.json file

You can view the full API reference here.

Relevant Permissions

There are no permissions required to use the Action API, however you will need to define the action property in your manifest.json file in order to use the API. A basic usage example can be seen below:

{
  "action": { 
    "default_popup": "popup.html",
    "default_icon": {
      "16": "icon16.png",
    }
  }
}

You will also need to ensure you're using Manifest V3, as the Action API is not supported in Manifest V2.

Essential functions

The Action API comes with a variety of functions that allow for manipulating the icon and it's corresponding actions that can be found in the API reference. Here are some of the most notable and highly used ones:

action.setIcon(): Sets the extension's icon, which can be a static image or a badge indicating the extension's status.
action.setPopup(): Specifies the popup HTML document that will be displayed when the user clicks on the icon.
action.setTitle(): Sets the title of the icon, which is displayed as a tooltip when the user hovers over it.
action.setBadgeText(): Sets the text that appears in the badge of the action. This is displayed on top of the icon.
action.getTitle(): Returns the title of the icon.
action.getBadgeText(): Returns the text of the badge.
action.getPopup(): Returns the popup HTML document set for the action.
action.openPopup(): Opens the popup for the extension.

Essential events

The Action API also comes with a few events:

action.onClicked: This event is triggered when the user clicks on the icon. This will not fire if the action has a popup set.
action.onUserSettingsChanged: This event is triggered when user-specific settings relating to the action are changed.

Examples

This can be done purely by adding to your manifest.json file, no additional code is required:

{
  "action": {
    "default_title": "Click to view a popup",
    "default_popup": "popup.html"
  }
}

This requires adding a small amount of JavaScript to your background script, as well as omitting the default_popup property from your manifest.json file:

{
  "action": {
    "default_title": "Click to view a popup"
  },
  "background": {
    "service_worker": "background.js"
  },
}

Then in your background background.js script you can open the popup with the following code:

chrome.action.onClicked.addListener(function () {
  chrome.action.openPopup();
});

Set the badge text

chrome.action.setBadgeText({ text: '10' });

You can also optionally set the badge text based on the tab by passing in the tabId property:

chrome.action.setBadgeText({ text: '10', tabId: 123 });

Relevant ExtensionKit resources

ExtensionKit makes use of the Action API in a number of different templates and example extensions, including:

Popup starter (basic) - a popup is displayed when the user clicks the extension icon
New tab starter (React) - a new tab page is created when the user clicks the extension icon
Popup full page & new tab starter (Vue) - a new tab page is created when the user clicks a button within the extension popup
And many more!