PublicKeyCredential: isConditionalMediationAvailable() static method - Web APIs

PublicKeyCredential: isConditionalMediationAvailable() static method
====================================================================

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The **`isConditionalMediationAvailable()`** static method of the `PublicKeyCredential` interface returns a `Promise` which resolves to `true` if conditional mediation is available.

Conditional mediation, if available, results in any discovered credentials being presented to the user in a non-modal dialog box along with an indication of the origin requesting credentials. This is requested by including `mediation: 'conditional'` in your `get()` call. In practice, this means autofilling available credentials; you need to include `autocomplete="webauthn"` on your form fields so that they will show the WebAuthn sign-in options.

A conditional `get()` call does not show the browser UI and remains pending until the user picks an account to sign-in with from available autofill suggestions:

* If the user makes a gesture outside of the dialog, it closes without resolving or rejecting the Promise and without causing a user-visible error condition.
* If the user selects a credential, that credential is returned to the caller.

The prevent silent access flag (see `CredentialsContainer.preventSilentAccess()`) is treated as being `true` regardless of its actual value: the conditional behavior always involves user mediation of some sort if applicable credentials are discovered.

**Note:** If no credentials are discovered, the non-modal dialog will not be visible, and the user agent can prompt the user to take action in a way that depends on the type of credential (for example, to insert a device containing credentials).

Syntax
------

```js
isConditionalMediationAvailable()
```

### Parameters

None.

### Return value

A `Promise` which resolves to a boolean value indicating whether or not conditional mediation is available.

Examples
--------

Before invoking a conditional WebAuthn API call, check if:

* The browser supports the Web Authentication API.
* The browser supports WebAuthn conditional UI.

```js
// Availability of `window.PublicKeyCredential` means WebAuthn is usable.
if (
  window.PublicKeyCredential &&
  PublicKeyCredential.isConditionalMediationAvailable
) {
  // Check if conditional mediation is available.
  const isCMA = await PublicKeyCredential.isConditionalMediationAvailable();
  if (isCMA) {
    // Call WebAuthn authentication
    const publicKeyCredentialRequestOptions = {
      // Server generated challenge
      challenge: \*\*\*\*,
      // The same RP ID as used during registration
      rpId: "example.com",
    };

    const credential = await navigator.credentials.get({
      publicKey: publicKeyCredentialRequestOptions,
      signal: abortController.signal,
      // Specify 'conditional' to activate conditional UI
      mediation: "conditional",
    });
  }
}
```

**Note:** See Sign in with a passkey through form autofill for more information about using conditional mediation.

Specifications
--------------

| Specification |
| --- |
| Web Authentication: An API for accessing Public Key Credentials - Level 3 # dom-publickeycredential-isconditionalmediationavailable |

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

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


PublicKeyCredential: parseRequestOptionsFromJSON() static method - Web APIs

PublicKeyCredential: parseRequestOptionsFromJSON() static method
================================================================

**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The **`parseRequestOptionsFromJSON()`** static method of the `PublicKeyCredential` interface converts a JSON type representation into its corresponding `publicKey` request credentials options object structure.

The method is a convenience function for converting information provided by a relying server to a web app in order to request an existing credential.

Syntax
------

```js
PublicKeyCredential.parseRequestOptionsFromJSON(options)
```

### Parameters

`options`

An object with the same structure as the Web Authentication API `publicKey` request credentials options object, but with base64url-encoded strings used in place of buffer properties.

### Return value

An object with the Web Authentication API `publicKey` request credentials options object structure.

### Exceptions

`EncodingError` `DOMException`

Thrown if any part of the `options` object cannot be converted into the `publicKey` request credentials options object structure.

Description
-----------

 The Web Authentication process for authenticating a (registered) user involves a relying party server sending the web app information needed to find an existing credential, including details about the user identity, the relying party, a "challenge", and optionally where to look for the credential: for example on a local built-in authenticator, or on an external one over USB, BLE, and so on.
 The web app passes this information to an authenticator to find the credential, by calling `navigator.credentials.get()` with an argument that contains the server-supplied data in the `publicKey` request credentials options object structure.

 The specification does not define how the information needed for requesting a credential is sent.
 A convenient approach is for the server to encapsulate the information in a JSON type representation of the `publicKey` request credentials options object that mirrors its structure but encodes buffer properties such as the `challenge` as base64url strings.
 This object can be serialized to a JSON string, sent to the web app and deserialized, and then converted to the `publicKey` request credentials options object structure using **`parseRequestOptionsFromJSON()`**.

Examples
--------

 When authorizing an already registered user, a relying party server will supply the web app with information about the requested credentials, the relying party, and a challenge.
 The code below defines this information in the form described in the `options` parameter above:

```js
const requestCredentialOptionsJSON =  {
    challenge: new Uint8Array([139, 66, 181, 87, 7, 203, ...]),
    rpId: "acme.com",
    allowCredentials: [{
      type: "public-key",
      id: new Uint8Array([64, 66, 25, 78, 168, 226, 174, ...])
    }],
    userVerification: "required",
  }
```

Because this object only uses JSON data types, it can be serialized to JSON using `JSON.stringify()` and sent to the web app.

```js
JSON.stringify(requestCredentialOptionsJSON);
```

 The web app can deserialize the JSON string back to a `requestCredentialOptionsJSON` object (not shown).
 The **`parseRequestOptionsFromJSON()`** method is used to convert that object to the form that can be used in `navigator.credentials.get()`:

```js
// Convert options to form used by get()
const publicKey = PublicKeyCredential.parseRequestOptionsFromJSON(
  requestCredentialOptionsJSON, // JSON-type representation
);

navigator.credentials
  .get({ publicKey })
  .then((returnedCredentialInfo) => {
    // Handle the returned credential information here.
  })
  .catch((err) => {
    console.error(err);
  });
```

Specifications
--------------

| Specification |
| --- |
| Web Authentication: An API for accessing Public Key Credentials - Level 3 # dom-publickeycredential-parserequestoptionsfromjson |

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

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

See also
--------

* Web Authentication API
* `PublicKeyCredential.parseCreationOptionsFromJSON()`


PublicKeyCredential: id property - Web APIs

PublicKeyCredential: id property
================================

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

 The **`id`** read-only property of the
 `PublicKeyCredential` interface is a string, inherited
 from `Credential`, which represents the identifier of the current
 `PublicKeyCredential` instance.

This property is a base64url encoded version of `PublicKeyCredential.rawId`.

**Note:** This property may only be used in top-level contexts and will
 not be available in an `<iframe>` for example.

Value
-----

A string being the base64url encoded version of `PublicKeyCredential.rawId`.

Examples
--------

```js
const publicKey = {
  challenge: new Uint8Array(26) /\* this actually is given from the server \*/,
  rp: {
    name: "Example CORP",
    id: "login.example.com",
  },
  user: {
    id: new Uint8Array(26) /\* To be changed for each user \*/,
    name: "canand@example.com",
    displayName: "Carina Anand",
  },
  pubKeyCredParams: [
    {
      type: "public-key",
      alg: -7,
    },
  ],
};

navigator.credentials
  .create({ publicKey })
  .then((newCredentialInfo) => {
    const id = newCredentialInfo.id;
    // Do something with the id

    // send attestation response and client extensions
    // to the server to proceed with the registration
    // of the credential
  })
  .catch((err) => {
    console.error(err);
  });
```

Specifications
--------------

#### No specification found

No specification data found for `api.PublicKeyCredential.id`.
Check for problems with this page or contribute a missing `spec_url` to mdn/browser-compat-data. Also make sure the specification is included in w3c/browser-specs.

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

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

See also
--------

* `Credential.id`


PublicKeyCredential: getClientExtensionResults() method - Web APIs

PublicKeyCredential: getClientExtensionResults() method
=======================================================

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

 The **`getClientExtensionResults()`** method of the
 `PublicKeyCredential` interface returns a map between the identifiers of extensions requested during credential creation or authentication, and their results after processing by the user agent.

 During the creation or fetching of a `PublicKeyCredential` (via
 `navigator.credentials.create()` and
 `navigator.credentials.get()` respectively), it is possible
 to request "custom" processing by the client for different extensions, specified in the `publicKey` option's `extensions` property. You can find more information about requesting the different extensions in Web Authentication extensions.

**Note:** `getClientExtensionResults()` only returns the results from extensions processed by the user agent (client). The results from extensions processed by the authenticator can be found in the authenticator data available in `AuthenticatorAssertionResponse.authenticatorData`.

Syntax
------

```js
getClientExtensionResults()
```

### Parameters

None.

### Return value

A `map`, with each entry being an extensions' identifier string as the key, and the output from the processing of the extension by the client as the value.

Examples
--------

```js
const publicKey = {
  // Here are the extension "inputs"
  extensions: {
    appid: "https://accounts.example.com",
  },
  allowCredentials: {
    id: "fgrt46jfgd...",
    transports: ["usb", "nfc"],
    type: "public-key",
  },
  challenge: new Uint8Array(16) /\* from the server \*/,
};

navigator.credentials
  .get({ publicKey })
  .then((publicKeyCred) => {
    const myResults = publicKeyCred.getClientExtensionResults();
    // myResults will contain the output of processing the "appid" extension
  })
  .catch((err) => {
    console.error(err);
  });
```

Specifications
--------------

| Specification |
| --- |
| Web Authentication: An API for accessing Public Key Credentials - Level 3 # ref-for-dom-publickeycredential-getclientextensionresults |

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

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

**Note:** Extensions are optional and different browsers may recognize different extensions. Processing extensions is always optional for the client: if a browser does not recognize a given extension, it will just ignore it. For information on which extensions are supported by which browsers, see Web Authentication extensions.

See also
--------

* The list of the currently defined extensions
* `AuthenticatorAssertionResponse.authenticatorData` which contains the
 result of the authenticator's extensions processing


PublicKeyCredential: rawId property - Web APIs

PublicKeyCredential: rawId property
===================================

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

 The **`rawId`** read-only property of the
 `PublicKeyCredential` interface is an `ArrayBuffer` object
 containing the identifier of the credentials.

The `PublicKeyCredential.id` property is a base64url encoded version of this identifier.

**Note:** This property may only be used in top-level contexts and will
 not be available in an `<iframe>` for example.

Value
-----

 A `ArrayBuffer` containing the identifier of the credentials. This
 identifier is expected to be globally unique and is appointed for the current
 `PublicKeyCredential` and its associated
 `AuthenticatorAssertionResponse`.

Examples
--------

```js
const options = {
  challenge: new Uint8Array(26) /\* from the server \*/,
  rp: {
    name: "Example CORP",
    id: "login.example.com",
  },
  user: {
    id: new Uint8Array(26) /\* To be changed for each user \*/,
    name: "canand@example.com",
    displayName: "Carina Anand",
  },
  pubKeyCredParams: [
    {
      type: "public-key",
      alg: -7,
    },
  ],
};

navigator.credentials
  .create({ publicKey: options })
  .then((pubKeyCredential) => {
    const rawId = pubKeyCredential.rawId;
    // Do something with rawId
  })
  .catch((err) => {
    // Deal with any error
  });
```

Specifications
--------------

| Specification |
| --- |
| Web Authentication: An API for accessing Public Key Credentials - Level 3 # ref-for-dom-publickeycredential-rawid |

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

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


PublicKeyCredential: parseCreationOptionsFromJSON() static method - Web APIs

PublicKeyCredential: parseCreationOptionsFromJSON() static method
=================================================================

**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The **`parseCreationOptionsFromJSON()`** static method of the `PublicKeyCredential` interface converts a JSON type representation into its corresponding `publicKey` create credentials options object structure.

The method is a convenience function for converting credential options information provided by a relying party server to the form that a web app can use to create a credential.

Syntax
------

```js
PublicKeyCredential.parseCreationOptionsFromJSON(options)
```

### Parameters

`options`

An object with the same structure as the Web Authentication API `publicKey` create credentials options object, but with base64url-encoded strings used in place of buffer properties.

### Return value

An object with the Web Authentication API `publicKey` create credentials options object structure.

### Exceptions

`EncodingError` `DOMException`

Thrown if any part of the `options` object cannot be converted into the `publicKey` create credentials options object structure.

Description
-----------

 The Web Authentication process for creating a key pair and registering a user involves a relying party server sending the web app information needed to create a credential, including details about the user identity, the relying party, and a "challenge".
 The web app passes this information to an authenticator to create the credential, by calling `navigator.credentials.create()` with an argument that contains the server-supplied data in the `publicKey` create credentials options object structure.

 The specification does not define how the information needed for creating a credential is sent.
 A convenient approach is for the server to encapsulate the information in a JSON type representation of the `publicKey` create credentials options object that mirrors its structure but encodes buffer properties such as the `challenge` and `user.id` as base64url strings.
 This object can be serialized to a JSON string, sent to the web app and deserialized, and then converted to the `publicKey` create credentials options object structure using **`parseCreationOptionsFromJSON()`**.

Examples
--------

 When registering a new user, a relying party server will supply information about the expected credentials to the web app.
 The code below defines this information in the form described in the `options` parameter above (taken from the "getting an AuthenticatorAttestationResponse" in `AuthenticatorResponse`):

```js
const createCredentialOptionsJSON = {
  challenge:
    "21, 31, 105, " /\* 29 more random bytes generated by the server in this string \*/,
  rp: {
    name: "Example CORP",
    id: "login.example.com",
  },
  user: {
    id: "16",
    name: "canand@example.com",
    displayName: "Carina Anand",
  },
  pubKeyCredParams: [
    {
      type: "public-key",
      alg: -7,
    },
  ],
};
```

Because this object only uses JSON data types, it can be serialized to JSON using `JSON.stringify()` and sent to the web app.

```js
JSON.stringify(createCredentialOptionsJSON);
```

 The web app can deserialize the JSON string back to a `createCredentialOptionsJSON` object (not shown).
 The **`parseCreationOptionsFromJSON()`** method is used to convert that object to the form that can be used in `navigator.credentials.create()`:

```js
// Convert options to form used by create()
const createCredentialOptions =
  PublicKeyCredential.parseCreationOptionsFromJSON(
    createCredentialOptionsJSON, // JSON-type representation
  );

navigator.credentials
  .create({ createCredentialOptions })
  .then((newCredentialInfo) => {
    // Handle the new credential information here.
  })
  .catch((err) => {
    console.error(err);
  });
```

Specifications
--------------

| Specification |
| --- |
| Web Authentication: An API for accessing Public Key Credentials - Level 3 # dom-publickeycredential-parsecreationoptionsfromjson |

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

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

See also
--------

* Web Authentication API
* `PublicKeyCredential.parseRequestOptionsFromJSON()`
* `PublicKeyCredential.toJSON()`


PublicKeyCredential: isUserVerifyingPlatformAuthenticatorAvailable() static method - Web APIs

PublicKeyCredential: isUserVerifyingPlatformAuthenticatorAvailable() static method
==================================================================================

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The **`isUserVerifyingPlatformAuthenticatorAvailable()`** static method of the `PublicKeyCredential` interface returns a `Promise` which resolves to `true` if a user-verifying platform authenticator is present.

A user-verifying platform authenticator is a kind of multi-factor authenticator that is part of the client device (it is generally not removable) and that involves an action from the user in order to identify them. Common user-verifying platform authenticators include:

* Touch ID or Face ID (macOS and iOS)
* Windows Hello (Windows)
* Device unlock (fingerprint, face, PIN, etc.) on Android

**Note:** This method may only be used in top-level contexts and will not be available in an `<iframe>` for example.

Syntax
------

```js
PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable()
```

### Parameters

None.

### Return value

 A `Promise` which resolves to a boolean value indicating whether or
 a not a user-verifying platform authenticator is available.

**Note:** In earlier versions of the specification, the boolean also
 conveyed the consent of the user to disclose such an authenticator existed.

Examples
--------

```js
PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable()
  .then((available) => {
    if (available) {
      // We can proceed with the creation of a PublicKeyCredential
      // with this authenticator
    } else {
      // Use another kind of authenticator or a classical login/password
      // workflow
    }
  })
  .catch((err) => {
    // Something went wrong
    console.error(err);
  });
```

Specifications
--------------

| Specification |
| --- |
| Web Authentication: An API for accessing Public Key Credentials - Level 3 # dom-publickeycredential-isuserverifyingplatformauthenticatoravailable |

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

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

See also
--------

* Windows Hello
* Web Authentication and Windows Hello - MSDN Guide and especially the special considerations mentioning `isUserVerifyingPlatformAuthenticator()`


PublicKeyCredential: response property - Web APIs

PublicKeyCredential: response property
======================================

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

 The **`response`** read-only property of the
 `PublicKeyCredential` interface is an `AuthenticatorResponse`
 object which is sent from the authenticator to the user agent for the creation/fetching
 of credentials. The information contained in this response will be used by the relying
 party's server to verify the demand is legitimate.

An `AuthenticatorResponse` is either:

* an `AuthenticatorAttestationResponse` (when the
 `PublicKeyCredential` is created via
 `CredentialsContainer.create()`)
* an `AuthenticatorAssertionResponse` (when the
 `PublicKeyCredential` is obtained via
 `CredentialsContainer.get()`).

 In order to validate the *creation* of credentials, a relying party's server
 needs both:

* this response
* the extensions of the client (given by
 `PublicKeyCredential.getClientExtensionResults()`) to validate the
 demand.

**Note:** When validating the fetching of existing credentials, the
 whole `PublicKeyCredential` object and the client extensions are necessary
 for the relying party's server.

**Note:** This property may only be used in top-level contexts and will
 not be available in an `<iframe>` for example.

Value
-----

 An `AuthenticatorResponse` object containing the data a relying party's
 script will receive and which should be sent to the relying party's server in order to
 validate the demand for creation or fetching. This object contains data from the client
 (`AuthenticatorResponse/clientDataJSON`) and from the authenticator.

Examples
--------

```js
const options = {
  challenge: new Uint8Array(16) /\* from the server \*/,
  rp: {
    name: "Example CORP",
    id: "login.example.com",
  },
  user: {
    id: new Uint8Array(16) /\* from the server \*/,
    name: "canand@example.com",
    displayName: "Carina Anand",
  },
  pubKeyCredParams: [
    {
      type: "public-key",
      alg: -7,
    },
  ],
};

navigator.credentials
  .create({ publicKey: options })
  .then((pubKeyCredential) => {
    const response = pubKeyCredential.response;
    const clientExtResults = pubKeyCredential.getClientExtensionResults();
    // Send response and client extensions to the server so that it can validate
    // and create credentials
  })
  .catch((err) => {
    // Deal with any error
  });
```

Specifications
--------------

| Specification |
| --- |
| Web Authentication: An API for accessing Public Key Credentials - Level 3 # dom-publickeycredential-response |

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

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


PublicKeyCredential: authenticatorAttachment property - Web APIs

PublicKeyCredential: authenticatorAttachment property
=====================================================

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The **`authenticatorAttachment`** read-only property of the `PublicKeyCredential` interface is a string that indicates the general category of authenticator used during the associated `navigator.credentials.create()` or `navigator.credentials.get()` call.

Value
-----

A string, which will be one of the following values:

`"platform"`

The authenticator is part of the device WebAuthn is running on (termed a **platform authenticator**), therefore WebAuthn will communicate with it using a transport available to that platform, such as a platform-specific API. A public key credential bound to a platform authenticator is called a **platform credential**.

`"cross-platform"`

The authenticator is not a part of the device WebAuthn is running on (termed a **roaming authenticator** as it can roam between different devices), therefore WebAuthn will communicate with it using a cross-platform transport protocol such as Bluetooth or NFC. A public key credential bound to a roaming authenticator is called a **roaming credential**.

Examples
--------

```js
const options = {
  challenge: new Uint8Array(26) /\* from the server \*/,
  rp: {
    name: "Example CORP",
    id: "login.example.com",
  },
  user: {
    id: new Uint8Array(26) /\* To be changed for each user \*/,
    name: "canand@example.com",
    displayName: "Carina Anand",
  },
  pubKeyCredParams: [
    {
      type: "public-key",
      alg: -7,
    },
  ],
};

navigator.credentials
  .create({ publicKey: options })
  .then((pubKeyCredential) => {
    const attachment = pubKeyCredential.authenticatorAttachment;
    // Do something with authenticatorAttachment
  })
  .catch((err) => {
    // Deal with any error
  });
```

Specifications
--------------

| Specification |
| --- |
| Web Authentication: An API for accessing Public Key Credentials - Level 3 # dom-publickeycredential-authenticatorattachment |

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

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


CSSTransformValue: entries() method - Web APIs

CSSTransformValue: entries() method
===================================

 The **`CSSTransformValue.entries()`** method
 returns an array of a given object's own enumerable
 property `[key, value]` pairs in the same order as that provided by a
 `for...in` loop (the difference being that a for-in loop enumerates
 properties in the prototype chain as well).

Syntax
------

```js
entries(obj)
```

### Parameters

`obj`

 The `CSSTransformValue` whose enumerable own property
 `[key, value]` pairs are to be returned.

### Return value

 An array of the given `CSSTransformValue` object's own enumerable property
 `[key, value]` pairs.

Examples
--------

To Do

Specifications
--------------

#### No specification found

No specification data found for `api.CSSTransformValue.entries`.
Check for problems with this page or contribute a missing `spec_url` to mdn/browser-compat-data. Also make sure the specification is included in w3c/browser-specs.

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

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


CSSTransformValue: CSSTransformValue() constructor - Web APIs

CSSTransformValue: CSSTransformValue() constructor
==================================================

 The **`CSSTransformValue()`** constructor
 creates a new `CSSTransformValue` object which represents a list of
 individual transform objects.

Syntax
------

```js
new CSSTransformValue(transforms)
```

### Parameters

`transforms`

A list of `CSSTransformComponent` objects to iterate over.

### Return value

A new `CSSTransformValue`.

### Exceptions

`TypeError`

Raised if transforms is empty.

Examples
--------

To do

Specifications
--------------

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-csstransformvalue-csstransformvalue |

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

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


CSSTransformValue: toMatrix() method - Web APIs

CSSTransformValue: toMatrix() method
====================================

 The **`toMatrix()`** method of the
 `CSSTransformValue` interface returns a `DOMMatrix` object.

Syntax
------

```js
toMatrix()
```

### Parameters

None.

### Return value

A `DOMMatrix` object.

### Exceptions

`TypeError`

 Raised if any lengths involved in generating the matrix are not compatible units
 with px (such as relative lengths or percentages).

Examples
--------

To Do

Specifications
--------------

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-csstransformvalue-tomatrix |

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

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


CSSTransformValue: length property - Web APIs

CSSTransformValue: length property
==================================

 The read-only **`length`** property of the
 `CSSTransformValue` interface returns the number of transform components in
 the list.

Value
-----

An integer representing the number of transform components in the list.

Examples
--------

To Do

Specifications
--------------

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-csstransformvalue-length |

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

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


CSSTransformValue: values() method - Web APIs

CSSTransformValue: values() method
==================================

 The **`CSSTransformValue.values()`** returns a
 new *array iterator* object that contains the values for
 each index in the CSSTransformValue object.

Syntax
------

```js
values()
```

### Parameters

None.

### Return value

A new `Array`.

Examples
--------

To Do

Specifications
--------------

#### No specification found

No specification data found for `api.CSSTransformValue.values`.
Check for problems with this page or contribute a missing `spec_url` to mdn/browser-compat-data. Also make sure the specification is included in w3c/browser-specs.

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

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


CSSTransformValue: keys() method - Web APIs

CSSTransformValue: keys() method
================================

 The **`CSSTransformValue.keys()`** method
 returns a new *array iterator* object that contains the keys
 for each index in the array.

Syntax
------

```js
keys()
```

### Parameters

None.

### Return value

A new `Array`.

Examples
--------

To Do

Specifications
--------------

#### No specification found

No specification data found for `api.CSSTransformValue.keys`.
Check for problems with this page or contribute a missing `spec_url` to mdn/browser-compat-data. Also make sure the specification is included in w3c/browser-specs.

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

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


CSSTransformValue: is2D property - Web APIs

CSSTransformValue: is2D property
================================

 The read-only **`is2D`** property of the
 `CSSTransformValue` interface returns whether the transform is 2D or 3D.

 In the case of the `CSSTransformValue` this property returns
 true unless any of the individual functions return false for `Is2D`, in which
 case it returns false.

Value
-----

 A boolean. True indicates that the transform is a 2D transform, false that it is a 3D
 transform.

Examples
--------

To Do

Specifications
--------------

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-csstransformvalue-is2d |

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

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


CSSTransformValue: forEach() method - Web APIs

CSSTransformValue: forEach() method
===================================

The **`CSSTransformValue.forEach()`** method executes a provided function once for each element of the `CSSTransformValue`.

Syntax
------

```js
forEach(callbackFn)
forEach(callbackFn, thisArg)
```

### Parameters

`callbackFn`

The function to execute for each element, taking three arguments:

`currentValue`

The value of the current element being processed.

`index` Optional

The index of the current element being processed.

`array` Optional

The `CSSTransformValue` that `forEach()` is being called on.

`thisArg` Optional

Value to use as **`this`** (i.e., the reference `Object`) when executing `callback`.

### Return value

None (`undefined`).

Examples
--------

To Do

Specifications
--------------

#### No specification found

No specification data found for `api.CSSTransformValue.forEach`.
Check for problems with this page or contribute a missing `spec_url` to mdn/browser-compat-data. Also make sure the specification is included in w3c/browser-specs.

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

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


TextUpdateEvent: updateRangeStart property - Web APIs

TextUpdateEvent: updateRangeStart property
==========================================

**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

The **`TextUpdateEvent.updateRangeStart`** read-only property indicates the start position of the text range that is being replaced in the `EditContext` object.

Value
-----

A `Number`.

Examples
--------

### Using `textupdate` to display the inserted text and location

```html
<div id="editor"></div>
```

```js
const editorEl = document.getElementById("editor");
const editContext = new EditContext();
editorEl.editContext = editContext;

editContext.addEventListener("textupdate", (e) => {
  console.log(
    `The user inserted the text "${e.text}" between index ${e.updateRangeStart} and index ${e.updateRangeEnd}.`,
  );
});
```

Specifications
--------------

| Specification |
| --- |
| EditContext API # dom-textupdateevent-updaterangestart |

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

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


TextUpdateEvent: text property - Web APIs

TextUpdateEvent: text property
==============================

**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

The **`TextUpdateEvent.text`** read-only property contains the text that was inserted within the updated range of a `EditContext`'s `textupdate` event.

Value
-----

A `String` that contains the text that replaces the text contained between the `updateRangeStart` and `updateRangeEnd` indexes.

Examples
--------

### Using `textupdate` to display the inserted text and location

```html
<div id="editor"></div>
```

```js
const editorEl = document.getElementById("editor");
const editContext = new EditContext();
editorEl.editContext = editContext;

editContext.addEventListener("textupdate", (e) => {
  console.log(
    `The user inserted the text "${e.text}" at index ${e.updateRangeStart}.`,
  );
});
```

Specifications
--------------

| Specification |
| --- |
| EditContext API # dom-textupdateevent-text |

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

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


TextUpdateEvent: selectionEnd property - Web APIs

TextUpdateEvent: selectionEnd property
======================================

**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

The **`TextUpdateEvent.selectionEnd`** read-only property indicates the position of the end of the selection (or caret) within the text content of the editable region attached to the `EditContext` object.

Value
-----

A `Number`.

Examples
--------

### Using `textupdate` to render the edited text and user selection

This example shows how to use the `selectionEnd` property to render the selected text within a `textupdate` event handler.

```css
#editor {
  height: 200px;
  background: #eee;
  color: black;
}

.selection {
  display: inline-block;
  vertical-align: bottom;
  background: blue;
  color: white;
  min-width: 2px;
  height: 3ex;
}
```

```html
<div id="editor"></div>
```

```js
const editorEl = document.getElementById("editor");
const editContext = new EditContext();
editorEl.editContext = editContext;

editContext.addEventListener("textupdate", (e) => {
  // Clear the current content.
  editorEl.innerHTML = "";

  const text = editContext.text;
  const { selectionStart, selectionEnd } = e;

  // Render the text before the selection.
  const textBefore = document.createElement("span");
  textBefore.textContent = text.substring(0, selectionStart);

  // Render the selected text, or caret.
  const textSelected = document.createElement("span");
  textSelected.classList.add("selection");
  textSelected.textContent = text.substring(selectionStart, selectionEnd);

  // Render the text after the selection.
  const textAfter = document.createElement("span");
  textAfter.textContent = text.substring(selectionEnd);

  editorEl.appendChild(textBefore);
  editorEl.appendChild(textSelected);
  editorEl.appendChild(textAfter);

  console.log(`Text before selection: ${textBefore.textContent}`);
  console.log(`Selected text: ${textSelected.textContent}`);
  console.log(`Text after selection: ${textAfter.textContent}`);
});
```

Specifications
--------------

| Specification |
| --- |
| EditContext API # dom-textupdateevent-selectionend |

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

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


TextUpdateEvent: selectionStart property - Web APIs

TextUpdateEvent: selectionStart property
========================================

**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

The **`TextUpdateEvent.selectionStart`** read-only property indicates the position of the end of the selection (or caret) within the text content of the editable region attached to the `EditContext` object.

Value
-----

A `Number`.

Examples
--------

### Using `textupdate` to render the edited text and user selection

This example shows how to use the `selectionStart` property to render the selected text within a `textupdate` event handler.

```css
#editor {
  height: 200px;
  background: #eee;
  color: black;
}

.selection {
  display: inline-block;
  vertical-align: bottom;
  background: blue;
  color: white;
  min-width: 2px;
  height: 3ex;
}
```

```html
<div id="editor"></div>
```

```js
const editorEl = document.getElementById("editor");
const editContext = new EditContext();
editorEl.editContext = editContext;

editContext.addEventListener("textupdate", (e) => {
  // Clear the current content.
  editorEl.innerHTML = "";

  const text = editContext.text;
  const { selectionStart, selectionEnd } = e;

  // Render the text before the selection.
  const textBefore = document.createElement("span");
  textBefore.textContent = text.substring(0, selectionStart);

  // Render the selected text, or caret.
  const textSelected = document.createElement("span");
  textSelected.classList.add("selection");
  textSelected.textContent = text.substring(selectionStart, selectionEnd);

  // Render the text after the selection.
  const textAfter = document.createElement("span");
  textAfter.textContent = text.substring(selectionEnd);

  editorEl.appendChild(textBefore);
  editorEl.appendChild(textSelected);
  editorEl.appendChild(textAfter);

  console.log(`Text before selection: ${textBefore.textContent}`);
  console.log(`Selected text: ${textSelected.textContent}`);
  console.log(`Text after selection: ${textAfter.textContent}`);
});
```

Specifications
--------------

| Specification |
| --- |
| EditContext API # dom-textupdateevent-selectionstart |

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

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


TextUpdateEvent: updateRangeEnd property - Web APIs

TextUpdateEvent: updateRangeEnd property
========================================

**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

The **`TextUpdateEvent.updateRangeEnd`** read-only property indicates the end position of the text range that is being replaced in the `EditContext` object.

Value
-----

A `Number`.

Examples
--------

### Using `textupdate` to display the inserted text and location

```html
<div id="editor"></div>
```

```js
const editorEl = document.getElementById("editor");
const editContext = new EditContext();
editorEl.editContext = editContext;

editContext.addEventListener("textupdate", (e) => {
  console.log(
    `The user inserted the text "${e.text}" between index ${e.updateRangeStart} and index ${e.updateRangeEnd}.`,
  );
});
```

Specifications
--------------

| Specification |
| --- |
| EditContext API # dom-textupdateevent-updaterangeend |

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

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


TextUpdateEvent: TextUpdateEvent() constructor - Web APIs

TextUpdateEvent: TextUpdateEvent() constructor
==============================================

**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

The **`TextUpdateEvent()`** constructor returns a new `TextUpdateEvent` object.

Syntax
------

```js
new TextUpdateEvent(type)
new TextUpdateEvent(type, options)
```

### Parameters

`type`

A string representing the type of the event. Possible values: `"textupdate"`.

`options` Optional

An optional object with the following properties:

`updateRangeStart`

A number representing the offset of the first character within the editable region text that needs to be updated.

`updateRangeEnd`

A number representing the offset of the last character within the editable region text that needs to be updated.

`text`

A string representing the text that needs to be inserted or deleted.

`selectionStart`

A number representing the offset of the selection start within the editable region text.

`selectionEnd`

A number representing the offset of the selection end within the editable region text.

`compositionStart`

A number representing the offset of the start of the composition within the editable region text.

`compositionEnd`

A number representing the offset of the end of the composition within the editable region text.

Specifications
--------------

| Specification |
| --- |
| EditContext API # dom-textupdateevent-constructor |

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

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

See also
--------

* The `TextUpdateEvent` interface it belongs to.


WorkletSharedStorage: keys() method - Web APIs

WorkletSharedStorage: keys() method
===================================

**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`keys()`** method of the
 `WorkletSharedStorage` interface returns an async iterator, which contains the keys for each item in a `WorkletSharedStorage` instance.

Syntax
------

```js
keys()
```

### Parameters

None.

### Return value

An array of the `WorkletSharedStorage`'s enumerable property keys.

### Exceptions

`TypeError`

Thrown if the calling site does not have the Shared Storage API included in a successful privacy sandbox enrollment process.

Examples
--------

```js
// keys() available inside a shared storage worklet module
const storage = await this.sharedStorage;

async function logKeys() {
  for await (const key of storage.keys()) {
    console.log(key);
  }
}
```

Specifications
--------------

| Specification |
| --- |
| Shared Storage API # worklet-shared-storage |

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

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

See also
--------

* Shared Storage API


WorkletSharedStorage: length() method - Web APIs

WorkletSharedStorage: length() method
=====================================

**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`length()`** method of the
 `WorkletSharedStorage` interface returns the number of entries currently stored in shared storage for the current origin.

Syntax
------

```js
length()
```

### Parameters

None.

### Return value

A `Promise` that fulfills with a number, which represents the total count of key-value pairs currently in the shared storage.

### Exceptions

`TypeError`

Thrown if:

* The worklet module has not yet been added with `addModule()`.
* The calling site does not have the Shared Storage API included in a successful privacy sandbox enrollment process.
* The browser fails to retrieve the number of entries for some other reason.

Examples
--------

```js
// length() available inside a shared storage worklet module

async function retrieveLength() {
  const length = await this.sharedStorage.length();
  console.log(length);
}
```

Specifications
--------------

| Specification |
| --- |
| Shared Storage API # dom-workletsharedstorage-length |

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

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

See also
--------

* Shared Storage API


WorkletSharedStorage: entries() method - Web APIs

WorkletSharedStorage: entries() method
======================================

**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`entries()`** method of the
 `WorkletSharedStorage` interface returns an async iterator. The iterator provides an array of `[key, value]` pairs corresponding to the enumerable properties of a `WorkletSharedStorage` instance. The order of these pairs is similar to that in a `for...in` loop, though a `for...in` loop also enumerates properties from the prototype chain.

Syntax
------

```js
entries()
```

### Parameters

None.

### Return value

An array of the `WorkletSharedStorage`'s enumerable property key-value pairs.

### Exceptions

`TypeError`

Thrown if the calling site does not have the Shared Storage API included in a successful privacy sandbox enrollment process.

Examples
--------

```js
// entries() available inside a shared storage worklet module
const storage = await this.sharedStorage;

async function logEntries() {
  for await (const [key, value] of storage.entries()) {
    console.log({ key, value });
  }
}
```

Specifications
--------------

| Specification |
| --- |
| Shared Storage API # worklet-shared-storage |

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

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

See also
--------

* Shared Storage API


WorkletSharedStorage: context property - Web APIs

WorkletSharedStorage: context property
======================================

**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

**Non-standard:** This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

The **`context`** read-only property of the `WorkletSharedStorage` interface contains contextual data passed into the shared storage worklet from the associated browsing context via the `FencedFrameConfig.setSharedStorageContext()` method.

Value
-----

A string representing the data. The value will match the latest value that was passed into the `FencedFrameConfig.setSharedStorageContext()` method prior to navigation to the `FencedFrameConfig`. If no value was set by `setSharedStorageContext()` prior to navigation, then `context` will return `undefined`.

Examples
--------

See the main `WorkletSharedStorage` page for an example.

Specifications
--------------

The `context` property is not currently defined in a specification.

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

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

See also
--------

* Shared Storage API


WorkletSharedStorage: remainingBudget() method - Web APIs

WorkletSharedStorage: remainingBudget() method
==============================================

**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`remainingBudget()`** method of the
 `WorkletSharedStorage` interface returns the remaining navigation budget for the current origin.

The navigation budget is the number of entropy bits permitted inside a `<fencedframe>` due to the `WindowSharedStorage.selectURL()` calls per origin every 24 hours. This is not the same as the number of navigations; rather, it is based on the number of potential navigations in each call. Each time a `selectURL()` navigation occurs, the corresponding origin's budget decreases by the logarithm (base 2) of the number of URL choices.

Navigation budget is a mechanism designed to limit the rate of leakage of cross-site data to the destination pages navigated to in fenced frames.

Syntax
------

```js
remainingBudget()
```

### Parameters

None.

### Return value

A `Promise` that fulfills with a number representing the remaining navigation budget.

### Exceptions

`TypeError`

Thrown if the worklet module has not yet been added with `addModule()` or if the calling site does not have the Shared Storage API included in a successful privacy sandbox enrollment process.

Examples
--------

```js
// remainingBudget() available inside a shared storage worklet module

async function retrieveBudget() {
  const budget = await this.sharedStorage.remainingBudget();
  console.log(budget);
}
```

Specifications
--------------

| Specification |
| --- |
| Shared Storage API # dom-workletsharedstorage-remainingbudget |

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

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

See also
--------

* Shared Storage API


WorkletSharedStorage: get() method - Web APIs

WorkletSharedStorage: get() method
==================================

**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`get()`** method of the
 `WorkletSharedStorage` interface retrieves a value from shared storage.

Syntax
------

```js
get(key)
```

### Parameters

`key`

A string representing the key of the key-value pair you want to retrieve.

### Return value

A `Promise` that fulfills with either a string equal to the value of the retrieved key-value pair or `undefined` if the specified `key` is not found in the shared storage.

### Exceptions

`TypeError`

Thrown if:

* The worklet module has not yet been added with `addModule()`.
* `key` exceeds the browser-defined maximum length.
* The calling site does not have the Shared Storage API included in a successful privacy sandbox enrollment process.

Examples
--------

### Measuring K+ frequency

The following example measures the K+ frequency of content views. Sometimes described as "effective frequency", K frequency refers to the minimum number of views before a user will recognize or recall certain content (often used in the context of ad views).

The main page script:

```js
// k-frequency-measurement.js

async function injectContent() {
  // Load the Shared Storage worklet
  await window.sharedStorage.worklet.addModule('k-freq-measurement-worklet.js');

  // Run the K-frequency measurement operation
  await window.sharedStorage.run('k-freq-measurement', { data: { kFreq: 3, contentId: 123 });
}

injectContent();
```

The worklet module is shown below:

```js
// k-frequency-measurement-worklet.js

// Scale factor for handling noise added to data
const SCALE\_FACTOR = 65536;

/\*\*
 \* The bucket key must be a number, and in this case, it is simply the content
 \* ID itself. For more complex bucket key construction, see other use cases in
 \* this demo.
 \*/
function convertContentIdToBucket(contentId) {
  return BigInt(contentId);
}

class KFreqMeasurementOperation {
  async run(data) {
    const { kFreq, contentId } = data;

    // Read from Shared Storage
    const hasReportedContentKey = "has-reported-content";
    const impressionCountKey = "impression-count";
    const hasReportedContent =
      (await this.sharedStorage.get(hasReportedContentKey)) === "true";
    const impressionCount = parseInt(
      (await this.sharedStorage.get(impressionCountKey)) || 0,
    );

    // Do not report if a report has been sent already
    if (hasReportedContent) {
      return;
    }

    // Check impression count against frequency limit
    if (impressionCount < kFreq) {
      await this.sharedStorage.set(impressionCountKey, impressionCount + 1);
      return;
    }

    // Generate the aggregation key and the aggregatable value
    const bucket = convertContentIdToBucket(contentId);
    const value = 1 \* SCALE\_FACTOR;

    // Send an aggregatable report via the Private Aggregation API
    privateAggregation.sendHistogramReport({ bucket, value });

    // Set the report submission status flag
    await this.sharedStorage.set(hasReportedContentKey, "true");
  }
}

// Register the operation
register("k-freq-measurement", KFreqMeasurementOperation);
```

For more details about this example, see K+ frequency measurement. See the Shared Storage API landing page for links to other examples.

Specifications
--------------

| Specification |
| --- |
| Shared Storage API # dom-workletsharedstorage-get |

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

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

See also
--------

* Shared Storage API
* Noise and scaling on developer.chrome.com (2023)


HTMLAllCollection: item() method - Web APIs

HTMLAllCollection: item() method
================================

The **`item()`** method of the `HTMLAllCollection` interface returns the element located at the specified offset into the collection, or the element with the specified value for its `id` or `name` attribute.

Syntax
------

```js
item(nameOrIndex)
```

### Parameters

`nameOrIndex`

If this parameter is an integer, or a string that can be converted to an integer, then it represents the position of the `Element` to be returned. Elements appear in an `HTMLAllCollection` in the same order in which they appear in the document's source. If the parameter is a string can't be converted to an integer, it will be interpreted as the `name` or `id` of the element to be returned.

### Return value

If `nameOrIndex` represents an index, `item()` returns the `Element` at the specified index, or `null` if `nameOrIndex` is less than zero or greater than or equal to the length property. If `nameOrIndex` represents a name, `item()` returns the same value as `namedItem()`.

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

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

See also
--------

* `HTMLCollection.item()`


HTMLAllCollection: namedItem() method - Web APIs

HTMLAllCollection: namedItem() method
=====================================

The **`namedItem()`** method of the `HTMLAllCollection` interface returns the first `Element` in the collection whose `id` or `name` attribute matches the specified name, or `null` if no element matches.

Syntax
------

```js
namedItem(name)
```

### Parameters

`name`

A string representing the value of the `id` or `name` attribute of the element we are looking for.

### Return value

The first `Element` in the `HTMLAllCollection` matching the `name`, or `null`, if there are none.

Specifications
--------------

| Specification |
| --- |
| HTML Standard # dom-htmlallcollection-nameditem |

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

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

See also
--------

* `HTMLAllCollection.namedItem()`


HTMLAllCollection: length property - Web APIs

HTMLAllCollection: length property
==================================

The **`HTMLAllCollection.length`** property returns the number of items in this `HTMLAllCollection`.

Value
-----

An integer value representing the number of items in this `HTMLAllCollection`.

Specifications
--------------

| Specification |
| --- |
| HTML Standard # dom-htmlallcollection-length |

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

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

See also
--------

* `HTMLCollection.length`


SharedStorageSelectURLOperation: run() method - Web APIs

SharedStorageSelectURLOperation: run() method
=============================================

**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

The **`run()`** method of the `SharedStorageSelectURLOperation` interface defines the structure to which the `run()` method defined inside a URL Selection output gate operation should conform.

Syntax
------

```js
run(urls, data)
```

### Parameters

`urls`

An array of objects representing the URLs to be chosen by the URL Selection operation. Each object contains two properties:

`url`

A string representing the URL.

`reportingMetadata` Optional

An object containing properties where names are event types and values are URLs pointing to reporting destinations, for example `"click" : "my-reports/report1.html"`. The URLs act as destinations for reports submitted with a destination of type `"shared-storage-select-url"`, typically submitted via a `Fence.reportEvent()` or `Fence.setReportEventDataForAutomaticBeacons()` method call.

`data`

An object representing any data required for executing the operation.

### Return value

A `Promise` that fulfills with a number defining the array index of the URL selected by the operation.

Examples
--------

See the main `SharedStorageSelectURLOperation` page for an example.

Specifications
--------------

| Specification |
| --- |
| Shared Storage API # dom-sharedstorageselecturloperation-run |

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

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

See also
--------

* Shared Storage API


WritableStreamDefaultController: error() method - Web APIs

WritableStreamDefaultController: error() method
===============================================

 The **`error()`** method of the
 `WritableStreamDefaultController` interface causes any future interactions
 with the associated stream to error.

 This method is rarely used, since usually it suffices to return a rejected promise from
 one of the underlying sink's methods. However, it can be useful for suddenly shutting
 down a stream in response to an event outside the normal lifecycle of interactions with
 the underlying sink.

Syntax
------

```js
error(message)
```

### Parameters

`message`

 A string representing the error you want future interactions to
 fail with.

### Return value

None (`undefined`).

### Exceptions

`TypeError`

The stream you are trying to error is not a `WritableStream`.

Examples
--------

```js
const writableStream = new WritableStream({
  start(controller) {
    // do stuff with controller

    // error stream if necessary
    controller.error("My error is broken");
  },
  write(chunk, controller) {
    // ...
  },
  close(controller) {
    // ...
  },
  abort(err) {
    // ...
  },
});
```

Specifications
--------------

| Specification |
| --- |
| Streams Standard # ref-for-ws-default-controller-error① |

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

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


WritableStreamDefaultController: signal property - Web APIs

WritableStreamDefaultController: signal property
================================================

The read-only **`signal`** property of the `WritableStreamDefaultController` interface returns the `AbortSignal` associated with the controller.

Value
-----

An `AbortSignal` object.

Examples
--------

### Aborting a long write operation

In this example, we simulate a slow operation using a local sink: We do nothing when some data is written but to wait for a second. This gives us enough time to call the `writer.abort()` method and to immediately reject the promise.

```js
const writingStream = new WritableStream({
  // Define the slow local sink to simulate a long operation
  write(controller) {
    return new Promise((resolve, reject) => {
      controller.signal.addEventListener("abort", () =>
        reject(controller.signal.reason),
      );

      // Do nothing but wait with the data: it is a local sink
      setTimeout(resolve, 1000); // Timeout to simulate a slow operation
    });
  },
});

// Perform the write
const writer = writingStream.getWriter();
writer.write("Lorem ipsum test data");

// Abort the write manually
await writer.abort("Manual abort!");
```

### Transferring the `AbortSignal` to the underlying layer

In this example, we use the Fetch API to actually send the message to a server. The Fetch API also support `AbortSignal`: It is possible to use the same object for both the `fetch` method and the `WritableStreamDefaultController`.

```js
const endpoint = "https://www.example.com/api"; // Fake URL for example purpose
const writingStream = new WritableStream({
  async write(chunk, controller) {
    // Write to the server using the Fetch API
    const response = await fetch(endpoint, {
      signal: controller.signal, // We use the same object for both fetch and controller
      method: "POST",
      body: chunk,
    });
    await response.text();
  },
});

// Perform the write
const writer = writingStream.getWriter();
writer.write("Lorem ipsum test data");

// Abort the write manually
await writer.abort("Manual abort!");
```

Specifications
--------------

| Specification |
| --- |
| Streams Standard # ref-for-ws-default-controller-signal① |

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

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


TextEncoderStream: writable property - Web APIs

TextEncoderStream: writable property
====================================

The **`writable`** read-only property of the `TextEncoderStream` interface returns a `WritableStream`.

Value
-----

A `WritableStream`.

Examples
--------

The following example demonstrates how to return a `WritableStream` from a `TextEncoderStream` object.

```js
stream = new TextEncoderStream();
console.log(stream.writable); // A WritableStream
```

Specifications
--------------

| Specification |
| --- |
| Streams Standard # dom-generictransformstream-writable |

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

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


TextEncoderStream: TextEncoderStream() constructor - Web APIs

TextEncoderStream: TextEncoderStream() constructor
==================================================

The **`TextEncoderStream()`** constructor creates a new `TextEncoderStream` object which is used to convert a stream of strings into bytes using UTF-8 encoding.

Syntax
------

```js
new TextEncoderStream()
```

### Parameters

None.

Examples
--------

In this example a `TextEncoderStream` is created and used to upload a stream of text.

```js
const body = textStream.pipeThrough(new TextEncoderStream());
fetch("/dest", {
  method: "POST",
  body,
  headers: { "Content-Type": "text/plain; charset=UTF-8" },
});
```

Specifications
--------------

| Specification |
| --- |
| Encoding Standard # ref-for-dom-textencoderstream① |

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

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


TextEncoderStream: readable property - Web APIs

TextEncoderStream: readable property
====================================

The **`readable`** read-only property of the `TextEncoderStream` interface returns a `ReadableStream`.

Value
-----

A `ReadableStream`.

Examples
--------

The following example demonstrates how to return a `ReadableStream` from a `TextEncoderStream` object.

```js
stream = new TextEncoderStream();
console.log(stream.readable); //a ReadableStream
```

Specifications
--------------

| Specification |
| --- |
| Streams Standard # dom-generictransformstream-readable |

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

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


TextEncoderStream: encoding property - Web APIs

TextEncoderStream: encoding property
====================================

 The **`encoding`** read-only property of the `TextEncoderStream` interface returns a
 string containing the name of the encoding algorithm used by the current `TextEncoderStream` object.

Value
-----

A string containing `utf-8` encoded data.

Examples
--------

The following example demonstrates how to return `encoding` from a `TextEncoderStream` object.

```js
stream = new TextEncoderStream();
console.log(stream.encoding);
```

Specifications
--------------

| Specification |
| --- |
| Encoding Standard # dom-textencoder-encoding |

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

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


HTMLDataElement: value property - Web APIs

HTMLDataElement: value property
===============================

 The **`value`** property of the `HTMLDataElement`
 interface returns a string reflecting the `value` HTML attribute.

Value
-----

A string.

Specifications
--------------

| Specification |
| --- |
| HTML Standard # dom-data-value |

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

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


RTCDTMFSender: insertDTMF() method - Web APIs

RTCDTMFSender: insertDTMF() method
==================================

 The **`insertDTMF()`** method on the `RTCDTMFSender` interface
 starts sending DTMF tones to the remote peer over the
 `RTCPeerConnection`.

 Sending of the tones is performed asynchronously,
 with `tonechange` events sent to the `RTCDTMFSender` every time
 a tone starts or ends.

 As long as the connection is active, you can send tones at any time. Calling
 `insertDTMF()` replaces any already-pending tones from the `toneBuffer`.
 You can abort sending queued tones by specifying an empty string (`""`) as the set of tones to play.
 Since `insertDTMF()` replaces the tone buffer, in order to add to the DTMF tones being played, it is necessary to call
 `insertDTMF` with a string containing both the remaining tones (stored in the `toneBuffer`) and the new tones appended together.

Syntax
------

```js
insertDTMF(tones)
insertDTMF(tones, duration)
insertDTMF(tones, duration, interToneGap)
```

### Parameters

`tones`

 A string containing the DTMF codes to be transmitted to the
 recipient. Specifying an empty string as the `tones` parameter clears the
 tone buffer, aborting any currently queued tones. A "," character inserts a two second
 delay.

`duration` Optional

 The amount of time, in milliseconds, that each DTMF tone should last. This value
 must be between 40 ms and 6000 ms (6 seconds), inclusive. The default is 100 ms.

`interToneGap` Optional

 The length of time, in milliseconds, to wait between tones. The browser will enforce
 a minimum value of 30 ms (that is, if you specify a lower value, 30 ms will be used
 instead); the default is 70 ms.

### Return value

None (`undefined`).

### Exceptions

`InvalidStateError` `DOMException`

 Thrown if the DTMF tones couldn't be sent because the track has been stopped or is in a
 read-only or inactive state.

`InvalidCharacterError` `DOMException`

Thrown if one or more of the characters in `tones` is not valid DTMF (0-9, A-Z, # or ,).

Examples
--------

tbd

Specifications
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-RTCDTMFSender-insertDTMF |

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

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

See also
--------

* WebRTC API
* Using DTMF with WebRTC
* `RTCPeerConnection`
* `RTCDTMFSender`
* `RTCRtpSender`


RTCDTMFSender: tonechange event - Web APIs

RTCDTMFSender: tonechange event
===============================

The **`tonechange`** event is sent to an `RTCDTMFSender` by the WebRTC API to indicate when DTMF tones previously queued for sending (by calling `RTCDTMFSender.insertDTMF()`) begin and end.

To determine what tone started playing, or if a tone stopped playing, check the value of the event's `tone` property.

This event is not cancelable and does not bubble.

Syntax
------

Use the event name in methods like `addEventListener()`, or set an event handler property.

```js
addEventListener("tonechange", (event) => {});

ontonechange = (event) => {};
```

Event type
----------

An `RTCDTMFToneChangeEvent`. Inherits from `Event`.

Event

RTCDTMFToneChangeEventEvent properties
----------------

*In addition to the properties of `Event`, this interface offers the following:*

`RTCDTMFToneChangeEvent.tone` Read only

A string specifying the tone which has begun playing, or an empty string (`""`) if the previous tone has finished playing.

Examples
--------

This example establishes a handler for the `tonechange` event which updates an element to display the currently playing tone in its content, or, if all tones have played, the string "<none>".

This can be done using `addEventListener()`:

```js
dtmfSender.addEventListener(
  "tonechange",
  (ev) => {
    let tone = ev.tone;
    if (tone === "") {
      tone = "<none>";
    }

    document.getElementById("playingTone").innerText = tone;
  },
  false,
);
```

You can also just set the `ontonechange` event handler property directly:

```js
dtmfSender.ontonechange = (ev) => {
  let tone = ev.tone;
  if (tone === "") {
    tone = "<none>";
  }

  document.getElementById("playingTone").innerText = tone;
};
```

Specifications
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # event-RTCDTMFSender-tonechange |

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

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


RTCDTMFSender: toneBuffer property - Web APIs

RTCDTMFSender: toneBuffer property
==================================

 The `RTCDTMFSender` interface's toneBuffer property returns a string
 containing a list of the DTMF tones currently queued for sending to the
 remote peer over the `RTCPeerConnection`. To place tones into the buffer,
 call `insertDTMF()`.

Tones are removed from the string as they're played, so only upcoming tones are listed.

Value
-----

 A string listing the tones to be played. If the string is empty,
 there are no tones pending.

### Exceptions

`InvalidCharacterError` `DOMException`

Thrown if a character is not a DTMF tone character (0-9, A-D, # or ,).

### Tone buffer format

 The tone buffer is a string which can contain any combination of the characters that
 are permitted by the DTMF standard.

#### DTMF tone characters

The digits 0-9

These characters represent the digit keys on a telephone keypad.

The letters A-D

 These characters represent the "A" through "D" keys which are part of the DTMF
 standard but not included on most telephones. These are *not* interpreted as
 digits. Lower-case "a"-"d" automatically gets converted to upper-case.

The pound/hash sign ("#") and the asterisk ("\*")

 These correspond to the similarly-labeled keys which are typically on the bottom row
 of the telephone keypad.

The comma (",")

 This character instructs the dialing process to pause for two seconds before sending
 the next character in the buffer.

**Note:** All other characters are unrecognized and will cause
 `insertDTMF()` to throw an
 `InvalidCharacterError` `DOMException`.

#### Using tone buffer strings

 For example, if you're writing code to control a voicemail system by sending DTMF
 codes, you might use a string such as "\*,1,5555". In this example, we would send "\*" to
 request access to the VM system, then, after a pause, send a "1" to start playback of
 voicemail messages, then after a pause, dial "5555" as a PIN number to open the
 messages.

 Setting the tone buffer to an empty string (`""`) cancels any pending DTMF
 codes.

Example
-------

tbd

Specifications
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-RTCDTMFSender-tonebuffer |

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

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

See also
--------

* WebRTC API
* Using DTMF with WebRTC
* `RTCDTMFSender.insertDTMF()`
* `RTCPeerConnection`
* `RTCDTMFSender`
* `RTCRtpSender`


CSSPageRule: style property - Web APIs

CSSPageRule: style property
===========================

The **`style`** read-only property of the `CSSPageRule` interface returns a `CSSStyleDeclaration` object. This represents an object that is a CSS declaration block, and exposes style information and various style-related methods and properties.

Value
-----

A `CSSStyleDeclaration` object, which represents a CSS declaration block with the following properties:

computed flag

Unset.

declarations

The declared declarations in the rule, in the order they were specified, shorthand properties expanded to longhands.

parent CSS rule

The context object, which is an alias for this.

owner node

Null.

Examples
--------

The stylesheet includes a `@page` rule. Getting a list of rules, then returning the value of the style property will return a `CSSStyleDeclaration` object.

```css
@page {
  margin: 1cm;
}
```

```js
let myRules = document.styleSheets[0].cssRules;
console.log(myRules[0].style); // returns a CSSStyleDeclaration object
```

Specifications
--------------

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssgroupingrule-style |

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

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


CSSPageRule: selectorText property - Web APIs

CSSPageRule: selectorText property
==================================

The **`selectorText`** property of the `CSSPageRule` interface gets and sets the selectors associated with the `CSSPageRule`.

Value
-----

A string.

Examples
--------

The stylesheet includes two `@page` rules. The `selectorText` property will return the literal selector text of `:first` as a string.

```css
@page {
  margin: 1cm;
}

@page :first {
  margin: 2cm;
}
```

```js
let myRules = document.styleSheets[0].cssRules; //returns two myRules
console.log(myRules[1].selectorText); // returns the string ":first"
```

Specifications
--------------

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssgroupingrule-selectortext |

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

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


FileSystem: root property - Web APIs

FileSystem: root property
=========================

 The read-only **`root`** property of the
 `FileSystem` interface specifies a `FileSystemDirectoryEntry`
 object representing the root directory of the file system, for use with the File and Directory Entries API.

Value
-----

 A `FileSystemDirectoryEntry` representing the file system's root
 directory.

Examples
--------

```js
// tbd
```

Specifications
--------------

| Specification |
| --- |
| File and Directory Entries API # dom-filesystem-root |

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

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

See also
--------

* File and Directory Entries API
* Introduction to the File and Directory Entries API
* `FileSystem`


FileSystem: name property - Web APIs

FileSystem: name property
=========================

 The read-only **`name`** property of the
 `FileSystem` interface indicates the file system's name. This
 string is unique among all file systems currently exposed by the File and Directory Entries API.

Value
-----

A string representing the file system's name.

Examples
--------

```js
// tbd
```

Specifications
--------------

| Specification |
| --- |
| File and Directory Entries API # dom-filesystem-name |

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

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

See also
--------

* File and Directory Entries API
* Introduction to the File and Directory Entries API
* `FileSystem`


HTMLDetailsElement: open property - Web APIs

HTMLDetailsElement: open property
=================================

 The **`open`** property of the
 `HTMLDetailsElement` interface is a boolean value reflecting the
 `open` HTML attribute, indicating whether the `<details>`'s contents (not counting the `<summary>`) is to be shown to the user.

Value
-----

A boolean value.

The boolean value represents the state of the `open` HTML attribute. The value of `true` means it is set with both the summary and the additional information shown to the user. The `false` value means it not set, with only the summary shown.

Specifications
--------------

| Specification |
| --- |
| HTML Standard # dom-details-open |

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

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

See also
--------

* The `<details>` and `<summary>` elements


HTMLDetailsElement: toggle event - Web APIs

HTMLDetailsElement: toggle event
================================

The **`toggle`** event fires when the `open`/`closed` state of a `<details>` element is toggled.

This event is not cancelable and does not bubble.

**Note:** The `toggle` event is also available in a different form on `HTMLElement`; this version fires on popover elements just after they are shown or hidden. See the `HTMLElement` `toggle event` page for more information.

Syntax
------

Use the event name in methods like `addEventListener()`, or set an event handler property.

```js
addEventListener("toggle", (event) => {});

ontoggle = (event) => {};
```

Event type
----------

A generic `Event`.

Examples
--------

This example logs chapters that are open. Chapters are removed from the log when they are closed.

### HTML

```html
<aside id="log">
  <p>Open chapters:</p>
  <div data-id="ch1" hidden>I</div>
  <div data-id="ch2" hidden>II</div>
  <div data-id="ch3" hidden>III</div>
</aside>
<section id="summaries">
  <p>Chapter summaries:</p>
  <details id="ch1">
    <summary>Chapter I</summary>
    Philosophy reproves Boethius for the foolishness of his complaints against
    Fortune. Her very nature is caprice.
  </details>
  <details id="ch2">
    <summary>Chapter II</summary>
    Philosophy in Fortune's name replies to Boethius' reproaches, and proves
    that the gifts of Fortune are hers to give and to take away.
  </details>
  <details id="ch3">
    <summary>Chapter III</summary>
    Boethius falls back upon his present sense of misery. Philosophy reminds him
    of the brilliancy of his former fortunes.
  </details>
</section>
```

### CSS

```css
body {
  display: flex;
  flex-direction: row-reverse;
}

#log {
  flex-shrink: 0;
  padding-left: 3em;
}

#summaries {
  flex-grow: 1;
}
```

### JavaScript

```js
function logItem(e) {
  const item = document.querySelector(`[data-id=${e.target.id}]`);
  item.toggleAttribute("hidden");
}

const chapters = document.querySelectorAll("details");
chapters.forEach((chapter) => {
  chapter.addEventListener("toggle", logItem);
});
```

### Result

Specifications
--------------

| Specification |
| --- |
| HTML Standard # event-toggle |

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

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


GPUBuffer: mapAsync() method - Web APIs

GPUBuffer: mapAsync() method
============================

**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`mapAsync()`** method of the
 `GPUBuffer` interface maps the specified range of the `GPUBuffer`. It returns a `Promise` that resolves when the `GPUBuffer`'s content is ready to be accessed. While the `GPUBuffer` is mapped it cannot be used in any GPU commands.

Once the buffer is successfully mapped (which can be checked via `GPUBuffer.mapState`), calls to `GPUBuffer.getMappedRange()` will return an `ArrayBuffer` containing the `GPUBuffer`'s current values, to be read and updated by JavaScript as required.

When you have finished working with the `GPUBuffer` values, call `GPUBuffer.unmap()` to unmap it, making it accessible to the GPU again.

Syntax
------

```js
mapAsync(mode)
mapAsync(mode, offset, size)
```

### Parameters

`mode`

A bitwise flag that specifies whether the `GPUBuffer` is mapped for reading or writing. Possible values are:

`GPUMapMode.READ`

The `GPUBuffer` is mapped for reading. Values can be read, but any changes made to the `ArrayBuffer` returned by `GPUBuffer.getMappedRange()` will be discarded once `GPUBuffer.unmap()` is called.

Read-mode mapping can only be used on `GPUBuffer`s that have a usage of `GPUBufferUsage.MAP_READ` set on them (i.e. when created with `GPUDevice.createBuffer()`).

`GPUMapMode.WRITE`

The `GPUBuffer` is mapped for writing. Values can be read and updated — any changes made to the `ArrayBuffer` returned by `GPUBuffer.getMappedRange()` will be saved to the `GPUBuffer` once `GPUBuffer.unmap()` is called.

Write-mode mapping can only be used on `GPUBuffer`s that have a usage of `GPUBufferUsage.MAP_WRITE` set on them (i.e. when created with `GPUDevice.createBuffer()`).

`offset` Optional

A number representing the offset, in bytes, from the start of the buffer to the start of the range to be mapped. If `offset` is omitted, it defaults to 0.

`size` Optional

A number representing the size, in bytes, of the range to be mapped. If `size` is omitted, the range mapped extends to the end of the `GPUBuffer`.

### Return value

A `Promise` that resolves to `Undefined` when the `GPUBuffer`'s content is ready to be accessed.

### Validation

The following criteria must be met when calling **`mapSync()`**, otherwise an `OperationError` `DOMException` is thrown, the promise is rejected, and a `GPUValidationError` is generated:

* `offset` is a multiple of 8.
* The total range to be mapped (`size` if specified, or `GPUBuffer.size` - `offset` if not) is a multiple of 4.
* The total range to be mapped is inside the bounds of the `GPUBuffer`.
* If mode is `GPUMapMode.READ`, the `GPUBuffer` has a usage of `GPUBufferUsage.MAP_READ`.
* If mode is `GPUMapMode.WRITE`, the `GPUBuffer` has a usage of `GPUBufferUsage.MAP_WRITE`.
Examples
--------

See the main `GPUBuffer` page for an example.

Specifications
--------------

| Specification |
| --- |
| WebGPU # dom-gpubuffer-mapasync |

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

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

See also
--------

* The WebGPU API


GPUBuffer: label property - Web APIs

GPUBuffer: label property
=========================

**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`label`** property of the
 `GPUBuffer` interface provides a label that can be used to identify the object, for example in `GPUError` messages or console warnings.

This can be set by providing a `label` property in the descriptor object passed into the originating `GPUDevice.createBuffer()` call, or you can get and set it directly on the `GPUBuffer` object.

Value
-----

A string. If this has not been previously set as described above, it will be an empty string.

Examples
--------

Setting and getting a label via `GPUBuffer.label`:

```js
const output = device.createBuffer({
  size: BUFFER\_SIZE,
  usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY\_SRC,
});

output.label = "mybuffer";

console.log(output.label); // "mybuffer"
```

Setting a label via the originating `GPUDevice.createBuffer()` call, and then getting it via `GPUBuffer.label`:

```js
const output = device.createBuffer({
  size: BUFFER\_SIZE,
  usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY\_SRC,
  label: "mybuffer",
});

console.log(output.label); // "mybuffer"
```

Specifications
--------------

| Specification |
| --- |
| WebGPU # dom-gpuobjectbase-label |

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

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

See also
--------

* The WebGPU API


GPUBuffer: usage property - Web APIs

GPUBuffer: usage property
=========================

**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`usage`** read-only property of the
 `GPUBuffer` interface contains the bitwise flags representing the allowed usages of the `GPUBuffer`.

`usage` is set via the `usage` property in the descriptor object passed into the originating `GPUDevice.createBuffer()` call.

Value
-----

The bitwise flags representing the original usages set when the `GPUBuffer` was first created. The returned number is the sum of decimal values representing the different flags, as seen in the table below.

| Bitwise flag | Usage description | Hex equiv. | Decimal equiv. |
| --- | --- | --- | --- |
| `GPUBufferUsage.COPY_SRC` | The buffer can be used as the source of a copy operation, for example the source argument of a `copyBufferToBuffer()` call. | 0x0004 | 4 |
| `GPUBufferUsage.COPY_DST` | The buffer can be used as the destination of a copy/write operation, for example the destination argument of a `copyTextureToBuffer()` call. | 0x0008 | 8 |
| `GPUBufferUsage.INDEX` | The buffer can be used as an index buffer, for example as the `buffer` argument passed to `setIndexBuffer()`. | 0x0010 | 16 |
| `GPUBufferUsage.INDIRECT` | The buffer can be used to store indirect command arguments, for example as the `indirectBuffer` argument of a `drawIndirect()` or `dispatchWorkgroupsIndirect()` call. | 0x0100 | 256 |
| `GPUBufferUsage.MAP_READ` | The buffer can be mapped for reading, for example when calling `mapAsync()` with a `mode` of `GPUMapMode.READ`. This flag may only be combined with `GPUBufferUsage.COPY_DST`. | 0x0001 | 1 |
| `GPUBufferUsage.MAP_WRITE` | The buffer can be mapped for writing, for example when calling `mapAsync()` with a `mode` of `GPUMapMode.WRITE`. This flag may only be combined with `GPUBufferUsage.COPY_SRC`. | 0x0002 | 2 |
| `GPUBufferUsage.QUERY_RESOLVE` | The buffer can be used to capture query results, for example as the destination argument of a `resolveQuerySet()` call. | 0x0200 | 512 |
| `GPUBufferUsage.STORAGE` | The buffer can be used as a storage buffer, for example as a resource in a bind group entry when creating a `GPUBindGroup` (via `createBindGroup()`), which adheres to a `GPUBindGroupLayout` entry with a buffer binding layout `type` of `"storage"` or `"read-only-storage"`. | 0x0080 | 128 |
| `GPUBufferUsage.UNIFORM` | The buffer can be used as a uniform buffer, for example as a resource in a bind group entry when creating a `GPUBindGroup` (via `createBindGroup()`), which adheres to a `GPUBindGroupLayout` entry with a buffer binding layout `type` of `"uniform"`. | 0x0040 | 64 |
| `GPUBufferUsage.VERTEX` | The buffer can be used as a vertex buffer, for example as the `buffer` argument passed to `setVertexBuffer()`. | 0x0020 | 32 |

Examples
--------

```js
const output = device.createBuffer({
  size: BUFFER\_SIZE,
  usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY\_SRC,
});

console.log(output.usage); // 132

const stagingBuffer = device.createBuffer({
  size: BUFFER\_SIZE,
  usage: GPUBufferUsage.MAP\_READ | GPUBufferUsage.COPY\_DST,
});

console.log(stagingBuffer.usage); // 9
```

Specifications
--------------

| Specification |
| --- |
| WebGPU # dom-gpubuffer-usage |

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

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

See also
--------

* The WebGPU API


GPUBuffer: unmap() method - Web APIs

GPUBuffer: unmap() method
=========================

**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`unmap()`** method of the
 `GPUBuffer` interface unmaps the mapped range of the `GPUBuffer`, making its contents available for use by the GPU again after it has previously been mapped with `GPUBuffer.mapAsync()` (the GPU cannot access a mapped `GPUBuffer`).

When `unmap()` is called, any `ArrayBuffer`s created via `GPUBuffer.getMappedRange()` are detached.

Syntax
------

```js
unmap()
```

### Parameters

None.

### Return value

None (`Undefined`).

Examples
--------

See the main `GPUBuffer` page for an example.

Specifications
--------------

| Specification |
| --- |
| WebGPU # dom-gpubuffer-unmap |

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

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

See also
--------

* The WebGPU API


GPUBuffer: size property - Web APIs

GPUBuffer: size property
========================

**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`size`** read-only property of the
 `GPUBuffer` interface represents the length of the `GPUBuffer`'s memory allocation, in bytes.

`size` is set via the `size` property in the descriptor object passed into the originating `GPUDevice.createBuffer()` call.

Value
-----

A number.

Examples
--------

```js
// Define global buffer size
const BUFFER\_SIZE = 1000;

// ...

const output = device.createBuffer({
  size: BUFFER\_SIZE,
  usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY\_SRC,
});

console.log(output.size); // 1000
```

Specifications
--------------

| Specification |
| --- |
| WebGPU # dom-gpubuffer-size |

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

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

See also
--------

* The WebGPU API


GPUBuffer: mapState property - Web APIs

GPUBuffer: mapState property
============================

**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`mapState`** read-only property of the
 `GPUBuffer` interface represents the mapped state of the `GPUBuffer`.

Value
-----

An enumerated value. Possible values are:

`unmapped`

The buffer is not mapped. `GPUBuffer.getMappedRange()` cannot be used to access the contents of the `GPUBuffer` in JavaScript. This could be because:

* `GPUBuffer.mapAsync()` has not yet been called.
* The `GPUBuffer` was previously mapped, and then unmapped again with `GPUBuffer.unmap()`.

`pending`

The buffer is not yet mapped. `GPUBuffer.mapAsync()` has been called, but its `Promise` is currently pending. `GPUBuffer.getMappedRange()` cannot currently be used to access the contents of the `GPUBuffer` in JavaScript.

`mapped`

The buffer is mapped. The `GPUBuffer.mapAsync()` `Promise` has fulfilled, and `GPUBuffer.getMappedRange()` can now be used to access the contents of the `GPUBuffer` in JavaScript.

Examples
--------

```js
const stagingBuffer = device.createBuffer({
  size: BUFFER\_SIZE,
  usage: GPUBufferUsage.MAP\_READ | GPUBufferUsage.COPY\_DST,
});

console.log(stagingBuffer.mapState); // "unmapped"

// ...

await stagingBuffer.mapAsync(
  GPUMapMode.READ,
  0, // Offset
  BUFFER\_SIZE, // Length
);

console.log(stagingBuffer.mapState); // "mapped"
```

Specifications
--------------

| Specification |
| --- |
| WebGPU # dom-gpubuffer-mapstate |

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

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

See also
--------

* The WebGPU API


GPUBuffer: getMappedRange() method - Web APIs

GPUBuffer: getMappedRange() method
==================================

**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`getMappedRange()`** method of the
 `GPUBuffer` interface returns an `ArrayBuffer` containing the mapped contents of the `GPUBuffer` in the specified range.

This can only happen once the `GPUBuffer` has been successfully mapped with `GPUBuffer.mapAsync()` (this can be checked via `GPUBuffer.mapState`). While the `GPUBuffer` is mapped it cannot be used in any GPU commands.

When you have finished working with the `GPUBuffer` values, call `GPUBuffer.unmap()` to unmap it, making it accessible to the GPU again.

Syntax
------

```js
getMappedRange()
getMappedRange(offset)
getMappedRange(offset, size)
```

### Parameters

`offset` Optional

A number representing the offset, in bytes, from the start of the `GPUBuffer`'s mapped range to the start of the range to be returned in the `ArrayBuffer`. If `offset` is omitted, it defaults to 0.

`size` Optional

A number representing the size, in bytes, of the `ArrayBuffer` to return. If `size` is omitted, the range extends to the end of the `GPUBuffer`'s mapped range.

### Return value

An `ArrayBuffer`.

### Validation

The following criteria must be met when calling **`getMappedRange()`**, otherwise an `OperationError` `DOMException` is thrown:

* `offset` is a multiple of 8.
* The total range to be mapped (`size` if specified, or mapped range length - `offset` if not) is a multiple of 4.
* The total range is inside the bounds of the mapped range and does not overlap with the `ArrayBuffer` ranges specified by any other active `getMappedRange()` calls.
### Exceptions

`TypeError` `DOMException`

Thrown if an attempt is made to detach the `ArrayBuffer` in any way other than via `GPUBuffer.unmap()`.

Examples
--------

See the main `GPUBuffer` page for an example.

Specifications
--------------

| Specification |
| --- |
| WebGPU # dom-gpubuffer-getmappedrange |

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

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

See also
--------

* The WebGPU API


GPUBuffer: destroy() method - Web APIs

GPUBuffer: destroy() method
===========================

**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`destroy()`** method of the
 `GPUBuffer` interface destroys the `GPUBuffer`.

Syntax
------

```js
destroy()
```

### Parameters

None.

### Return value

None (`Undefined`).

Examples
--------

```js
const output = device.createBuffer({
  size: 1000,
  usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY\_SRC,
});

// some time later

output.destroy();
```

Specifications
--------------

| Specification |
| --- |
| WebGPU # dom-gpubuffer-destroy |

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

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

See also
--------

* The WebGPU API


MediaMetadata: artwork property - Web APIs

MediaMetadata: artwork property
===============================

 The **`artwork`** property of the
 `MediaMetaData` interface returns or sets an array of
 objects representing images associated with playing
 media.

Value
-----

An `Array` of objects, each containing the following fields:

`src`

The URL from which the user agent fetches the image's data.

`sizes` Optional

Specifies the resource in multiple sizes so the user agent doesn't have to scale a single image. It defaults to the empty string (`""`).

`type` Optional

The MIME type hint for the user agent that allows it to ignore images of types that it doesn't support. However, the user agent may still use MIME type sniffing after downloading the image to determine its type. It defaults to the empty string (`""`).

Examples
--------

 The following example checks for browser compatibility and sets the current metadata
 for the media session.

```js
if ("mediaSession" in navigator) {
  navigator.mediaSession.metadata = new MediaMetadata({
    title: "Unforgettable",
    artist: "Nat King Cole",
    album: "The Ultimate Collection (Remastered)",
    artwork: [
      {
        src: "https://dummyimage.com/96x96",
        sizes: "96x96",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/128x128",
        sizes: "128x128",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/192x192",
        sizes: "192x192",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/256x256",
        sizes: "256x256",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/384x384",
        sizes: "384x384",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/512x512",
        sizes: "512x512",
        type: "image/png",
      },
    ],
  });
}
```

Specifications
--------------

| Specification |
| --- |
| Media Session # dom-mediametadata-artwork |

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

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