What are the differences between page action and browser action?

I made a browser action, but I just tried testing a page action. The button is put in the same place, but the page action button can't be clicked (the icon is greyed-out). I thought page action buttons were located on the address bar, not in the toolbar. Why is it located in the same place?

My browser action button:

My page action button:

Both Browser Action and Page Action buttons are located "to the right of the address bar", as described in the Extension API documentation. The two types of buttons have a lot of similarities. Which to use depends largely on if your extension is intended to be usable most of the time, or just on a small subset of pages.

Browser Action buttons are intended to be used when your extension can be used most of the time, or on most pages. They also allow you to provide some immediately visible status information to the user by having a badge containing a couple/few characters over the icon and changing the color of the background used for that badge.

Page Action buttons are intended for use when your extension is often/usually not available for use. For instance, if it's only usable on a few domains or URLs.

Browser action buttons

Browser action buttons should be used when your button is valid for use most of the time, either on most pages, or not related to/dependent upon the page that is being displayed in the active tab. By default, browser action buttons are enabled on all tabs/URLs. You have to call browserAction.disable() to disable the button in each tab where you want it disabled (or generally disabled on all tabs). The browser action button does not change enabled/disabled state when the tab displays a different URL.

Chrome's browser action button page says (some emphasis mine):

> Use browser actions to put icons in the main Google Chrome toolbar, to the right of the address bar. In addition to its icon, a browser action can also have a tooltip, a badge, and a popup.

>* Do use browser actions for features that make sense on most pages. >* Don't use browser actions for features that make sense for only a few pages. Use page actions instead. >* Do use big, colorful icons that make the most of the 16x16-dip space. Browser action icons should seem a little bigger and heavier than page action icons. >* Don't attempt to mimic Google Chrome's monochrome menu icon. That doesn't work well with themes, and anyway, extensions should stand out a little. >* Do use alpha transparency to add soft edges to your icon. Because many people use themes, your icon should look nice on a variety of background colors. >* Don't constantly animate your icon. That's just annoying.

Browser actions have the following APIs:

• Types
• ColorArray
• ImageDataType¹
• Methods
• disable − browserAction.disable(integer tabId)
• enable − browserAction.enable(integer tabId)
• getBadgeBackgroundColor − browserAction.getBadgeBackgroundColor(object details, function callback)
• getBadgeText − browserAction.getBadgeText(object details, function callback)
• getPopup¹ − browserAction.getPopup(object details, function callback)
• getTitle¹ − browserAction.getTitle(object details, function callback)
• setBadgeBackgroundColor − browserAction.setBadgeBackgroundColor(object details)
• setBadgeText − browserAction.setBadgeText(object details)
• setIcon¹ − browserAction.setIcon(object details, function callback)
• setPopup¹ − browserAction.setPopup(object details)
• setTitle¹ − browserAction.setTitle(object details)
• Events
• onClicked¹

Page action buttons

Page action buttons should be used when the ability to use of your extension's button is dependent on the URL being shown in the active tab and when it is usually not available for use (i.e. only usable under some conditions, or on some URLs). By default, page action buttons are disabled/grayed out ("hidden") on all URLs. You have to call pageAction.show() to enable the button for each URL/tab you want it enabled. The page action button automatically becomes disabled/hidden if the tab displays a different URL.

Chrome's page action button page says (some emphasis mine):

> Use the chrome.pageAction API to put icons in the main Google Chrome toolbar, to the right of the address bar. Page actions represent actions that can be taken on the current page, but that aren't applicable to all pages. Page actions appear grayed out when inactive.

> Like browser actions, page actions can have an icon, a tooltip, and popup; they can't have badges, however. In addition, page actions can be grayed out. You can find information about icons, tooltips, and popups by reading about the browser action UI.

>You make a page action appear and be grayed out using the pageAction.show and pageAction.hide methods, respectively. By default, a page action appears grayed out. When you show it, you specify the tab in which the icon should appear. The icon remains visible until the tab is closed or starts displaying a different URL (because the user clicks a link, for example).

>* Do use page actions for features that make sense for only a few pages. >* Don't use page actions for features that make sense for most pages. Use browser actions instead. >* Don't constantly animate your icon. That's just annoying.

Page actions have the following APIs:

• Types
• ImageDataType¹
• Methods
• getPopup¹ − pageAction.getPopup(object details, function callback)
• getTitle¹ − pageAction.getTitle(object details, function callback)
• hide − chrome.pageAction.hide(integer tabId)
• setIcon¹ − pageAction.setIcon(object details, function callback)
• setPopup¹ − pageAction.setPopup(object details)
• setTitle¹ − pageAction.setTitle(object details)
• show − pageAction.show(integer tabId)
• Events
• onClicked¹

---

^{1. This API is available for both browser actions and page actions. It does basically the same thing on both.}

Update January, 2022

In the latest Manifest Version 3, both browser_action and page_action are unified into a single action api.

Both browser_action and page_actions fulfilled similar roles, the main difference was page_actions were intended to be available only to selected tabs or urls.

Note that the new action api is similar to browser_action, but you can emulate the behaviour of page_action using the action api, i.e you can restrict the actions to specific sites.

This example from Chrome Extension documentation gives an idea about how you can enable action on specific sites:

// background.js

// Wrap in an onInstalled callback in order to avoid unnecessary work
// every time the background script is run
chrome.runtime.onInstalled.addListener(() => {
  // Page actions are disabled by default and enabled on select tabs
  chrome.action.disable();

  // Clear all rules to ensure only our expected rules are set
  chrome.declarativeContent.onPageChanged.removeRules(undefined, () => {
    // Declare a rule to enable the action on example.com pages
    let exampleRule = {
      conditions: [
        new chrome.declarativeContent.PageStateMatcher({
          pageUrl: {hostSuffix: '.example.com'},
        })
      ],
      actions: [new chrome.declarativeContent.ShowAction()],
    };

    // Finally, apply our new array of rules
    let rules = [exampleRule];
    chrome.declarativeContent.onPageChanged.addRules(rules);
  });
});