Context menu items
This user interface option adds one or more items to a browser context menu. This is the menu available when a user right-clicks on a web page. Tabs and bookmarks can also have context menus, available through the menus API.
You use this option to expose features relevant to specific browser or web page contexts. For example, you can show features to open a graphic editor when the user clicks on an image or offer a feature to save page content when part of a page is selected. You can add plain menu items, checkbox items, radio button groups, and separators to menus. Once a context menu item has been added using menus.create it's displayed in all browser tabs, but you can hide it by removing it with menus.remove.
The full list of supported contexts is available at menus.ContextType and includes contexts outside of a web page, such as bookmark items in the browser UI. For example, the "Open bookmark in Container Tab" extension adds a menu item that allows the user to open a bookmark URL in a new container tab.
You can also override the context menus displayed in extension pages, such as custom sidebars and popups, to use either the tab or bookmark context menus instead of the default context menu, with menus.overrideContext. This is a helpful method when your extension provides a custom presentation of tabs or bookmarks. The menu automatically includes menu items for any other extensions that have defined tab or bookmark context menu items. You can choose whether to include the default context menu items. Hiding the default items gives the extension complete control over the items displayed in the rendered native context menu, as shown in the image below for the Tree Style Tab extension.
Specifying context menu items
You manage context menu items programmatically using the menus or contextMenus namespace. The namespace and permission to use depend on the browser:
- Use the
menusnamespace with themenuspermission in Firefox and Safari. - Use the
contextMenusnamespace with thecontextMenuspermission in browsers that support it.
In Firefox, contextMenus is an alias for menus. The examples in this guide use the menus namespace.
To use the API with the menus namespace, request the menus permission in your manifest.json file:
"permissions": ["menus"]
You can then add, update, or delete context menu items in your extension's background script. To create a menu item, specify an ID, a title, and the contexts in which it should appear:
browser.menus.create(
{
id: "log-selection",
title: browser.i18n.getMessage("contextMenuItemSelectionLogger"),
contexts: ["selection"],
},
onCreated,
);
Your extension can listen for clicks on menu items. The event provides information about the clicked item, the context in which the click occurred, and the tab where it took place. You can use this information to invoke the appropriate extension functionality.
browser.menus.onClicked.addListener((info, tab) => {
switch (info.menuItemId) {
case "log-selection":
console.log(info.selectionText);
break;
// …
}
});
Icons
For details on how to create icons to use with your context menu, see Iconography in the Acorn Design System documentation.
Examples
The webextensions-examples repository on GitHub contains two examples of extensions that implement context menu items:
- menu-demo adds several items to the browser's context menu.
- context-menu-copy-link-with-types adds a context menu item to links that copies the link URL to the clipboard, as plain text and rich HTML.