Example extensions
To illustrate how to use the WebExtension APIs, we maintain a repository of example extensions at https://github.com/mdn/webextensions-examples. This article describes how to run these examples and lists the examples along with the WebExtension APIs they demonstrate.
These examples work in Firefox Nightly: most work in earlier versions of Firefox, but check the strict_min_version key in the extension's manifest.json to make sure.
Warning: Some examples work only on specific domains or pages. Details of any restrictions are provided in each example's readme file. None of the examples work in private browsing windows by default, see Extensions in Private Browsing for details.
To try these examples, clone the repository then:
- load the extension from its source folder using the Load Temporary Add-on feature. The extension stays loaded until you restart Firefox.
- open the extension's source folder at the command-line and use
web-ext
to run the extension. The extension stays loaded until you restart Firefox. - in Firefox use File > Open File and find the example in the
build
folder. Thebuild
folder contains built and signed versions of all the examples. This permanently installs the example.
Warning: Please do not submit these WebExtension examples to addons.mozilla.org (AMO); you do not have to sign the add-on WebExtension examples to run them. Follow the steps above.
If you want to contribute to the repository, send us a pull request.
Name | Description | JavaScript APIs |
---|---|---|
annotate-page | Displays a sidebar that lets you take notes on web pages. | storage.local tabs.onActivated tabs.onUpdated tabs.query tabs.Tab windows.getCurrent windows.Window |
apply-css | Adds a page action to the toolbar. Click the button to apply a red border using injected CSS. Click the button again to remove the CSS. | pageAction.getTitle pageAction.onClicked pageAction.setIcon pageAction.setTitle pageAction.show tabs.insertCSS tabs.onUpdated tabs.query tabs.removeCSS tabs.Tab |
beastify | Adds a browser action icon to the toolbar. Click the button to choose a beast. The active tab's body content is then replaced with a picture of the chosen beast. | extension.getURL runtime.onMessage tabs.executeScript tabs.insertCSS tabs.query tabs.removeCSS tabs.sendMessage tabs.Tab |
bookmark-it | Adds a bookmark button to the toolbar. Click the button to toggle a bookmark for the current page. | bookmarks.create bookmarks.onCreated bookmarks.onRemoved bookmarks.remove bookmarks.search browserAction.onClicked browserAction.setIcon browserAction.setTitle tabs.onActivated tabs.onUpdated tabs.query tabs.Tab windows.onFocusChanged |
borderify | Adds a solid red border to all webpages matching mozilla.org. | |
chill-out | Show a page action after a period of inactivity. Show cat gifs when the page action is clicked. | alarms.clearAll alarms.create alarms.onAlarm pageAction.hide pageAction.onClicked pageAction.show tabs.get tabs.onActivated tabs.onUpdated tabs.query tabs.update |
commands | Demonstrates using the commands API to set up a keyboard shortcut. The shortcut created is accessed using Ctrl+Shift+U (Command+Shift+U on a Mac). | commands.getAll commands.onCommand commands.reset commands.update tabs.create |
content-script-register | Illustrates how an extension can register URL-matching content scripts at runtime. | contentScripts.register runtime.onMessage runtime.sendMessage |
context-menu-copy-link-with-types | Add a context menu option to links to copy the link to the clipboard, as plain text and as a link in rich HTML. | contextMenus.create contextMenus.onClicked tabs.executeScript |
contextual-identities | List, create, and remove contextual identities. | contextualIdentities.query tabs.create tabs.query tabs.remove |
cookie-bg-picker | Allows the user to customize the background color and tiled pattern on sites they visit, and also saves their preferences via a cookie, reapplying them whenever they revisit a site they previously customized. | cookies.get cookies.onChanged cookies.remove cookies.set extension.getURL runtime.onMessage tabs.onActivated tabs.onUpdated tabs.query tabs.Tab tabs.sendMessage |
devtools-panels | Demonstrates some of the devtools APIs. | devtools.inspectedWindow devtools.panels runtime.getURL runtime.onMessage runtime.sendMessage tabs.executeScript |
discogs-search | Demonstrates adding a custom search engine with the chrome_settings_overrides key. | |
dnr-block-only | Demonstrates how to block network requests without host permissions using the declarativeNetRequest API with the `declarative_net_request` manifest key. | declarativeNetRequest.Rule declarativeNetRequest.RuleAction declarativeNetRequest.RuleCondition |
dnr-dynamic-with-options | Demonstrates a generic way to request host permissions and register declarativeNetRequest rules to modify network requests, without any install-time permission warnings. The options_ui page offers a way to request permissions and register DNR rules. | declarativeNetRequest.Rule declarativeNetRequest.getDynamicRules declarativeNetRequest.getSessionRules declarativeNetRequest.updateDynamicRules declarativeNetRequest.updateSessionRules permissions.getAll permissions.remove permissions.request |
dnr-redirect-url | Demonstrates multiple ways to redirect requests using the declarativeNetRequest API through the `declarative_net_request` manifest key. Demonstrates aspects of Manifest Version 3 (MV3): action, host_permissions, and web_accessible_resources, and includes a comparison with Manifest Version 2 (MV2). | declarativeNetRequest.Redirect declarativeNetRequest.Rule declarativeNetRequest.RuleAction declarativeNetRequest.RuleCondition declarativeNetRequest.URLTransform permissions.contains permissions.remove permissions.request |
dynamic-theme | Dynamic theme example | alarms.create alarms.onAlarm theme.update |
emoji-substitution | Replaces words with emojis. | |
eslint-example | Demonstrates how to configure an extension with eslint. | |
export-helpers | Demonstrates how to use export helpers like cloneInto to share objects with page scripts. | notifications.create runtime.onMessage runtime.sendMessage |
favourite-colour | An example options page, letting you store your favourite colour. | browserAction.onClicked runtime.openOptionsPage storage.managed storage.sync |
find-across-tabs | Demonstration of the find API. | browserAction.onClicked extension.getBackgroundPage find.find find.highlightResults runtime.getURL runtime.onMessage runtime.sendMessage tabs.create tabs.query tabs.Tab |
firefox-code-search | Demonstrates how to use the omnibox API. | omnibox.onInputChanged omnibox.onInputEntered omnibox.setDefaultSuggestion tabs.create tabs.update |
forget-it | Demonstrates how to use the browsingData API. | browserAction.onClicked browsingData.remove notifications.create storage.local |
google-userinfo | Demonstrates how to use the identity API. | browserAction.onClicked identity.getRedirectURL identity.launchWebAuthFlow notifications.create |
history-deleter | History API demo: deletes history items for a given domain | history.deleteUrl history.search pageAction.show tabs.onUpdated tabs.query |
http-response | Demonstrates how to rewrite HTTP responses using the webRequest.filterResponseData() API. | webRequest.filterResponseData webRequest.onBeforeRequest |
imagify | Using a sidebar, illustrates the use of file picker and drag and drop. A content script replaces the current page content with the chosen image. | extension.getURL runtime.onMessage tabs.executeScript tabs.query tabs.sendMessage |
latest-download | Shows the last downloaded item, and lets you open or delete it. | downloads.erase downloads.getFileIcon downloads.open downloads.removeFile downloads.search |
list-cookies | This extensions list the cookies in the active tab. | cookies.getAll tabs.query |
menu-accesskey-visible | Shows how to set up a single letter access key for a menu item. | i18n.getMessage menus.update menus.create menus.onClicked |
menu-demo | Demonstrates adding and manipulating menu items using the menus API. | i18n.getMessage menus.create menus.onClicked menus.remove menus.update runtime.lastError tabs.executeScript |
menu-labelled-open | Shows how an extension can listen for the display of a menu and then add, remove, or update its menu items. | menus.create menus.onClicked menus.onShown menus.refresh menus.update tabs.update |
menu-remove-element | Shows how to detect the page element at the cursor position and remove that element, or a parent element, from the page. This example includes use of the polyfill, illustrating cross-browser extension development. | menus.create menus.onClicked menus.getTargetElement pageAction.openPopup pageAction.show tabs.executeScript |
menu-search | Illustrates how to retrieve a list of search engines and issue a search request, using search engine details added to the context menu for selected text. | search.search search.get menus.create menus.onClicked |
mocha-client-tests | This example shows two methods of testing an extension: running tests from within the extension, and running tests from the command line using Karma. | runtime.onMessage runtime.sendMessage |
native-messaging | Example of native messaging, including a Python application and an extension which exchanges messages with it. | browserAction.onClicked runtime.connectNative |
navigation-stats | Demonstration of the webNavigation API, showing basic stats about which pages you've visited. | storage.local webNavigation.onCommitted webNavigation.onCompleted |
notify-link-clicks-i18n | Shows a localized notification when the user clicks on links. | extension.getURL i18n.getMessage notifications.create runtime.onMessage runtime.sendMessage |
open-my-page-button | Adds a browser action icon to the toolbar. When the browser action is clicked, the add-on opens a page that was packaged with it. | browserAction.onClicked tabs.create |
page-to-extension-messaging | Demonstrates how a web page and a content script can exchange messages. Visit https://mdn.github.io/webextensions-examples/content-script-page-script-messaging.html for the demo. | |
permissions | Demonstrates optional permissions using the permissions API. | browserAction.onClicked permissions.getAll permissions.remove permissions.request runtime.getURL tabs.create |
private-browsing-theme | Example dynamic theme: sets a dark theme for private windows. | theme.reset theme.update windows.getAll windows.onCreated |
proxy-blocker | Uses the proxy API to block requests to hosts specified on a list. | extension.getURL proxy.onRequest proxy.onError storage.local storage.onChanged |
quicknote | Allows the user to make quick notes by clicking a button and entering text into the resulting popup. The notes are saved in storage. | storage.local |
root-cert-stats | Shows how to get details about a request's TLS connection. | webRequest.getSecurityInfo |
runtime-examples | Demo of various runtime APIs. | browserAction.onClicked notifications.create runtime.getManifest runtime.onInstalled runtime.reload |
selection-to-clipboard | Demonstrates how to write to the clipboard from a content script | |
session-state | Demonstrates how to retrieve extension-defined state from restored tabs. | menus.create menus.onClicked sessions.getTabValue sessions.setTabValue tabs.insertCSS tabs.onCreated tabs.onUpdated tabs.query |
store-collected-images | Demonstrates how to use the idb-file-storage library to store and manipulate files in an extension. | browserAction.onClicked contextMenus.create contextMenus.onClicked runtime.onMessage runtime.sendMessage tabs.create windows.create |
stored-credentials | Performs basic authentication by supplying stored credentials. | storage.local webRequest.onAuthRequired webRequest.onCompleted webRequest.onErrorOccurred |
tabs-tabs-tabs | Demonstrates tab manipulation: opening, closing, moving, zooming tabs. | browserAction.setBadgeBackgroundColor browserAction.setBadgeText tabs.create tabs.duplicate tabs.getZoom tabs.move tabs.onCreated tabs.onMoved tabs.onRemoved tabs.query tabs.reload tabs.remove tabs.setZoom tabs.Tab tabs.update |
theme-integrated-sidebar | A sidebar that integrates with the current theme. | theme.getCurrent theme.onUpdated windows.getCurrent |
theme-switcher | An example of how to use the management API for themes. | management.getAll management.setEnabled |
themes | A collection of themes illustrating:
| |
top-sites | Demonstration of the topSites API. | topSites.get |
user-agent-rewriter | Demonstrates using the webRequest API to rewrite the User-Agent HTTP header. | extension.getBackgroundPage webRequest.onBeforeSendHeaders |
user-script-register | Illustrates how an extension can register URL-matching user scripts at runtime. | userScripts.register runtime.onMessage runtime.sendMessage |
webpack-modules | Demonstrates how to use webpack to package npm modules in an extension. | runtime.onMessage runtime.sendMessage |
window-manipulator | Demonstrates how to manipulate windows: opening, closing, resizing windows. | windows.create windows.getAll windows.getCurrent windows.remove windows.update windows.Window |
open-irc-links | Demonstrates the use of protocol handlers. |