Welcome What's new in Chrome extensions Getting started API Reference Samples
Welcome What's new in Chrome extensions Getting started API Reference Samples

chrome.omnibox

  • Description

    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.

Summary

Types

DefaultSuggestResult

A suggest result.

Properties

  • 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.

SuggestResult

A suggest result.

Properties

  • content
    string

    The text that is put into the URL bar, and that is sent to the extension when the user chooses this entry.

  • deletable
    boolean optional

    Since Chrome 63.

    Whether the suggest result can be deleted by the user.

  • 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. You must escape the five predefined entities to display them as text: stackoverflow.com/a/1091953/89484

DescriptionStyleType

Since Chrome 44.

The style type.

Enum

"url", "match", or "dim"

OnInputEnteredDisposition

Since Chrome 44.

The window disposition for the omnibox query. This is the recommended context to display results. For example, if the omnibox command is to navigate to a certain URL, a disposition of 'newForegroundTab' means the navigation should take place in a new selected tab.

Enum

"currentTab", "newForegroundTab", or "newBackgroundTab"

Methods

setDefaultSuggestion

omnibox.setDefaultSuggestion(suggestion: DefaultSuggestResult)

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

Events

onDeleteSuggestion

omnibox.onDeleteSuggestion.addListener(listener: function)

Since Chrome 63.

User has deleted a suggested result.

Event

  • listener
    function

    The listener parameter should be a function that looks like this:

    (text: string) => {...}
    • text
      string

      Text of the deleted suggestion.

onInputCancelled

omnibox.onInputCancelled.addListener(listener: function)

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

Event

  • listener
    function

    The listener parameter should be a function that looks like this:

    () => {...}

onInputChanged

omnibox.onInputChanged.addListener(listener: function)

User has changed what is typed into the omnibox.

Event

  • listener
    function

    The listener parameter should be a function that looks like this:

    (text: string, suggest: function) => {...}
    • text
      string
    • suggest
      function

      The suggest function looks like this:

      suggest(suggestResults: SuggestResult[]) => {...}

onInputEntered

omnibox.onInputEntered.addListener(listener: function)

User has accepted what is typed into the omnibox.

Event

onInputStarted

omnibox.onInputStarted.addListener(listener: 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.

Event

  • listener
    function

    The listener parameter should be a function that looks like this:

    () => {...}
We serve cookies on this site to analyze traffic, remember your preferences, and optimize your experience.