Adding search engines from web pages

Firefox allows JavaScript code to install search engine plugins, and supports two search engine plugin formats: OpenSearch, and Sherlock.

Note: Starting with Firefox 2, OpenSearch is the preferred search format for Firefox. Sherlock support will be removed in the future (bug 862137).

When JavaScript code attempts to install a search plugin, Firefox presents an alert asking the user for permission to install the plugin.

Installing OpenSearch plugins

To install an OpenSearch plugin, you need to use the window.external.AddSearchProvider() DOM method. The syntax for this method is:


Where engineURL is the absolute URL to the XML file for the search engine plugin.

Note: OpenSearch support is available only in Firefox 2 and later.

Installing Sherlock plugins

This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.

Support for window.sidebar.addSearchEngine was dropped in Firefox 44.

To install a Sherlock plugin, you need to call window.sidebar.addSearchEngine(), the syntax for which is:

window.sidebar.addSearchEngine(engineURL, iconURL, suggestedName, suggestedCategory);
  • The engineURL parameter is the URL to the Sherlock plugin (a ".src" file) to install.
  • iconURL is the URL to an icon to associate with the plugin.
  • The suggestedName parameter is only used when prompting the user for permission to install the plugin, so that a message such as "Do you want to install suggestedName from engineURL?" can be displayed.
  • The suggestedCategory parameter is not used. You should specify either an empty string ("") or null.

For details on Sherlock, visit

Browser search engine capability detection

Since the search engine addition APIs have changed between Firefox 1.5 and Firefox 2, and since Firefox 1.5 does not support OpenSearch description files, web page authors that want to add search engines in a backwards compatible way (i.e., that will work in Firefox 1.5, Firefox 2.0, or IE 7) must support both Sherlock and OpenSearch formats, and must detect the browser's capabilities accordingly. The following code snippet is an example of how this can be done:


function installSearchEngine() {
 if (window.external && ("AddSearchProvider" in window.external)) {
   // Firefox 2 and IE 7, OpenSearch
 } else if (window.sidebar && ("addSearchEngine" in window.sidebar)) {
   // Firefox <= 1.5, Sherlock
                                  "Search Plugin", "");
 } else {
   // No search engine support (IE 6, Opera, etc).
   alert("No search engine support");


© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.

Add-ons Search plugins