Toolbar buttons are one of the main UI components available to WebExtensions. Toolbar buttons live in the main browser toolbar and contain an icon. When the user clicks the icon, one of two things can happen:
- if you have specified a popup for the icon, the popup is shown. Popups are transient dialogs specified using HTML, CSS, and JavaScript.
- if you have not shown a popup, a click event is generated, that you can listen for in your code.
In WebExtensions these kinds of buttons are called "browser actions".
- the manifest.json key
browser_actionis used to define the button - the JavaScript API
browserActionis used to listen for clicks and to change the button from your code.
A simple button
In this section we'll create a WebExtension that adds a button to the toolbar. When the user clicks the button, we'll open https://developer.mozilla.org in a new tab.
First, create a new directory, "button", and create a file called manifest.json with the following contents:
{
"description": "Demonstrating toolbar buttons",
"manifest_version": 2,
"name": "button-demo",
"version": "1.0",
"background": {
"scripts": ["background.js"]
},
"browser_action": {
"default_icon": {
"16": "icons/page-16.png",
"32": "icons/page-32.png"
}
}
}
This specifies that we'll have a background script named "background.js", and a browser action whose icons will live in the "icons" directory.
So let's create the "icons" directory, and copy two icons there:
- "page-16.png" (
) - "page-32.png" (
).
Next, create "background.js" in the add-on's root directory, and give it the following contents:
function openPage() {
chrome.tabs.create({
url: "https://developer.mozilla.org"
});
}
chrome.browserAction.onClicked.addListener(openPage);
This just listens for the browser action's click event, and opens the page in the event listener, using the tabs API.
At this point the complete add-on should look like this:
button/
icons/
page-16.png
page-32.png
background.js
manifest.jsonNow install the WebExtension and click the button:
{{EmbedYouTube("kwwTowgT-Ys")}}
Adding a popup
Let's try adding a popup to the button. Replace manifest.json with this:
{
"description": "Demonstrating toolbar buttons",
"manifest_version": 2,
"name": "button-demo",
"version": "1.0",
"browser_action": {
"browser_style": true,
"default_popup": "popup/choose_page.html",
"default_icon": {
"16": "icons/page-16.png",
"32": "icons/page-32.png"
}
}
}
We've made three changes from the original:
- We've removed "background.js", because we're now handling the logic in the popup's script (you are allowed background.js as well as a popup, it's just that we don't need it in this case).
- We've added
"browser_style": true, which will help the styling of our popup look more like part of the browser. - Finally, we've added
"default_popup": "popup/choose_page.html", which is telling the browser that this browser action now wants a popup, the document for which it can find at "popup/choose_page.html".
So now create a directory called "popup" and in that directory, create a file called "choose_page.html". Give it the following contents:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<link rel="stylesheet" href="choose_page.css"/>
</head>
<body>
<div class="page-choice">developer.mozilla.org</div>
<div class="page-choice">support.mozilla.org</div>
<div class="page-choice">addons.mozilla.org</div>
<script src="choose_page.js"></script>
</body>
</html>
You can see that this is a normal HTML page, containing three div elements, each with the name of a Mozilla site. It also includes a CSS file and a JavaScript file, which we'll add next.
Create a file called "choose_page.css", and give it these contents:
html, body {
width: 300px;
}
.page-choice {
width: 100%;
padding: 4px;
font-size: 1.5em;
text-align: center;
cursor: pointer;
}
.page-choice:hover {
background-color: #CFF2F2;
}
This is just a bit of styling for our choices.
Next, create "choose_page.js", and give it these contents:
document.addEventListener("click", function(e) {
if (!e.target.classList.contains("page-choice")) {
return;
}
var chosenPage = "https://" + e.target.textContent;
chrome.tabs.create({
url: chosenPage
});
});
We listen for clicks on the choices, and open a new tab containing the corresponding page. Note that we can use the WebExtension APIs in the popup's script, just as we can in the background script.
Now the add-on should look like this:
button/
icons/
page-16.png
page-32.png
popup/
choose_page.css
choose_page.html
choose_page.js
manifest.json
Now reload the add-on, click the button again, and try clicking on the choices in the popup:
{{EmbedYouTube("QPEh1L1xq0Y")}}
Page actions
Page actions are just like browser actions, except that they are for actions which are relevant only for particular pages, rather than the browser as a whole.
While browser actions are always shown, page actions are only shown in tabs where they are relevant. Page action button are displayed in the URL bar, rather than the browser toolbar.
Learn more
browser_actionmanifest keybrowserActionAPI- Browser action examples:
page_actionmanifest keypageActionAPI- Page action examples: