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:
- First, the extension must include an "omnibox" key in its manifest.json file, which defines a keyword.
- When the user focuses the address bar and types the keyword followed by a space, the extension gets an
omnibox.onInputStarted
event. - Optionally, the extension can call
omnibox.setDefaultSuggestion()
to define the first suggestion displayed in the address bar drop-down. - 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 usingomnibox.setDefaultSuggestion()
, this suggestion is displayed first in the drop-down. - If the user accepts a suggestion, the extension gets an
omnibox.onInputEntered
event. The event listener is passed the accepted suggestion. - If the user deletes a suggestion, the extension gets an
omnibox.onDeleteSuggestion
event. - 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
BCD tables only load in the browser
Note: This API is based on Chromium's chrome.omnibox
API.