pageActions vs browserActions

I have been working with WebExtensions for a while now and came across two action handlers for a browser add-on namely browserActions and pageActions. So I thought to clear out few dev-doubts in using these action handlers.

browserActions are the events that are performed when we click our add-on button from the add-on toolbar. when you click on the button in the toolbar a browserAction event is triggered. If a popup is defined in the manifest.json file then it is opened else you can listen to the event using ‘browserAction.onClicked’.(will discuss more on this)


Similarly pageActions are similar to browserActions but the only difference is they appear inside the url input box. basically you can define page actions on whatever tab you would like the button to be shown.


Firstly, If you are building an add-on and the action is applicable across all tabs on the browser( Eg: adblock ) then you should use browser actions but if your add-on works only on a particular website then you should use pageAction instead of a browserAction.

Using browserActions:

You have to do two things to include a browserAction in your add-on

  • Include the required info about browser actions in the manifest.json file.
"browser_action": {
  "browser_style": true,
  "default_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  "default_title": "Whereami?",
  "default_popup": "popup/geo.html"

browser_style is used if you want to include a css style for the browser action popup. You will have default_icon which gets displayed in the browser toolbar. default_title is the tooltip you will see when you hover over the icon in the toolbar and finally default_popup is the html of the popup that is displayed when the icon is cliked from the toolbar.

  • write the javascript code in your background.js file. more info about the API is here.

If you are not using any popup just like I did in my previous blogpost then you can listen to click event using ‘onClicked’ listener.


Using pageActions:

The declaration in manifest and listener is almost same for both page action and browser action except that you need to enable pageaction for a particular tab using

  • Add this to your manifest
"page_action": {
  "browser_style": true,
  "default_icon": {
    "19": "button/geo-19.png",
    "38": "button/geo-38.png"
  "default_title": "Whereami?",
  "default_popup": "popup/geo.html"
  • write the js code in your background.js file. more info on API is here.

first you need to show pageAction to a particular tab;

and then add an event listener to pageaction


I created my first add-on using browserAction here and pageAction here. You can have a look at it for reference/difference.

Happy Coding!


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s