omnibox

Enables WebExtensions to implement customised behavior when the user types into the browser's address bar.

When the user focuses the browser's address bar and starts typing, the browser displays a drop-down list containing suggested pages, based on what they typed. This gives the user a quick way to access, for example, pages from their history or bookmarks.

The omnibox API gives WebExtensions a way to customise the suggestions displayed in the drop-down, when the user enters a keyword defined by the WebExtension. It works as follows:

  1. First, the WebExtension must include an "omnibox" key in its manifest.json file, which defines a keyword. Optionally, the WebExtension can also call omnibox.setDefaultSuggestion() to define the first suggestion that will be displayed in the address bar drop-down.
  2. When the user focuses the address bar and types the keyword, followed by a space, the WebExtension will get an omnibox.onInputStarted event.
  3. As the user continues to type characters after this, the WebExtension will get omnibox.onInputChanged events. The event listener will be passed the current value the user has typed, and will be able to populate the address bar drop-down with suggestions. If the WebExtension set a default suggestion using omnibox.setDefaultSuggestion(), then this will appear first in the drop-down.
  4. If the user accepts a suggestion, the WebExtension will get an omnibox.onInputEntered event. The event listener will be passed the accepted suggestion.
  5. If the user dismisses the drop-down, the WebExtension will get an omnibox.onInputCancelled event.

Types

omnibox.OnInputEnteredDisposition
Describes the recommended method to handle the selected suggestion: open in the current tab, open in a new foreground tab, or open in a new background tab.
omnibox.SuggestResult
Object representing a suggestion to add to the address bar drop-down.

Functions

omnibox.setDefaultSuggestion()
Defines the first suggestion that appears in the drop-down when the user enters the keyword for your WebExtension, followed by a space.

Events

omnibox.onInputStarted
Fired when a the user focuses the address bar and types your WebExtension's omnibox keyword, followed by a space.
omnibox.onInputChanged
Fired whenever the user's input changes, after they have focused the address bar and typed your WebExtension's omnibox keyword, followed by a space.
omnibox.onInputEntered
Fired when the user accepts one of your WebExtension's suggestions.
omnibox.onInputCancelled
Fired when the user dismisses the address bar drop-down, after they have focused the address bar and typed your WebExtension's omnibox keyword.

Browser compatibility

ChromeEdgeFirefoxFirefox for AndroidOpera
OnInputEnteredDispositionYesNo52.0NoYes
SuggestResultYesNo52.0 *NoYes
onInputCancelledYesNo52.0NoYes
onInputChangedYesNo52.0NoYes
onInputEnteredYesNo52.0NoYes
onInputStartedYesNo52.0NoYes
setDefaultSuggestionYesNo52.0 *NoYes

Example add-ons

Acknowledgements

This API is based on Chromium's chrome.omnibox API.

Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.

Document Tags and Contributors

 Contributors to this page: wbamberg
 Last updated by: wbamberg,