WittCode💻

Chrome Extension chrome.action API

By

Learn about the chrome extension chrome.action API. We will go over its manifest.json configuration and how to work with it programatically.

Table of Contents 📖

What is the chrome.action API?

The chrome.action API allows us to customize the behavior of an extension's icon in the toolbar. For example, changing what icon is displayed for the extension, changing the popup that appears when the extension's icon is clicked, disabling the extension icon on certain web pages, etc.

Image

Above, we can see (if you zoom in!) a docker compose icon, some red badge text, and a popup HTML saying WittCode is cool. This is what the chrome.action API allows us to build and what we will build here.

Configuring the chrome.action API

To use the chrome.action API, we need to specify the action key in manifest.json.

{
  "manifest_version": 3,
  "name": "Chrome Action API",
  "description": "chrome.action API demonstration.",
  "version": "1.0",
  "action": {}
}

The action key takes an object where each key is optional. One of these keys is default_icon.

"action": {
  "default_icon": {
    "16": "src/assets/dockerCompose.png",
    "24": "src/assets/dockerCompose.png",
    "32": "src/assets/dockerCompose.png"
  }
}

The default_icon key determines what icon is shown on the Chrome toolbar for the extension. Specifically, it takes an object where each key is a size in device-independent pixels (DIP) and each value is the image to display. Here, we are saying that for 16, 24, and 32 DIP set the extension image to the dockerCompose.png image located in src/assets. Out in production we would of course want to use different sized images for each of these DIPs. We can also set the tooltip of the extension with the default_title key.

"default_title": "My cool extension"

Now, hovering over the icon will display My cool extension. Finally, lets talk about creating a popup. A popup is what is displayed when the extension icon is clicked. It can be set with the default_popup property in manifest.json.

"default_popup": "src/index.html"

Now lets create this index.html file and place some simple HTML inside.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Document</title>
  </head>
  <body>
    <h1>WittCode is cool</h1>
  </body>
</html>

Now clicking on the extension icon will display the text WittCode is cool. Note that the popup is sized automatically to fit its contents. However, the popup cannot be any smaller than 25x25 px or larger than 800x600 px.

Working with chrome.action API Programatically

We can also work with the chrome.action API programatically using service workers. A chrome extension service worker is an extension's central event handler. They respond to events such as closing a tab, network calls, navigating to a new web page, etc. To work with service workers, we need to first specify the location of the script in manifest.json with the background and service_worker keys.

"background": {
  "service_worker": "src/background/index.js"
},

Now we can access the chrome.action API by using the chrome.action object.

chrome.action.setBadgeText({
  text: '1'
}, () => {
  console.log('The badge text has been set!')
});

chrome.action.setBadgeBackgroundColor({
  color: 'red'
}, () => {
  console.log('The badge background color has been set!')
})

Here we use the methods setBadgeText and setBadgeBackgroundColor to add the number 1 with a background color of red to the extension icon. The function passed as a second argument is a callback function. A badge is text that overlays the extension icon. They are useful for displaying things such as notifications. There are many other methods available on the chrome.action API. In fact all the configuration we placed inside manifest.json such as default_popup and default_title can be set programatically with the chrome.action API. Here is a list of them.

const keys = Object.keys(chrome.action);
console.log(...keys);
// onClicked disable enable getBadgeBackgroundColor getBadgeText getBadgeTextColor getPopup 
// getTitle getUserSettings isEnabled setBadgeBackgroundColor setBadgeText setBadgeTextColor 
// setIcon setPopup setTitle