omnibox

Enables extensions to implement customized 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 provides the extension a way to customize the suggestions displayed in the drop-down, when the user enters a keyword defined by the extension. It works as follows:

  1. First, the extension must include an "omnibox" key in its manifest.json file, which defines a keyword.
  2. When the user focuses the address bar and types the keyword followed by a space, the extension gets an omnibox.onInputStarted event.
  3. Optionally, the extension can call omnibox.setDefaultSuggestion() to define the first suggestion displayed in the address bar drop-down.
  4. As the user continues to type characters, the extension gets omnibox.onInputChanged events. The event listener is passed the value the user has typed and can populate the address bar drop-down with suggestions. If the extension sets a default suggestion using omnibox.setDefaultSuggestion(), this suggestion is displayed first in the drop-down.
  5. If the user accepts a suggestion, the extension gets an omnibox.onInputEntered event. The event listener is passed the accepted suggestion.
  6. If the user deletes a suggestion, the extension gets an omnibox.onDeleteSuggestion event.
  7. If the user dismisses the drop-down, the extension gets 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

An object representing a suggestion to add to the address bar drop-down.

Functions

omnibox.setDefaultSuggestion()

Defines the first suggestion displayed in the drop-down when the user enters your extension's keyword followed by a space.

Events

omnibox.onDeleteSuggestion

Fired whenever the user deletes a suggestion.

omnibox.onInputStarted

Fired when the user focuses the address bar and types your extension'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 extension's keyword followed by a space.

omnibox.onInputEntered

Fired when the user accepts one of your extension's suggestions.

omnibox.onInputCancelled

Fired when the user dismisses the address bar drop-down after they have focused the address bar and typed your extension's keyword followed by a space.

Example extensions

Browser compatibility

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Firefox for Android
Safari on iOS
omnibox
OnInputEnteredDisposition
SuggestResult
SuggestResult.content
SuggestResult.deletable
SuggestResult.description
onDeleteSuggestion
onInputCancelled
onInputChanged
onInputEntered
onInputStarted
setDefaultSuggestion

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
See implementation notes.

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