recursal/MDN huggingface dataset:
search.query()
==============

Perform a search using the browser's default search engine.

The results are displayed in the current tab, a new tab, or a new window according to the `disposition` property or in the tab specified in the `tabId` property. If neither is specified, the results display in the current tab.

To use this function, your extension must have the `"search"` manifest permission.

Syntax
------


```js
browser.search.query(
  queryInfo             // object
)
```

### Parameters

`queryInfo`

`object`. An object with the following properties:

`disposition` Optional

`string`. The location where the search results are displayed. Valid values are `CURRENT_TAB`, `NEW_TAB`, and `NEW_WINDOW`. Defaults to `CURRENT_TAB`. Cannot be specified with `tabId`.

`tabId` Optional

`integer`. An optional identifier for the tab you want to execute the search in. If this property is omitted, the search results are displayed in a new tab. Cannot be specified with `disposition`.

`text`

`string`. The search query.


### Return value

None.

Examples
--------

A search with the results shown in the current tab (default):


```js
function search() {
  browser.search.query({
    text: "styracosaurus",
  });
}

browser.browserAction.onClicked.addListener(search);
```


A search with the results shown in a new window:


```js
function search() {
  browser.search.query({
    text: "styracosaurus",
    disposition: "NEW\_WINDOW",
  });
}

browser.browserAction.onClicked.addListener(search);
```


A search with the results shown in a specific tab:


```js
function search(tab) {
  browser.search.query({
    query: "styracosaurus",
    tabId: tab.id,
  });
}

browser.browserAction.onClicked.addListener(search);
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
search.get()
============

Gets an array of all installed search engines.

Each search engine returned is identified with a name, which you can pass into `search.search()` to use that particular engine to make a search.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let gettingEngines = browser.search.get()
```

### Parameters

None.

### Return value

A `Promise` that will be fulfilled with an array of search engine objects. Each search engine object may contain the following properties:

`name`

`string`. The search engine's name.

`isDefault`

`boolean`. `true` if the search engine is the default. Only one search engine can be the default at any given time.

`alias` Optional

`string`. If a search engine has an alias, the user can search with a particular search engine by entering the alias in address bar before the search term. For example, if the Wikipedia engine has an alias "wk", the user can search Wikipedia for pandas by entering "wk pandas" in the address bar. The alias is sometimes also called a "keyword".

`favIconUrl` Optional

`string`. The search engine's icon, as a data: URL.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Get all installed search engines:


```js
function retrieved(results) {
  console.log(`There were: ${results.length} search engines retrieved.`);
  for (const searchEngine of results) {
    console.log(JSON.stringify(searchEngine.name));
  }
}

browser.search.get().then(retrieved);
```

### Example extensions

* menu-search
search.search()
===============

Perform a search using the search engine specified or the default search engine if no search engine is specified.

The results are displayed in the current tab, a new tab, or a new window according to the `disposition` property or in the tab specified in the `tabId` property. If neither is specified, the results display in a new tab.

To use this function, your extension must have the `"search"` manifest permission.

To get the installed search engines, use `search.get()`.

Syntax
------


```js
browser.search.search(
  searchProperties       // object
)
```

### Parameters

`searchProperties`

`object`. An object with the following properties:

`disposition` Optional

`string`. The location where the search results are displayed. Valid values are `CURRENT_TAB`, `NEW_TAB`, and `NEW_WINDOW`. Defaults to `NEW_TAB`. Cannot be specified with `tabId`.

`engine` Optional

`string`. The name of the search engine. If the search engine name doesn't exist, the function rejects the call with an error. If this property is omitted, the default search engine is used.

`query`

`string`. The search query.

`tabId` Optional

`integer`. An optional identifier for the tab you want to execute the search in. If this property is omitted, the search results are displayed in a new tab. Cannot be specified with `disposition`.


### Return value

None.

Examples
--------

A search using the default search engine with the results shown in the current tab (default):


```js
function search() {
  browser.search.search({
    query: "styracosaurus",
  });
}

browser.browserAction.onClicked.addListener(search);
```


A search using Wikipedia with the results shown in a new window:


```js
function search() {
  browser.search.search({
    query: "styracosaurus",
    engine: "Wikipedia (en)",
    disposition: "NEW\_WINDOW",
  });
}

browser.browserAction.onClicked.addListener(search);
```


A search using Wikipedia with the results shown in the current tab:


```js
function search(tab) {
  browser.search.search({
    query: "styracosaurus",
    engine: "Wikipedia (en)",
    tabId: tab.id,
  });
}

browser.browserAction.onClicked.addListener(search);
```

### Example extensions

* menu-search
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
menus.OnClickData
=================

Information passed to the `menus.onClicked` event listener when a menu item is clicked.

Type
----

Values of this type are objects. They contain the following properties:

`bookmarkId` Optional

`string`. The ID of the bookmark where the context menu was clicked.

`button` Optional

`integer`. Which mouse button was pressed. The values are the same as for `MouseEvent.button`.

`checked` Optional

`boolean`. A flag indicating whether a checkbox or radio item was checked after it was clicked.

`editable`

`boolean`. A flag indicating whether the element is editable: for example, if it is a textarea.

`frameId` Optional

`integer`. The ID of the frame in which the item was clicked. The frame ID can be used in other APIs that accept frame IDs, such as `tabs.sendMessage()`. If the item was clicked in the top level document, `frameId` is zero. If the item was clicked outside the page entirely (for example, in the `tools_menu` or `tab` context), then `frameId` is `undefined`.

`frameUrl` Optional

`string`. The URL of the frame of the element where the context menu was clicked, if it was in a frame.

`linkText` Optional

`string`. If the element is a link, the text for the link. If the link contains no text, the URL itself is given here.

`linkUrl` Optional

`string`. If the element is a link, the URL it points to.

`mediaType` Optional

`string`. One of "image", "video", or "audio" if the context menu was activated on one of these types of elements.

`menuItemId`

`integer` or `string`. The ID of the menu item that was clicked.

`modifiers`

`array` of `string`. An array containing any modifier keys that were pressed when the item was clicked. Possible values are: "Alt", "Command", "Ctrl", "MacCtrl", and "Shift". On a Mac, if the user has the Control key pressed, then both "Ctrl" and "MacCtrl" are included.

`pageUrl` Optional

`string`. The URL of the page in which the menu item was clicked. This property is not present if the click occurred in a context where there is no current page, such as on a browser action.

`parentMenuItemId` Optional

`integer` or `string`. The parent ID, if any, for the item clicked.

`selectionText` Optional

`string`. If some text was selected in the page, this contains the selected text.

`srcUrl` Optional

`string`. If present, the `src` value for the media in the clicked element.

`targetElementId` Optional

`integer`. An identifier of the element, if any, over which the context menu was created. Use `menus.getTargetElement()` in the content script to locate the element. Note that this is not the id attribute of the page element.

`viewType` Optional

`ViewType`. The type of extension view.

`wasChecked` Optional

`boolean`. A flag indicating whether a checkbox or radio item was checked before it was clicked.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.contextMenus` API. This documentation is derived from `context_menus.json` in the Chromium code.
menus.refresh()
===============

Refreshes a menu that's being shown.

Updates the extension's menu items in the menu that the browser is currently showing, including changes that have been made since the menu was shown. Has no effect if the menu is not being shown. Rebuilding a shown menu is an expensive operation, only invoke this method when necessary.

This would typically be called from inside a `menus.onShown` event handler, after the handler has made any updates to the menu.

Firefox makes this function available via the `contextMenus` namespace as well as the `menus` namespace.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
browser.menus.refresh()
```

### Parameters

None.

### Return value

A `Promise` that is fulfilled with no arguments.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

This example listens for the context menu to be shown over a link, then updates the `openLabelledId` menu item with the link's hostname:


```js
function updateMenuItem(linkHostname) {
  browser.menus.update(openLabelledId, {
    title: `Open (${linkHostname})`,
  });
  browser.menus.refresh();
}

browser.menus.onShown.addListener((info) => {
  if (!info.linkUrl) {
    return;
  }
  let linkElement = document.createElement("a");
  linkElement.href = info.linkUrl;
  updateMenuItem(linkElement.hostname);
});
```

### Example extensions

* menu-labelled-open
menus.ItemType
==============

The type of menu item.

Type
----

Values of this type are strings. Possible values are:

normal

A menu item that just displays a label.

checkbox

A menu item that represents a binary state. It displays a checkmark next to the label. Clicking the item toggles the checkmark. The `menus.onClicked` listener will be passed two extra properties: "checked", indicating whether the item is checked now, and "wasChecked", indicating whether the item was checked before the click event.

radio

A menu item that represents one of a group of choices. Just like a checkbox, this also displays a checkmark next to the label, and its `menus.onClicked` listener is passed "checked" and "wasChecked". However, if you create more than one radio item, then the items function as a group of radio items: only one item in the group can be checked, and clicking an item makes it the checked item.

separator

A line separating a group of items.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.contextMenus` API. This documentation is derived from `context_menus.json` in the Chromium code.
menus.remove()
==============

Removes a menu item.

For compatibility with other browsers, Firefox makes this method available via the `contextMenus` namespace as well as the `menus` namespace.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let removing = browser.menus.remove(
  menuItemId      // integer or string
)
```

### Parameters

`menuItemId`

`integer` or `string`. The ID of the menu item to remove.

### Return value

A `Promise` that will be fulfilled with no arguments if removal was successful, or rejected with an error message if removal failed (for example, because the item could not be found).

Examples
--------

This extension adds a menu item labeled "Remove me!". If you click the item, the extension removes it.


```js
function onRemoved() {
  console.log("item removed successfully");
}

function onError() {
  console.log("error removing item:", browser.runtime.lastError);
}

browser.menus.create({
  id: "remove-me",
  title: "Remove me!",
  contexts: ["all"],
});

browser.menus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === "remove-me") {
    let removing = browser.menus.remove(info.menuItemId);
    removing.then(onRemoved, onError);
  }
});
```

### Example extensions

* menu-demo
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.contextMenus` API. This documentation is derived from `context_menus.json` in the Chromium code.
menus.onHidden
==============

Fired when the browser stops displaying a menu: for example because the user clicked outside it or selected an item.

It is only triggered for menus that can be manipulated using the `menus` API itself: this includes the context menu, the browser's tools menu, and the bookmarks menu.

This is most likely to be used in combination with the `menus.onShown` and `menus.refresh()` APIs: an extension can update the menu when it is shown, then undo the changes when it is hidden.

Firefox makes this event available via the `contextMenus` namespace as well as the `menus` namespace.

Syntax
------


```js
browser.menus.onHidden.addListener(listener)
browser.menus.onHidden.removeListener(listener)
browser.menus.onHidden.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed no parameters.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

This example just logs a message whenever a menu is hidden:


```js
function hidden() {
  console.log("Menu was hidden");
}

browser.menus.onHidden.addListener(hidden);
```
menus.onClicked
===============

Fired when a menu item is clicked.

For compatibility with other browsers, Firefox makes this event available via the `contextMenus` namespace as well as the `menus` namespace.

Syntax
------


```js
browser.menus.onClicked.addListener(listener)
browser.menus.onClicked.removeListener(listener)
browser.menus.onClicked.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed these arguments:

`info`

`menus.OnClickData`. Information about the item clicked and the context where the click happened.

`tab`

`tabs.Tab`. The details of the tab where the click took place. If the click did not take place in or on a tab, this parameter will be missing.


Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

This example listens for clicks on a menu item, then log the item's ID and the tab ID:


```js
browser.menus.create({
  id: "click-me",
  title: "Click me!",
  contexts: ["all"],
});

browser.menus.onClicked.addListener((info, tab) => {
  console.log(`Item ${info.menuItemId} clicked in tab ${tab.id}`);
});
```

### Example extensions

* menu-accesskey-visible
* menu-demo
* menu-labelled-open
* menu-remove-element
* menu-search
* session-state

**Note:** This API is based on Chromium's `chrome.contextMenus` API. This documentation is derived from `context_menus.json` in the Chromium code.
menus.ACTION\_MENU\_TOP\_LEVEL\_LIMIT
=====================================

The maximum number of top level extension items that can be added to a menu item whose `ContextType` is "browser\_action" or "page\_action". Any items beyond this limit will be ignored.

Its value is `6` on Firefox and Chrome.

For compatibility with other browsers, Firefox makes this property available via the `contextMenus` namespace as well as the `menus` namespace.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.contextMenus` API. This documentation is derived from `context_menus.json` in the Chromium code.
menus.overrideContext()
=======================

Hide all default Firefox menu items in favor of providing a custom context menu UI.

The overrideContext method will cause the matching menu items from this extension to be shown instead of the default menu. This method should be called from a `contextmenu` DOM event handler, and only applies to the menu that opens after this event.

This interface requires the `menus.overrideContext` permission.

Syntax
------


```js
browser.menus.overrideContext(
  contextOptions // object
)
```

### Parameters

`contextOptions`

`object`. Options for how the context menus will be overridden.

`showDefaults` Optional

`boolean`. Whether to also include default menu items in the menu.

`context` Optional

`string`. ContextType to override, to allow menu items from other extensions in the menu. Currently only `'bookmark'` and `'tab'` are supported. `showDefaults` cannot be used with this option.

`bookmarkId` Optional

`string`. Required when context is `'bookmark'`. Requires 'bookmark' permission.

`tabId` Optional

`integer`. Required when context is `'tab'`. Requires 'tabs' permission.


Examples
--------

Open the tab context menu on your custom UI, in this case:


```js
document.addEventListener(
  "contextmenu",
  (event) => {
    const foo = event.target.closest(".foo");
    if (foo) {
      // When the context menu is opened on an element with the foo class
      // set the context to "opening a tab context menu".
      browser.menus.overrideContext({
        context: "tab",
        tabId: parseInt(foo.dataset.tabId),
      });
    }
  },
  { capture: true },
);
```


See this blog post for more details.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
menus.ContextType
=================

The different contexts a menu item can appear in.

Type
----

Values of this type are strings. The item is displayed when the given context applies. Possible values are:

all

Specifying 'all' is equivalent to the combination of all other contexts except for 'bookmark', 'tab' and 'tools\_menu'.

action

Applies when the user context-clicks your browser action in a Manifest V3 extension. The maximum number of items that can be added to the top-level browser action context menu is `menus.ACTION_MENU_TOP_LEVEL_LIMIT`, but you can add any number of items to submenus.

audio

Applies when the user context-clicks an audio element.

bookmark

Applies when the user context-clicks a bookmark item in the bookmarks toolbar, bookmarks menu, bookmarks sidebar (`Ctrl`+`B`) and the Library window (`Ctrl`+`Shift`+`B`). The latter two are supported as of Firefox 66. Requires the "bookmarks" API permission in the manifest.

browser\_action

Applies when the user context-clicks your browser action in a Manifest V2 extension. The maximum number of items that can be added to the top-level browser action context menu is `menus.ACTION_MENU_TOP_LEVEL_LIMIT`, but you can add any number of items to submenus.

editable

Applies when the user context-clicks an editable element, like a textarea.

frame

Applies when the user context-clicks in a nested iframe.

image

Applies when the user context-clicks an image.

link

Applies when the user context-clicks on a link.

page

Applies when the user context-clicks in the page, but none of the other page contexts apply (for example, the click is not on an image or a nested iframe or a link).

page\_action

Applies when the user context-clicks your page action. The maximum number of items that can be added to the top-level page action context menu is `menus.ACTION_MENU_TOP_LEVEL_LIMIT`, but you can add any number of items to submenus.

password

Applies when the user context-clicks on a password input element.

selection

Applies when part of the page is selected.

tab

Applies when the user context-clicks on a tab (specifically, this refers to the tab-strip or other user interface element enabling the user to switch from one browser tab to another, not to the page itself).

From Firefox 63, clicking the menu item on a tab grants the activeTab permission for the tab clicked, even if that isn't the currently active tab.

tools\_menu

The item will be added to the browser's tools menu. Note that this is only available if you access `ContextType` through the `menus` namespace. It is not available if you access it through the `contextMenus` namespace.

video

Applies when the user context-clicks a video element.

Note that "launcher" is not supported.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.contextMenus` API. This documentation is derived from `context_menus.json` in the Chromium code.
menus.getTargetElement()
========================

Returns the element for a given `targetElementId`

This method is available to all extension script contexts (content scripts, background pages and other extension pages) and returns the element for a given `info.targetElementId`, provided that the element still exists in the document where the method is invoked.

The method only works in the document that includes the right-clicked element and the `targetElementId` expires when the user opens another context menu.

**Note:** `menus.getTargetElement` only return the requested element if called in the same context as the document that contains the element, for example using content scripts (as shown in the example below).

An extension requires the "menus" permission to use this API.

Syntax
------


```js
let elem = browser.menus.getTargetElement(targetElementId);
```

### Parameters

`targetElementId`

The property of the ``menus.OnClickData`` object passed to the ``menus.onClicked`` handler or ``menus.onShown`` event.

### Return value

The element referred to by the `targetElementId` parameter. If the `targetElementId` parameter is not valid, the method returns `null`.

Examples
--------

The following example uses the `getTargetElement` method to get the element referred to by the `info.targetElementId` property and then removes it.


```js
browser.menus.create({
  title: "Remove element",
  documentUrlPatterns: ["\*://\*/\*"],
  contexts: [
    "audio",
    "editable",
    "frame",
    "image",
    "link",
    "page",
    "password",
    "video",
  ],
  onclick(info, tab) {
    browser.tabs.executeScript(tab.id, {
      frameId: info.frameId,
      code: `browser.menus.getTargetElement(${info.targetElementId}).remove();`,
    });
  },
});
```

### Example extensions

* menu-remove-element
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `menus.create`
* `menus.OnClickData`