Use the browser.urlbar API to experiment with new features in the URLBar. Restricted to Mozilla privileged WebExtensions.

Permissions: urlbar

Not allowed in: Content scripts, Devtools pages

_UrlbarOnBehaviorRequestedEvent
_UrlbarOnEngagementEvent
_UrlbarOnQueryCanceledEvent
_UrlbarOnResultPickedEvent
_UrlbarOnResultsRequestedEvent
Query
Result
SearchOptions
EngagementState
ResultType
SourceType
engagementTelemetry
onBehaviorRequested
onEngagement
onQueryCanceled
onResultPicked
onResultsRequested
closeView
focus
search
EngagementState: "start" | "engagement" | "abandonment" | "discard"

The state of an engagement made with the urlbar by the user. start: The user has started an engagement. engagement: The user has completed an engagement by picking a result. abandonment: The user has abandoned their engagement, for example by blurring the urlbar. discard: The engagement ended in a way that should be ignored by listeners.

ResultType: "dynamic" | "remote_tab" | "search" | "tab" | "tip" | "url"

Possible types of results. dynamic: A result whose view and payload are specified by the extension. remote_tab: A synced tab from another device. search: A search suggestion from a search engine. tab: An open tab in the browser. tip: An actionable message to help the user with their query. url: A URL that's not one of the other types.

SourceType: "bookmarks" | "history" | "local" | "network" | "search" | "tabs"

Possible sources of results. bookmarks: The result comes from the user's bookmarks. history: The result comes from the user's history. local: The result comes from some local source not covered by another source type. network: The result comes from some network source not covered by another source type. search: The result comes from a search engine. tabs: The result is an open tab in the browser or a synced tab from another device.

engagementTelemetry: Setting

Enables or disables the engagement telemetry.

onBehaviorRequested: _UrlbarOnBehaviorRequestedEvent

Before a query starts, this event is fired for the given provider. Its purpose is to request the provider's behavior for the query. The listener should return a behavior in response. By default, providers are inactive, so if your provider should always be inactive, you don't need to listen for this event.

The query for which the behavior is requested.

The behavior of the provider for the query.

onEngagement: _UrlbarOnEngagementEvent

This event is fired when the user starts and ends an engagement with the urlbar.

The state of the engagement.

onQueryCanceled: _UrlbarOnQueryCanceledEvent

This event is fired for the given provider when a query is canceled. The listener should stop any ongoing fetch or creation of results and clean up its resources.

The query that was canceled.

onResultPicked: _UrlbarOnResultPickedEvent

Typically, a provider includes a url property in its results' payloads. When the user picks a result with a URL, Firefox automatically loads the URL. URLs don't make sense for every result type, however. When the user picks a result without a URL, this event is fired. The provider should take an appropriate action in response. Currently the only applicable ResultTypes are dynamic and tip.

The payload of the result that was picked.

If the result is a dynamic type, this is the name of the element in the result view that was picked. If the result is not a dynamic type, this is an empty string.

onResultsRequested: _UrlbarOnResultsRequestedEvent

When a query starts, this event is fired for the given provider if the provider is active for the query and there are no other providers that are restricting. Its purpose is to request the provider's results for the query. The listener should return a list of results in response.

The query for which results are requested.

The results that the provider fetched for the query.

  • Closes the urlbar view in the current window.

    Returns Promise<any>

  • Focuses the urlbar in the current window.

    Parameters

    • Optionalselect: boolean

      If true, the text in the urlbar will also be selected.

    Returns Promise<any>

  • Starts a search in the urlbar in the current window.

    Parameters

    • searchString: string

      The search string.

    • Optionaloptions: SearchOptions

      Options for the search.

    Returns Promise<any>