recursal/MDN huggingface dataset:
contextualIdentities.create()
=============================

Creates a new contextual identity. Once created, the user will be able to create new tabs belonging to this contextual identity, just as they can with the built-in identities.

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

Syntax
------


```js
let createContext = browser.contextualIdentities.create(
  details                  // object
)
```

### Parameters

`details`

`object`. An object containing properties for the new contextual identity. This contains the following properties:

`name`

`string`. The name of the new identity. This will be displayed in the browser's UI, enabling them to open a new tab belonging to the identity. It will also be displayed in the URL bar for tabs belonging to this identity.

`color`

`string`. The color associated with the new identity. This will be used to highlight tabs belonging to this identity. You can supply any of the following values here:

* "blue"
* "turquoise"
* "green"
* "yellow"
* "orange"
* "red"
* "pink"
* "purple"
* "toolbar"

`icon`

`string`. The name of an icon to display in the URL bar for tabs belonging to this identity. You can supply any of the following values here:

* "fingerprint"
* "briefcase"
* "dollar"
* "cart"
* "circle"
* "gift"
* "vacation"
* "food"
* "fruit"
* "pet"
* "tree"
* "chill"
* "fence"


### Return value

A `Promise` that will be fulfilled with a `ContextualIdentity` that describes the new identity. If the contextual identities feature is not enabled, the promise is rejected.

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

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

Examples
--------

This example creates a new contextual identity and logs its cookie store ID:


```js
function onCreated(context) {
  console.log(`New identity's ID: ${context.cookieStoreId}.`);
}

function onError(e) {
  console.error(e);
}

browser.contextualIdentities
  .create({
    name: "my-thing",
    color: "purple",
    icon: "briefcase",
  })
  .then(onCreated, onError);
```
contextualIdentities.onRemoved
==============================

Fired when a new contextual identity is removed. Contextual identities may be removed by extensions using the `contextualIdentities` API, or directly by the user, using the browser's user interface.

Syntax
------


```js
browser.contextualIdentities.onRemoved.addListener(listener)
browser.contextualIdentities.onRemoved.removeListener(listener)
browser.contextualIdentities.onRemoved.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 this argument:

`changeInfo`

`object`. An object that contains a single property, `contextualIdentity`, which is a `contextualIdentities.ContextualIdentity` object representing the identity that was removed.


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

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

Examples
--------


```js
function handleRemoved(changeInfo) {
  console.log(`Removed: ${changeInfo.contextualIdentity.name}`);
}

browser.contextualIdentities.onRemoved.addListener(handleRemoved);
```
contextualIdentities.remove()
=============================

Removes a contextual identity, given its cookie store ID.

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

Syntax
------


```js
let removeContext = browser.contextualIdentities.remove(
  cookieStoreId                  // string
)
```

### Parameters

`cookieStoreId`

`string`. The ID of the contextual identity's cookie store. Because contextual identities each have their own cookie store, this serves as an identifier for the contextual identity itself.

### Return value

A `Promise` that will be fulfilled with a `ContextualIdentity` that describes the identity that was removed. If the identity could not be found or the contextual identities feature is not enabled, the promise is rejected.

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

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

Examples
--------

This example tries to remove the contextual identity whose ID is "firefox-container-1":


```js
function onRemoved(context) {
  if (!context) {
    console.error("Context not found");
  } else {
    console.log(`Removed identity: ${context.cookieStoreId}.`);
  }
}

function onError(e) {
  console.error(e);
}

browser.contextualIdentities
  .remove("firefox-container-1")
  .then(onRemoved, onError);
```
contextualIdentities.query()
============================

Gets information about all contextual identities, or about those contextual identities that match a given filter argument.

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

Syntax
------


```js
let getContext = browser.contextualIdentities.query(
  details                  // object
)
```

### Parameters

`details`

`object`. An object that can be used to filter the contextual identities returned. This may contain any of the following properties:

`name` Optional

`string`. Return only contextual identities with this name.


### Return value

A `Promise` that will be fulfilled with an array of `ContextualIdentity` objects, each describing a single identity. If the contextual identities feature is not enabled, the promise is rejected.

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

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

Examples
--------

Retrieve all contextual identities, and log their names:


```js
function onGot(contexts) {
  for (const context of contexts) {
    console.log(`Name: ${context.name}`);
  }
}

function onError(error) {
  console.error(error);
}

browser.contextualIdentities.query({}).then(onGot, onError);
```


Retrieve all contextual identities whose names are "my-thing", and log their names:


```js
function onGot(contexts) {
  for (const context of contexts) {
    console.log(`Name: ${context.name}`);
  }
}

function onError(error) {
  console.error(error);
}

browser.contextualIdentities
  .query({
    name: "my-thing",
  })
  .then(onGot, onError);
```

### Example extensions

* contextual-identities
contextualIdentities.update()
=============================

Updates properties of a contextual identity, given its cookie store ID.

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

Syntax
------


```js
let createContext = browser.contextualIdentities.update(
  cookieStoreId,           // string
  details                  // object
)
```

### Parameters

`cookieStoreId`

`string`. The ID of this contextual identity's cookie store. Because contextual identities each have their own cookie store, this serves as an identifier for the contextual identity itself.

`details`

`object`. An object containing new values for the properties that you wish to change. This may contain any of the following properties:

`name` Optional

`string`. A new name for the identity. This will be displayed in the browser's UI, enabling them to open a new tab in the identity. It will also be displayed in the URL bar for tabs belonging to this identity.

`color` Optional

`string`. A new color for the identity. This will be used to highlight tabs belonging to this identity. You can supply any of the following values here:

* "blue"
* "turquoise"
* "green"
* "yellow"
* "orange"
* "red"
* "pink"
* "purple"
* "toolbar"

`icon` Optional

`string`. A new icon for the identity. You can supply any of the following values here:

* "fingerprint"
* "briefcase"
* "dollar"
* "cart"
* "circle"
* "gift"
* "vacation"
* "food"
* "fruit"
* "pet"
* "tree"
* "chill"
* "fence"


### Return value

A `Promise` that will be fulfilled with a `ContextualIdentity` that describes the updated identity. If the identity could not be found or the contextual identities feature is not enabled, the promise is rejected.

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

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

Examples
--------

This example updates the contextual identity whose ID is "firefox-container-1" to have a new name, color, and icon:


```js
function onUpdated(context) {
  console.log(`New identity's name: ${context.name}.`);
}

function onError(e) {
  console.error(e);
}

browser.contextualIdentities
  .update("firefox-container-1", {
    name: "my-thing",
    color: "purple",
    icon: "briefcase",
  })
  .then(onUpdated, onError);
```
contextualIdentities.onCreated
==============================

Fired when a new contextual identity is created. Contextual identities may be created by extensions using the `contextualIdentities` API, or directly by the user, using the browser's user interface.

Syntax
------


```js
browser.contextualIdentities.onCreated.addListener(listener)
browser.contextualIdentities.onCreated.removeListener(listener)
browser.contextualIdentities.onCreated.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 this argument:

`changeInfo`

`object`. An object that contains a single property, `contextualIdentity`, which is a `contextualIdentities.ContextualIdentity` object, representing the identity that was created.


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

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

Examples
--------


```js
function handleCreated(changeInfo) {
  console.log(`Created: ${changeInfo.contextualIdentity.name}`);
}

browser.contextualIdentities.onCreated.addListener(handleCreated);
```
contextualIdentities.ContextualIdentity
=======================================

The **`contextualIdentities.ContextualIdentity`** type describes a single contextual identity.

Type
----

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

`cookieStoreId`

`string`. The cookie store ID for the identity. Since contextual identities don't share cookie stores, this serves as a unique identifier.

`color`

`string`. The color for the identity. This will be shown in tabs belonging to this identity. The following values are valid:

* "blue"
* "turquoise"
* "green"
* "yellow"
* "orange"
* "red"
* "pink"
* "purple"
* "toolbar"

The value "toolbar" represents a theme-dependent color. Identities with color "toolbar" will be displayed in the same color as text in the toolbar (corresponding to the theme key `"toolbar_field_text"`).

`colorCode`

`string`. A hex code representing the exact color used for the identity. For example: `"#37adff"`. In the special case of the "toolbar" color, `colorCode` is always `"#7c7c7d"`, regardless of the displayed color.

`icon`

`string`. The name of an icon for the identity. This will be shown in the URL bar for tabs belonging to this identity. The following values are valid:

* "fingerprint"
* "briefcase"
* "dollar"
* "cart"
* "circle"
* "gift"
* "vacation"
* "food"
* "fruit"
* "pet"
* "tree"
* "chill"
* "fence"

`iconUrl`

`string`. A full resource:// URL pointing to the identity's icon. For example: "resource://usercontext-content/fingerprint.svg".

`name`

`string`. Name of the identity. This will be shown in the URL bar for tabs belonging to this identity. Note that names don't have to be unique.

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

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

Moves one or more contextual identities to a new position within the list of contextual identities.

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

Syntax
------


```js
let moveContainers = browser.contextualIdentities.move(
  cookieStoreIds,                  // string or array of string
  position                         // integer
)
```

### Parameters

`cookieStoreIds`

`string` or `array` of `string`. An ordered list of the contextual identity cookie store IDs to move.

`position`

`integer`. The position to move `cookieStoreIds` to in the list of contextual identities. Zero-based; `0` indicates the first position. `-1` indicates that the items are moved to the end of the list.

### Return value

A `Promise` that is fulfilled when the contextual identities are reordered. The promise is rejected if the request is for an invalid move or the contextual identities feature is not enabled.

Examples
--------

This example moves the first identity to the end and then back to the start.


```js
let identities = await browser.contextualIdentities.query({});
let firstId = identities[0].cookieStoreId;

// Moves first identity to the end.
await browser.contextualIdentities.move(firstId, -1);

// Move identity to the start again.
await browser.contextualIdentities.move(firstId, 0);
```


Another way of moving the first identity to the end is by moving all other identities to the start.


```js
let identities = await browser.contextualIdentities.query({});
let ids = identities.map((identity) => identity.cookieStoreId);
// Create an array without the first item:
let otherIds = ids.slice(1);

// Move other identities to the start,
// effectively putting the first identity at the end.
await browser.contextualIdentities.move(otherIds, 0);
```


This example moves the "Personal" identity to before "Work". The example assumes containers with these names to exist. This may not be the case in customized or localized (non-English) Firefox instances.


```js
let identities = await browser.contextualIdentities.query({});

// Find the index and ID of the container with the name "Personal".
let personalIndex = identities.findIndex((ci) => ci.name === "Personal");
if (personalIndex === -1) {
  throw new Error("Personal container not found");
}
let personalId = identities[personalIndex].cookieStoreId;

// Find the index of the container with the name "Work".
let workIndex = identities.findIndex((identity) => identity.name === "Work");
if (workIndex === -1) {
  throw new Error("Work container not found!");
}

if (personalIndex < workIndex) {
  // When the Personal identity moves, all following
  // identities shift to the left by one. To place
  // the Personal identity before the Work identity,
  // we should therefore subtract one.
  workIndex--;
}
await browser.contextualIdentities.move(personalId, workIndex);
```

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

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

Resolves the given hostname to a DNS record.

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

Syntax
------


```js
let resolving = browser.dns.resolve(
  hostname,    // string
  flags        // array of string
)
```

### Parameters

`hostname`

`string`. The hostname to resolve.

`flags` Optional

`array` of `string`. Flags to modify the way the hostname is resolved. Any omitted flags default to `false`. You can pass zero or more of the following flags:

* `"allow_name_collisions"`: Allow name collision results which are normally filtered out.
* `"bypass_cache"`: Suppresses the internal DNS lookup cache.
* `"canonical_name"`: The canonical name of the specified host will be queried.
* `"disable_ipv4"`: Only IPv6 addresses will be returned.
* `"disable_ipv6"`: Only IPv4 addresses will be returned.
* `"disable_trr"`: Do not use the Trusted Recursive Resolver (TRR) for resolving the host name. A TRR enables resolving of host names using a dedicated DNS-over-HTTPS server.
* `"offline"`: Only literals and cached entries will be returned.
* `"priority_low"`: The request is given lower priority. If "priority\_medium" is also given, the query is given medium priority.
* `"priority_medium"`: The request is given medium priority. If "priority\_low" is also given, the query is given medium priority.
* `"speculate"`: Indicates that the request is speculative. Speculative requests return errors if prefetching is disabled by the browser's configuration.

### Return value

A `Promise` that will be fulfilled with a `DNSRecord` object. This object can contain the following properties:

`addresses`

`array` of `string`. The IP addresses associated with this DNS record.

`canonicalName`

`string`. The canonical name for this record. This is only included in the response if the `"canonical_name"` flag was passed to `resolve()`.

`isTRR`

`boolean`: `true` if the record was retrieved using a Trusted Recursive Resolver (TRR).

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

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

Examples
--------


```js
function resolved(record) {
  console.log(record.addresses);
}

let resolving = browser.dns.resolve("example.com");
resolving.then(resolved);

// > e.g. Array [ "192.0.2.172" ]
```


Bypass the cache, and ask for the canonical name:


```js
function resolved(record) {
  console.log(record.canonicalName);
  console.log(record.addresses);
}

let resolving = browser.dns.resolve("developer.mozilla.org", [
  "bypass\_cache",
  "canonical\_name",
]);
resolving.then(resolved);

// > e.g. xyz.us-west-2.elb.amazonaws.com
// > e.g. Array [ "192.0.2.172", "198.51.100.45" ]
```
i18n.detectLanguage()
=====================

Detects the language of the provided text using the Compact Language Detector (CLD).

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

See the Internationalization page for a guide on using this function.

Syntax
------


```js
let detectingLanguages = browser.i18n.detectLanguage(
  text                  // string
)
```

### Parameters

`text`

`string`. User input string to be translated.

### Return value

A `Promise` that will be fulfilled with a result object. The result object has two properties:

`isReliable`

`boolean`. Whether the language was detected reliably.

`languages`

`array` of objects, each of which has two properties:

`language`

`i18n.LanguageCode`. The detected language.

`percentage`

`integer`. The percentage of the input string that was in the detected language.


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

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

Examples
--------


```js
function onLanguageDetected(langInfo) {
  for (const lang of langInfo.languages) {
    console.log(`Language is: ${lang.language}`);
    console.log(`Percentage is: ${lang.percentage}`);
  }
}

let text = "L'homme est né libre, et partout il est dans les fers.";

let detecting = browser.i18n.detectLanguage(text);
detecting.then(onLanguageDetected);
```


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

Gets the localized string for the specified message.

See the Internationalization page for a guide on using this function.

Syntax
------


```js
browser.i18n.getMessage(
  messageName,  // string
  substitutions // optional any
)
```

### Parameters

`messageName`

`string`. The name of the message, as specified in the messages.json file. If the message can't be found in messages.json:

* Firefox returns "" and logs an error.
* Chrome returns "" and does not log an error.

`substitutions` Optional

`string` or `array` of `string`. A single substitution string, or an array of substitution strings.

In Chrome, if you supply more than 9 substitution strings, `getMessage()` will return `undefined`.

### Return value

`string`. Message localized for current locale.

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

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

Examples
--------

Get the localized string for `"messageContent"`, with `target.url` substituted:


```js
let message = browser.i18n.getMessage("messageContent", target.url);
console.log(message);
```


This would work with a \_locales/en/messages.json file containing:


```json
{
  "messageContent": {
    "message": "You clicked $URL$.",
    "description": "Tells the user which link they clicked.",
    "placeholders": {
      "url": {
        "content": "$1",
        "example": "https://developer.mozilla.org"
      }
    }
  }
}
```


If `target.url` is "https://developer.mozilla.org", then the value of message, in the "en" locale, would be:
```

"You clicked https://developer.mozilla.org."
```

### Example extensions

* menu-accesskey-visible
* menu-demo
* notify-link-clicks-i18n

**Note:** This API is based on Chromium's `chrome.i18n` API. This documentation is derived from `i18n.json` in the Chromium code.
i18n.LanguageCode
=================

A language tag such as `"en-US"` or "`fr`".

Type
----

Values of this type are strings.

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.i18n` API. This documentation is derived from `i18n.json` in the Chromium code.
i18n.getUILanguage()
====================

Gets the UI language of the browser. This is different from `i18n.getAcceptLanguages` which returns the preferred user languages.

See the Internationalization page for a guide on using this function.

Syntax
------


```js
browser.i18n.getUILanguage()
```

### Parameters

None.

### Return value

`string`. The browser UI language code as an `i18n.LanguageCode`.

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

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

Examples
--------


```js
let uiLanguage = browser.i18n.getUILanguage();
console.log(uiLanguage);

//e.g. "fr"
```


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

Gets the accept-languages of the browser. This is different from the locale used by the browser. To get the locale, use `i18n.getUILanguage`.

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

See the Internationalization page for a guide on using this function.

Syntax
------


```js
let gettingAcceptLanguages = browser.i18n.getAcceptLanguages()
```

### Parameters

None.

### Return value

A `Promise` that will be fulfilled with an `array` of ``i18n.LanguageCode`` objects.

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

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

Examples
--------


```js
function onGot(languages) {
  console.log(languages);
  //e.g. Array [ "en-US", "en" ]
}

let gettingAcceptLanguages = browser.i18n.getAcceptLanguages();
gettingAcceptLanguages.then(onGot);
```


**Note:** This API is based on Chromium's `chrome.i18n` API. This documentation is derived from `i18n.json` in the Chromium code.