chrome.omnibox

The omnibox API allows you to register a keyword with Google Chrome's address bar, which is also known as the omnibox.

A screenshot showing suggestions related to the keyword 'Chromium Search'

When the user enters your extension's keyword, the user starts interacting solely with your extension. Each keystroke is sent to your extension, and you can provide suggestions in response.

The suggestions can be richly formatted in a variety of ways. When the user accepts a suggestion, your extension is notified and can take action.

Manifest

You must include an omnibox keyword field in the manifest to use the omnibox API. You should also specify a 16x16-pixel icon, which will be displayed in the address bar when suggesting that users enter keyword mode.

For example: 

{
  "name": "Aaron's omnibox extension",
  "version": "1.0",
  "omnibox": { "keyword" : "aaron" },
  "icons": {
    "16": "16-full-color.png"
  },
  "background": {
    "persistent": false,
    "scripts": ["background.js"]
  }
}

Note: Chrome automatically creates a grayscale version of your 16x16-pixel icon. You should provide a full-color version so that it can also be used in other situations that require color. For example, the context menus API also uses a 16x16-pixel icon, but it is displayed in color.

Examples

You can find samples of this API on the sample page.

chrome.omnibox reference

Types

SuggestResult

A suggest result.

properties of SuggestResult

content ( string )
The text that is put into the URL bar, and that is sent to the extension when the user chooses this entry.
description ( string )
The text that is displayed in the URL dropdown. Can contain XML-style markup for styling. The supported tags are 'url' (for a literal URL), 'match' (for highlighting text that matched what the user's query), and 'dim' (for dim helper text). The styles can be nested, eg. dimmed match.

Methods

setDefaultSuggestion

chrome.omnibox.setDefaultSuggestion(object suggestion)

Sets the description and styling for the default suggestion. The default suggestion is the text that is displayed in the first suggestion row underneath the URL bar.

Parameters

suggestion ( object )
A partial SuggestResult object, without the 'content' parameter. See SuggestResult for a description of the parameters.
description ( string )
The text to display in the default suggestion. The placeholder string '%s' can be included and will be replaced with the user's input.

Events

onInputStarted

chrome.omnibox.onInputStarted.addListener(function() {...});

User has started a keyword input session by typing the extension's keyword. This is guaranteed to be sent exactly once per input session, and before any onInputChanged events.

onInputChanged

chrome.omnibox.onInputChanged.addListener(function(string text, function suggest) {...});

User has changed what is typed into the omnibox.

Listener Parameters

text ( string )
suggest ( function )
A callback passed to the onInputChanged event used for sending suggestions back to the browser.

Callback

The suggest parameter should specify a function that looks like this: 

function(array of SuggestResult suggestResults) {...};
suggestResults ( array of SuggestResult )
Array of suggest results

onInputEntered

chrome.omnibox.onInputEntered.addListener(function(string text) {...});

User has accepted what is typed into the omnibox.

Listener Parameters

text ( string )

onInputCancelled

chrome.omnibox.onInputCancelled.addListener(function() {...});

User has ended the keyword input session without accepting the input.

Sample Extensions that use chrome.omnibox

  • Omnibox Example – To use, type 'omnix' plus a search term into the Omnibox.
  • Chromium Search – Add support to the omnibox to search the Chromium source code.