recursal/MDN huggingface dataset:
devtools.panels.ElementsPanel.createSidebarPane()
=================================================

Adds a new pane to the sidebar in the HTML/CSS inspector.

The HTML/CSS inspector, called the Page Inspector in Firefox and the Elements panel in Chrome, displays the page DOM in the main part of its window, and has a sidebar that displays various other aspects of the page HTML/CSS in a tabbed interface. For example, in Firefox, the sidebar can display the CSS rules for the selected element, or its fonts, or its box model.

The `createSidebarPane()` function adds a new pane to the sidebar. For example, the screenshot below shows a new pane titled "My pane", that displays a JSON object:

![Image showing a new pane titled "My pane", that displays a JSON object](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/devtools/panels/ElementsPanel/createSidebarPane/inspector-sidebar.png)

This function takes one argument, which is a string representing the pane's title. It returns a `Promise` that resolves to an `ExtensionSidebarPane` object representing the new pane. You can use that object to define the pane's content and behavior.

Syntax
------


```js
let creating = browser.devtools.panels.elements.createSidebarPane(
  title       // string
)
```

### Parameters

`title`

`string`. The pane's title. This will appear in the row of tabs along the top of the sidebar, and is the main way the user will be able to identify your pane.

### Return value

A `Promise` that will be fulfilled with an `ExtensionSidebarPane` object representing the new pane.

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

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

Examples
--------

Create a new pane, and populate it with a JSON object. You could run this code in a script loaded by your extension's devtools page.


```js
function onCreated(sidebarPane) {
  sidebarPane.setObject({
    someBool: true,
    someString: "hello there",
    someObject: {
      someNumber: 42,
      someOtherString: "this is my pane's content",
    },
  });
}

browser.devtools.panels.elements.createSidebarPane("My pane").then(onCreated);
```


**Note:** This API is based on Chromium's `chrome.devtools.panels` API.
getLastChecked
==============

Returns the time since the last request was completed.

Syntax
------


```js
let state = browser.captivePortal.getLastChecked()
```

### Return value

A Promise that is fulfilled with an integer representing time in milliseconds.

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

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

Fires when the captive portal service determines that the user can connect to the internet.

Syntax
------


```js
browser.captivePortal.onConnectivityAvailable.addListener(listener)
browser.captivePortal.onConnectivityAvailable.removeListener(listener)
browser.captivePortal.onConnectivityAvailable.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:

`status`

`string` The status of the service, being one of `captive` if there is an unlocked captive portal present or `clear` if no captive portal is detected.


Examples
--------

Handle a change user's ability to connect to the internet:


```js
function handleConnectivity(connectivityInfo) {
  console.log(`The captive portal status: ${connectivityInfo.status}`);
}

browser.captivePortal.onConnectivityAvailable.addListener(handleConnectivity);
```

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

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

Return the canonical URL of the captive-portal detection page. Read-only.

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.tabs` API. This documentation is derived from `tabs.json` in the Chromium code.
getState
========

Returns the portal state as one of `unknown`, `not_captive`, `unlocked_portal`, or `locked_portal`.

Syntax
------


```js
let state = browser.captivePortal.getState()
```

### Return value

A Promise that is fulfilled with a string containing one of `unknown`, `not_captive`, `unlocked_portal`, or `locked_portal`.

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

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

Fires when the captive portal state changes.

Syntax
------


```js
browser.captivePortal.onStateChanged.addListener(listener)
browser.captivePortal.onStateChanged.removeListener(listener)
browser.captivePortal.onStateChanged.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:

`details`

`string` The captive portal state, being one of `unknown`, `not_captive`, `unlocked_portal`, or `locked_portal`.


Examples
--------

Handle a change in captive portal status:


```js
function handlePortalStatus(portalstatusInfo) {
  console.log(`The portal status is now: ${portalstatusInfo.details}`);
}

browser.captivePortal.onStateChanged.addListener(handlePortalStatus);
```

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

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

The **`getAllCookieStores()`** method of the `cookies` API returns a list of all cookie stores.

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

Syntax
------


```js
let gettingStores = browser.cookies.getAllCookieStores()
```

### Parameters

None.

### Return value

A `Promise` that will be fulfilled with an `array` of `cookies.CookieStore` objects representing all the existing cookie stores.

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

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

Examples
--------

In the following snippet, the `getAllCookieStores()` method is used to retrieve all the cookie stores currently available in the browser, and print out each cookie store ID, and the tabs that currently share each cookie store.


```js
function logStores(cookieStores) {
  for (const store of cookieStores) {
    console.log(`Cookie store: ${store.id}\n Tab IDs: ${store.tabIds}`);
  }
}

browser.cookies.getAllCookieStores().then(logStores);
```


Each member of the `cookieStores` array is a `cookies.CookieStore` object.

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

The `onChanged` event of the `cookies` API fires when a cookie that the extension can access is set or removed.

**Note:** When storage partitioning is active, `cookies.Cookie.partitionKey` contains the description of the cookie's storage partition. When modifying cookies, it's important to pass this value to `cookies.set()` or `cookies.remove()` to ensure the extension works with the correct cookie.

Note that updating a cookie's properties is implemented as a two step process:

1. First, the cookie to be updated is first removed entirely, generating a notification with a `cookies.OnChangedCause` of `overwrite`.
2. Next, a new cookie is written with the updated values, generating a second notification with a `cookies.OnChangedCause` of `explicit`.
Syntax
------


```js
browser.cookies.onChanged.addListener(listener)
browser.cookies.onChanged.removeListener(listener)
browser.cookies.onChanged.hasListener(listener)
```


This API is also available as `browser.cookies.onChanged.*`.

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:

`changeInfo`

An `object` containing details of the change that occurred. Its properties are as follows:

`removed`

A `boolean` that is set to `true` if a cookie was removed, and false if not.

`cookie`

A `cookies.Cookie` object containing information about the cookie that was set or removed.

`cause`

A `cookies.OnChangedCause` value representing the underlying reason behind the cookie's change.


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

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

Examples
--------

This example listens for `onChanged` events and logs details from the `changeInfo` argument:


```js
browser.cookies.onChanged.addListener((changeInfo) => {
  console.log(
    `Cookie changed: \n` +
      ` \* Cookie: ${JSON.stringify(changeInfo.cookie)}\n` +
      ` \* Cause: ${changeInfo.cause}\n` +
      ` \* Removed: ${changeInfo.removed}`,
  );
});
```

### Example extensions

* cookie-bg-picker

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

The **`remove()`** method of the `cookies` API deletes a cookie, given its name and URL.

The call succeeds only if you include the "cookies" API permission in your manifest.json file, as well as host permissions for the given URL specified in its manifest.

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

Syntax
------


```js
let removing = browser.cookies.remove(
  details               // object
)
```

### Parameters

`details`

An `object` containing information to identify the cookie to remove. It contains the following properties:

`firstPartyDomain` Optional

A `string` representing the first-party domain with which the cookie to remove is associated. This property must be supplied if the browser has first-party isolation enabled. See First-party isolation.

`name`

A `string` representing the name of the cookie to remove.

`partitionKey` Optional

An `object` representing the storage partition containing the cookie. Include this object to remove a cookie from partitioned storage. This object contains:

`topLevelSite` Optional

A `string` representing the first-party URL of the top-level site storage partition containing the cookie.


`storeId` Optional

A `string` representing the ID of the cookie store to find the cookie in. If unspecified, the cookie is looked for by default in the current execution context's cookie store.

`url`

A `string` representing the URL associated with the cookie. If the extension does not have host permissions for this URL, the API call will fail.


### Return value

A `Promise` that will be fulfilled with a `cookies.Cookie` object containing details about the cookie that's been removed. If a cookie matching the `details` parameter could not be found, the promise is fulfilled with `null`. If the call fails for any reason, the promise will be rejected with an error message.

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

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

Examples
--------

This example tries to remove the cookie named "favorite-color", whose URL matches the URL of the document hosted by the currently active tab:


```js
function onRemoved(cookie) {
  console.log(`Removed: ${cookie}`);
}

function onError(error) {
  console.log(`Error removing cookie: ${error}`);
}

function removeCookie(tabs) {
  let removing = browser.cookies.remove({
    url: tabs[0].url,
    name: "favorite-color",
  });
  removing.then(onRemoved, onError);
}

let getActive = browser.tabs.query({ active: true, currentWindow: true });
getActive.then(removeCookie);
```

### Example extensions

* cookie-bg-picker

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

The `OnChangedCause` type of the `cookies` API represents the reason a cookie changed.

Type
----

Values of this type are strings. Possible values are:

`evicted`

A cookie has been automatically removed due to garbage collection.

`expired`

A cookie has been automatically removed due to expiry.

`explicit`

A cookie has been inserted or removed via an explicit call to `cookies.remove()`.

`expired_overwrite`

A cookie has been overwritten by a cookie with an already-expired expiration date.

`overwrite`

A call to `cookies.set()` overwrote this cookie with a different one.

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

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

Examples
--------

You can listen to the `cookies.onChanged` event to be notified when cookies change. The listener is passed a `changeInfo` object that contains a `cause` property, whose value is the `OnChangeCaused` string:


```js
browser.cookies.onChanged.addListener((changeInfo) => {
  console.log(
    `Cookie changed: \n` +
      ` \* Cookie: ${JSON.stringify(changeInfo.cookie)}\n` +
      ` \* Cause: ${changeInfo.cause}\n` +
      ` \* Removed: ${changeInfo.removed}`,
  );
});
```


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

The `CookieStore` type of the `cookies` API represents a cookie store in the browser.

Windows in different browsing modes may use different cookie stores. For example, a private browsing/incognito mode window uses a separate cookie store from a non-incognito/private window. Also, a window may have several cookie stores when using container tabs in Firefox.

See Work with the Cookies API for more information about cookie stores.

Type
----

Values of this type are objects, which can contain the following properties:

`id`

A `string` representing the unique identifier for the cookie store.

`incognito` Optional

 A boolean value that indicates whether this is an incognito cookie store.
 This property is not supported in Chrome or Safari. However, you can identify incognito cookie stores in Chrome because their `id` is always "1".


`tabIds`

An `array` of `integers`, which identifies all of the browser tabs that share this cookie store.

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

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

Examples
--------

In the following snippet, the `cookies.getAllCookieStores()` method is used to retrieve all the cookie stores currently available in the browser, and print out each cookie store ID, and the tabs that currently share each cookie store.


```js
function logStores(cookieStores) {
  for (const store of cookieStores) {
    console.log(`Cookie store: ${store.id}\n Tab IDs: ${store.tabIds}`);
  }
}

browser.cookies.getAllCookieStores().then(logStores);
```


The following code snippet gets all cookie stores and then logs the total number of stores and how many of those stores are incognito.


```js
browser.cookies.getAllCookieStores().then((stores) => {
  const incognitoStores = stores.map((store) => store.incognito);
  console.log(
    `Of ${stores.length} cookie stores, ${incognitoStores.length} are incognito.`,
  );
});
```


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

The `Cookie` type of the `cookies` API represents information about an HTTP cookie.

Type
----

Values of this type are objects, which can contain the following properties:

`domain`

A `string` representing the domain the cookie belongs to (e.g. "www.google.com", "example.com").

`expirationDate` Optional

A `number` representing the expiration date of the cookie as the number of seconds since the UNIX epoch. Not provided for session cookies.

`firstPartyDomain`

A `string` representing the first-party domain associated with the cookie. This will be an empty string if the cookie was set while first-party isolation was off. See First-party isolation.

`hostOnly`

A `boolean`, `true` if the cookie is a host-only cookie (i.e. the request's host must exactly match the domain of the cookie), or `false` otherwise.

`httpOnly`

A `boolean`, `true` if the cookie is marked as HttpOnly (i.e. the cookie is inaccessible to client-side scripts), or `false` otherwise.

`name`

A `string` representing the name of the cookie.

`partitionKey` Optional

An `object` representing the description of the storage partition containing the cookie. This object is omitted (null) if the cookie is not in partitioned storage. This object contains the following properties:

`topLevelSite`

A `string` representing the first-party URL of the cookie's storage partition, if the cookie is in storage that is partitioned by top-level site.


`path`

A `string` representing the path of the cookie.

`secure`

A `boolean`, `true` if the cookie is marked as secure (i.e. its scope is limited to secure channels, typically HTTPS), or `false` otherwise.

`session`

A `boolean`, `true` if the cookie is a session cookie, or `false` if it is a persistent cookie with an expiration date.

`sameSite`

A `cookies.SameSiteStatus` value that indicates the SameSite state of the cookie.

`storeId`

A `string` representing the ID of the cookie store containing this cookie, as provided by `cookies.getAllCookieStores()`.

`value`

A `string` representing the value of the cookie.

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

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

Examples
--------

Most methods in the cookies API involve a `Cookie` object being used either as an input parameter or as part of the return value. For example, a call to `cookies.getAll()` returns an array of `Cookie` objects.

In the example below we've asked for all cookies, then logged some of the values of each of the resulting `Cookie` objects:


```js
function logCookies(cookies) {
  for (cookie of cookies) {
    console.log(`Domain: ${cookie.domain}`);
    console.log(`Name: ${cookie.name}`);
    console.log(`Value: ${cookie.value}`);
    console.log(`Persistent: ${!cookie.session}`);
  }
}

let gettingAll = browser.cookies.getAll({});
gettingAll.then(logCookies);
```


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

The `SameSiteStatus` type of the `cookies` API represents information about the `SameSite` state of a cookie.

Type
----

Values of this type are strings. Possible values are:

`no_restriction`

Corresponds to a cookie set with `SameSite=None`.

`lax`

Corresponds to a cookie set with `SameSite=Lax`.

`strict`

Corresponds to a cookie set with `SameSite=Strict`.

`unspecified`

Corresponds to a cookie set without the `SameSite` attribute. This state is not part of any SameSite standard, and is only supported by browsers that store this state internally. Other browsers map the absence of the SameSite flag to the default state (e.g. Lax). See the browser compatibility table for more details.

See SameSite cookies for more information.

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

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

The **`get()`** method of the `cookies` API retrieves information about a single cookie, given its name and URL.

If more than one cookie with the same name exists for a given URL, the one with the longest path will be returned. For cookies with the same path length, the cookie with the earliest creation time will be returned. If no matching cookie could be found, `null` is returned.

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

Syntax
------


```js
let getting = browser.cookies.get(
  details                // object
)
```

### Parameters

`details`

An `object` containing details that can be used to match a cookie to be retrieved. It can include the following properties:

`firstPartyDomain` Optional

A `string` representing the first-party domain with which the cookie to retrieve is associated. This property must be supplied if the browser has first-party isolation enabled. See First-party isolation.

`name`

A `string` representing the name of the cookie to retrieve.

`partitionKey` Optional

An `object` representing the storage partition containing the cookie. Include this object with `topLevelSite` to obtain a cookie from partitioned storage. Otherwise, returns the cookie from unpartitioned storage. This object contains:

`topLevelSite` Optional

A `string` representing the first-party URL of the top-level site storage partition containing the cookie.


`storeId` Optional

A `string` representing the ID of the `cookie store` in which to look for the cookie (as returned by `cookies.getAllCookieStores()`). By default, the current execution context's cookie store will be used.

`url`

A `string` representing the URL with which the cookie to retrieve is associated. This argument may be a full URL, in which case any data following the URL path (e.g. the query string) is ignored. If host permissions for this URL are not specified in the extension's manifest file, the API call will fail.


### Return value

A `Promise` that will be fulfilled with a `Cookie` object containing details about the cookie, or `null` if the cookie was not found.

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

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

Examples
--------

This example tries to get the cookie named "favorite-color", associated with the URL for the currently active tab:


```js
function logCookie(cookie) {
  if (cookie) {
    console.log(cookie.value);
  }
}

function getCookie(tabs) {
  let getting = browser.cookies.get({
    url: tabs[0].url,
    name: "favorite-color",
  });
  getting.then(logCookie);
}

let getActive = browser.tabs.query({
  active: true,
  currentWindow: true,
});
getActive.then(getCookie);
```

### Example extensions

* cookie-bg-picker

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

The `State` type of the `downloads` API defines different states that a current download can be in.

A `downloads.DownloadItem`'s `state` property will contain a string taken from the values defined in this type.

Type
----

Values of this type are strings. Possible values are:

`in_progress`

The browser is currently receiving download data from the server.

`interrupted`

An error broke the connection with the server.

`complete`

The download completed successfully.


**Note:** These string constants will never change, but new constants may be added.

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.downloads` API.