FontFaceSet: loadingerror event - Web APIs

FontFaceSet: loadingerror event
===============================

The `loadingerror` event fires when fonts have finished loading, but some or all fonts have failed to load.

Syntax
------

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

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

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

Example
-------

In the following example, if the font `Ephesis` fails to load, "Font loading error" is printed to the console.

```js
document.fonts.onloadingerror = () => {
  console.log("Font loading error");
};

(async () => {
  await document.fonts.load("16px Ephesis");
})();
```

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

| Specification |
| --- |
| CSS Font Loading Module Level 3 # dom-fontfaceset-onloadingerror |

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

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


FontFaceSet: size property - Web APIs

FontFaceSet: size property
==========================

The **`size`** property of the `FontFaceSet` interface returns the number of items in the `FontFaceSet`.

Value
-----

An integer indicating the number of items in the `FontFaceSet`.

Examples
--------

In the following example the `size` of the `FontFaceSet` is printed to the console.

```js
console.log(document.fonts.size);
```

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

#### No specification found

No specification data found for `api.FontFaceSet.size`.
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.


FontFaceSet: keys() method - Web APIs

FontFaceSet: keys() method
==========================

The **`keys()`** method of the `FontFaceSet` interface is an alias for `FontFaceSet.values`.

Syntax
------

```js
keys()
```

### Parameters

None.

### Return value

A new iterator object containing the values for each element in the given `FontFaceSet`, in insertion order.

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

#### No specification found

No specification data found for `api.FontFaceSet.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.


FontFaceSet: delete() method - Web APIs

FontFaceSet: delete() method
============================

The **`delete()`** method of the `FontFaceSet` interface removes a font from the set.

Font faces that were added to the set using the CSS `@font-face` rule remain connected to the corresponding CSS, and cannot be deleted.

Syntax
------

```js
delete(font)
```

### Parameters

`font`

A `FontFace` to be removed from the set.

### Return value

A boolean value which is `true` if the deletion was successful, and `false` otherwise.

Examples
--------

In the following example a new `FontFace` object is created and then deleted from the `FontFaceSet`.

```js
const font = new FontFace("MyFont", "url(myFont.woff2)");
document.fonts.delete(font);
```

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

| Specification |
| --- |
| CSS Font Loading Module Level 3 # dom-fontfaceset-delete |

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

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


FontFaceSet: status property - Web APIs

FontFaceSet: status property
============================

The **`status`** read-only property of the `FontFaceSet` interface returns the loading state of the fonts in the set.

Value
-----

One of:

* `"loading"`
* `"loaded"`
Examples
--------

In the following example the `status` of the `FontFaceSet` is printed to the console.

```js
console.log(document.fonts.status);
```

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

| Specification |
| --- |
| CSS Font Loading Module Level 3 # dom-fontfaceset-status |

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

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


CSSMathMax: values property - Web APIs

CSSMathMax: values property
===========================

 The CSSMathMax.values read-only property of the
 `CSSMathMax` interface returns a `CSSNumericArray` object
 which contains one or more `CSSNumericValue` objects.

Value
-----

A `CSSNumericArray`.

Examples
--------

To do

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

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-cssmathmax-values |

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

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


CSSMathMax: CSSMathMax() constructor - Web APIs

CSSMathMax: CSSMathMax() constructor
====================================

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

 The **`CSSMathMax()`** constructor creates a
 new `CSSMathMax` object which represents the CSS `max()` function.

Syntax
------

```js
new CSSMathMax(args)
```

### Parameters

`args`

 A list of values for the `CSSMathProduct` object to be either a double
 integer or a `CSSNumericValue`.

### Exceptions

`TypeError`

Thrown if there is a *failure* when adding all of the values in args.

Examples
--------

To do

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

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

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

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


ReportingObserver: takeRecords() method - Web APIs

ReportingObserver: takeRecords() method
=======================================

 The **`takeRecords()`** method of the
 `ReportingObserver` interface returns the current list of reports contained
 in the observer's report queue, and empties the queue.

Syntax
------

```js
takeRecords()
```

### Parameters

None.

### Return value

An array of `Report` objects.

Examples
--------

```js
const options = {
  types: ["deprecation"],
  buffered: true,
};

const observer = new ReportingObserver((reports, observer) => {
  reportBtn.onclick = () => displayReports(reports);
}, options);

observer.observe();

// …

const records = observer.takeRecords();
console.log(records);
```

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

| Specification |
| --- |
| Reporting API # dom-reportingobserver-takerecords |

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

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

See also
--------

* Reporting API


ReportingObserver: ReportingObserver() constructor - Web APIs

ReportingObserver: ReportingObserver() constructor
==================================================

 The **`ReportingObserver()`** constructor of the Reporting API creates a new
 `ReportingObserver` object instance, which can be used to collect and
 access reports.

Syntax
------

```js
new ReportingObserver(callback)
new ReportingObserver(callback, options)
```

### Parameters

`callback`

 A callback function that runs when the observer starts to collect reports (i.e. via
 `ReportingObserver.observe()`). The callback function is given two
 parameters:

`reports`

 A sequence of `Report` objects representing
 the reports collected in the observer's report queue. This is probably the most
 common way to retrieve the reports.

`observer`

 A reference to the same `ReportingObserver`
 object, allowing for recursive report collection, etc.

`options` Optional

An object allowing you to set the options for creating the object. The available options are:

`types`

 An array of strings representing the types of report to be
 collected by this observer. Available types include `deprecation`,
 `intervention`, and `crash` (although this last type usually
 isn't retrievable via a `ReportingObserver`). If this option is omitted, all supported types are collected.

`buffered`

 a boolean that defines whether the reports that were
 generated before the observer was able to be created should be observable
 (`true`) or not (`false`).

Examples
--------

```js
const options = {
  types: ["deprecation"],
  buffered: true,
};

const observer = new ReportingObserver((reports, observer) => {
  reportBtn.onclick = () => displayReports(reports);
}, options);
```

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

| Specification |
| --- |
| Reporting API # dom-reportingobserver-reportingobserver |

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

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

See also
--------

* Reporting API


ReportingObserver: disconnect() method - Web APIs

ReportingObserver: disconnect() method
======================================

 The **`disconnect()`** method of the
 `ReportingObserver` interface stops a reporting observer that had
 previously started observing from collecting reports.

 After calling `disconnect()`, neither
 `ReportingObserver.takeRecords()` nor the `records` parameter of
 the
 `ReportingObserver()`
 callback will return any reports. The associated observer will no longer be active.

Syntax
------

```js
disconnect()
```

### Parameters

None.

### Return value

None (`undefined`).

Examples
--------

```js
const options = {
  types: ["deprecation"],
  buffered: true,
};

const observer = new ReportingObserver((reports, observer) => {
  reportBtn.onclick = () => displayReports(reports);
}, options);

observer.observe();

// ...

observer.disconnect();
```

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

| Specification |
| --- |
| Reporting API # dom-reportingobserver-disconnect |

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

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

See also
--------

* Reporting API


ReportingObserver: observe() method - Web APIs

ReportingObserver: observe() method
===================================

 The **`observe()`** method of the
 `ReportingObserver` interface instructs a reporting observer to start
 collecting reports in its report queue.

Syntax
------

```js
observe()
```

### Parameters

None.

### Return value

None (`undefined`).

Examples
--------

```js
const options = {
  types: ["deprecation"],
  buffered: true,
};

const observer = new ReportingObserver((reports, observer) => {
  reportBtn.onclick = () => displayReports(reports);
}, options);

observer.observe();
```

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

| Specification |
| --- |
| Reporting API # dom-reportingobserver-observe |

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

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

See also
--------

* Reporting API


XRInputSource: targetRaySpace property - Web APIs

XRInputSource: targetRaySpace property
======================================

 The read-only `XRInputSource` property
 **`targetRaySpace`** returns an `XRSpace`
 (typically an `XRReferenceSpace`) representing the position and
 orientation of the target ray in the virtual space. Its native origin tracks
 the position of the origin point of the target ray, and its orientation indicates the
 orientation of the controller device itself. These values, interpreted in the context of
 the input source's `targetRayMode`, can be
 used both to fully interpret the device as an input source.

 To obtain an `XRSpace` representing the input controller's position and
 orientation in virtual space, use the `gripSpace` property.

Value
-----

 An `XRSpace` object—typically an `XRReferenceSpace` or
 `XRBoundedReferenceSpace`—which represents the position and orientation of
 the input controller's target ray in virtual space.

 The native origin of the returned `XRSpace` is located at the point from
 which the target ray is emitted, and the orientation of the space indicates the
 direction in which the target ray is pointing.

Usage notes
-----------

 All input sources—regardless of their `targetRayMode`—have a valid `targetRaySpace`. The exact meaning of this
 space varies, however, depending on the mode:

* Every gaze input (`targetRayMode` value of `gaze`), shares the
 same `XRSpace` object as their target ray space, since the gaze input
 comes from the viewer's head. This shared space represents the same location as the
 space returned by the `XRSession` method
 `requestReferenceSpace()`, but is
 maintained as a different object to allow for future enhancements to the API.
* The target ray space reported by tracked pointer inputs (`targetRayMode`
 of `tracked-pointer`) is actually based upon the true spatial position and
 orientation of the input device.

 To determine the position and orientation of the target ray while rendering a frame,
 pass it into the `XRFrame` method `getPose()` method, then use the returned `XRPose` object's
 `transform` to gather the spatial information you need.

Examples
--------

This fragment of code shows part of a function to be called once every frame. It looks for inputs which have a non-`null` `targetRaySpace`. Inputs which have a value for this property represent inputs that project a target ray outward from the user.

For each such input, this example looks for inputs whose `targetRayMode` is `tracked-pointer`, indicating that the input is in fact intended to represent a targeting device rather than a gazing device, screen tap, or mouse click. For tracked pointers, a function `myRenderTargetRayAsBeam()` is called to render a beam from the input controller's virtual position outward in the direction it's pointing.

The code should continue to perform tasks such as drawing controllers or any objects representative of the user's hands' positions in the virtual space, as well as any other input-related tasks.

```js
function updateInputSources(session, frame, refSpace) {
  for (const source of session.getInputSources()) {
    const targetRayPose = frame.getPose(inputSource.targetRaySpace, refSpace);

    if (targetRayPose) {
      if (source.targetRayMode === "tracked-pointer") {
        myRenderTargetRayAsBeam(targetRayPose);
      }
    }

    // …
  }
}
```

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

| Specification |
| --- |
| WebXR Device API # dom-xrinputsource-targetrayspace |

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

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

See also
--------

* WebXR Device API
* Inputs and input sources
* Using gamepads in WebXR applications


XRInputSource: hand property - Web APIs

XRInputSource: hand property
============================

The read-only **`hand`** property of the `XRInputSource` interface is a `XRHand` object providing access to a hand-tracking device.

Value
-----

An `XRHand` object or `null` if the `XRSession` has not been requested with the `hand-tracking` feature descriptor.

Examples
--------

```js
navigator.xr
  .requestSession({ optionalFeatures: ["hand-tracking"] })
  .then(/\* … \*/);

function renderFrame(session, frame) {
  // …

  for (const inputSource of session.inputSources) {
    if (inputSource.hand) {
      // render a hand model, perform gesture detection, etc.
    }
  }
}
```

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

| Specification |
| --- |
| WebXR Hand Input Module - Level 1 # dom-xrinputsource-hand |

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

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

See also
--------

* `XRHand`


XRInputSource: gripSpace property - Web APIs

XRInputSource: gripSpace property
=================================

The read-only `XRInputSource` property **`gripSpace`** returns an `XRSpace` whose native origin tracks the pose used to render virtual objects so they appear to be held in (or part of) the user's hand. For example, if a user were holding a virtual straight rod, the native origin of this `XRSpace` would be located at the approximate center of mass of the user's fist.

Value
-----

 An `XRSpace` object representing the position and orientation of the input
 device in virtual space, suitable for rendering an image of the device into the scene.
 `gripSpace` is `null` if the input source is inherently
 untrackable. For example, only inputs whose `targetRayMode` is `tracked-pointer` provide a `gripSpace`.

 Imagine that the controller is shaped like a straight rod, held in the user's fist. The
 native origin of the grip space is located at the centroid—the center of mass—of the
 user's fist, tracking the position of the user's hand.

**The coordinate system for the left hand's grip space.**

![A diagram showing how the grip space indicates the local coordinate system for the player's hand relative to the world.](/en-US/docs/Web/API/XRInputSource/gripSpace/gripspace-lefthand-light.svg)

**The coordinate system for the right hand's grip space.**

![A diagram showing how the grip space indicates the local coordinate system for the player's hand relative to the world.](/en-US/docs/Web/API/XRInputSource/gripSpace/gripspace-righthand-light.svg)

As shown in the diagram above, the coordinate system is oriented as follows:

* The x-axis is perpendicular to the palm of the user's hand, with the direction
 extending outward from the back of the hand being +X if the controller is in the
 user's right hand or -X if the controller is in the left hand.
* The z-axis along the length of the rod, parallel to the user's palm and along the
 length of their grip. -Z is in the direction of the user's thumb, and +Z is in the
 opposite direction.
* The y-axis is implied by the relationship between the other two axes; as is always
 the case, it's the cross product of the other two axes (lying 90° away from both the X
 and Z axes).
Examples
--------

 In tis example, taken from the frame rendering callback, the `gripSpace` is
 used to render a mesh that represents the position and orientation of the controller in
 the virtual environment.

```js
for (const source in xrSession.inputSources) {
  if (source.gripSpace) {
    const gripPose = frame.getPose(source.gripSpace, xrRefSpace);

    if (gripPose) {
      myDrawMeshUsingTransform(controllerMesh, gripPose.transform.matrix);
    }
  }
}
```

 For each input source which has a value for `gripSpace`, this loop obtains
 the `XRPose` representing the position and orientation that are described
 by `gripSpace`. If a valid pose is returned, a method
 `myDrawMeshUsingTransform()` is called to draw the controller's mesh
 transformed using the grip pose's transform matrix.

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

| Specification |
| --- |
| WebXR Device API # dom-xrinputsource-gripspace |

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

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


XRInputSource: profiles property - Web APIs

XRInputSource: profiles property
================================

The read-only `XRInputSource` property **`profiles`** returns an array of strings, each describing a configuration profile for the input source. The profile strings are listed in order of specificity, with the most specific profile listed first.

**Note:** The `profiles` list is always empty when the WebXR
 session is in inline mode.

Value
-----

 An array of strings, each describing one configuration profile
 for the input device represented by the `XRInputSource` object. Each input
 profile specifies the preferred visual representation and behavior of the input source.

### Input profile names

 An input profile name is a string describing a visual representation and behavior the
 input source may be configured to use. Each string:

* Has no spaces; instead, words are separated by hyphen ("-") characters
* If the platform makes it available, the USB vendor and product ID may be provided
 but cannot be relied upon
* Does not uniquely identify a specific device; rather, it identifies a configuration
 that the product is capable of using
* Does not provide information about handedness of the device, if applicable

 The WebXR Input Profiles Registry is used by device developers and browser developers to
 attempt to ensure that a given device will report the same profile strings regardless of
 which browser or other user agent you use.

### Generic input profile names

The following input profile names are generic and can serve as fallbacks that describe the devices in the roughest sense.

* generic-button
* generic-hand-select-grasp
* generic-hand-select
* generic-hand
* generic-touchpad
* generic-touchscreen
* generic-trigger-squeeze-thumbstick
* generic-trigger-squeeze-touchpad-thumbstick
* generic-trigger-squeeze-touchpad
* generic-trigger-squeeze
* generic-trigger-thumbstick
* generic-trigger-touchpad-thumbstick
* generic-trigger-touchpad
* generic-trigger
Examples
--------

The list in `profiles` is in order of reverse specificity; that is, the most precise description is first, and the least precise description is last. The first entry in the list is typically indicative of the precise model of the controller, or of a model with which the controller is compatible.

For example, entry 0 in `profiles` for an Oculus Touch controller is `oculus-touch`. The next entry is `generic-trigger-squeeze-thumbstick`, indicating a generic device with a trigger, a squeeze control, and a thumbstick. While the Oculus Touch controller actually has a thumbpad rather than a thumbstick, the overall description is "close enough" that the details within the profile matching the name will let the controller be interpreted usefully.

```js
inputSource.profiles;
// ['oculus-touch', 'generic-trigger-squeeze-thumbstick']
```

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

| Specification |
| --- |
| WebXR Device API # dom-xrinputsource-profiles |

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

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

See also
--------

* WebXR Device API
* Inputs and input sources


XRInputSource: handedness property - Web APIs

XRInputSource: handedness property
==================================

 The read-only `XRInputSource` property
 **`handedness`** indicates which of the user's hands the WebXR
 input source is associated with, or if it's not associated with a hand at all.

Value
-----

 A string indicating whether the input controller is held in one of
 the user's hands, and if it is, which hand. The value is one of the following:

`none`

The input controller is not associated with one of the user's hands.

`left`

The input controller is being held in, worn on, or is attached to the user's left hand.

`right`

The input controller is being held in, worn on, or is attached to the user's right hand.

Usage notes
-----------

 If the input source is not a device associated with a user's hand (whether by being
 held, attached, or worn), the value of `handedness` is `none`.
 This may indicate, for example, an input source which isn't hand-held, such as controls
 built into a headset or an input device attached to the head or body.

Examples
--------

One important usage scenario for `handedness` is to determine which hand a controller is in so you can draw a representation of that hand (or the device that hand is controlling) in virtual space.

```js
function updateInputSources(session, frame, refSpace) {
  for (const source of session.inputSources) {
    if (source.gripSpace) {
      const gripPose = frame.getPose(source.gripSpace, refSpace);

      if (gripPose) {
        myRenderHandObject(gripPose, inputSource.handedness);
      }
    }
  }
}
```

This function, which would be called every animation frame (or possibly just periodically, depending on the degree of smoothness required and any performance constraints), scans the list of input sources looking for any which have a `gripSpace` which isn't `null`. If a `gripSpace` is present, that means the input source is a hand-held device of some sort, so it should be rendered visibly if possible.

If `gripSpace` is non-`null`, the function proceeds to get the pose for the `gripSpace` transformed into the current reference space. Assuming that's then valid, a function called `myRenderHandObject()` is called with the grip's pose and the value of `handedness`. It then draws the appropriate model positioned and formed for the correct hand.

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

| Specification |
| --- |
| WebXR Device API # dom-xrinputsource-handedness |

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

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

See also
--------

* WebXR Device API
* Inputs and input sources
* Using gamepads in WebXR applications


XRInputSource: targetRayMode property - Web APIs

XRInputSource: targetRayMode property
=====================================

 The read-only `XRInputSource`
 property **`targetRayMode`** indicates the method by which the
 target ray for the input source should be generated and how it should be presented to
 the user.

Typically a target ray is drawn from the source of the targeting system along the target ray in the direction in which the user is looking or pointing. The style of the ray is generally up to you, as is the method for indicating the endpoint of the ray. The targeted point or object might be indicated by drawing a shape or highlighting the targeted surface or object.

A target ray emitted by a hand controller:

![A screenshot showing a target ray being emitted by a hand controller](/en-US/docs/Web/API/XRInputSource/targetRayMode/example-target-ray.gif)

The target ray can be anything from a simple line (ideally fading over distance) to an animated effect, such as the science-fiction "phaser" style shown in the screenshot above.

Value
-----

 A string indicating which method to use when generating and presenting the target ray to
 the user. The possible values are:

`gaze`

The user is using a gaze-tracking system (or **gaze input**) which detects the direction in which the user is looking. The target ray will be drawn originating at the viewer's eyes and will follow the direction in which they're looking.

`screen`

The direction of the target ray is indicated using a tap on a touch screen, mouse, or other tactile input device.

`tracked-pointer`

Targeting is being performed using a handheld device or hand-tracking system which the user points in the direction of the target. The target ray extends from the hand (or the object in the hand) in the targeted direction. The direction is determined using platform-specific rules, though if no such rules exist, the direction is chosen by assuming the user is pointing their index finger straight out from their hand.

Usage notes
-----------

 The input source's `targetRaySpace`
 indicates the position and orientation of the target ray, and can be used to determine
 where to render the ray.

Examples
--------

This fragment of code shows part of a function to be called once every frame. It looks for inputs which have a non-`null` `targetRaySpace`. Inputs which have a value for this property represent inputs that project a target ray outward from the user.

For each such input, this example looks for inputs whose `targetRayMode` is `tracked-pointer`, indicating that the input is in fact intended to represent a targeting device rather than a gazing device, screen tap, or mouse click. For tracked pointers, a function `myRenderTargetRayAsBeam()` is called to render a beam from the input controller's virtual position outward in the direction it's pointing.

The code should continue to perform tasks such as drawing controllers or any objects representative of the user's hands' positions in the virtual space, as well as any other input-related tasks.

```js
function updateInputSources(session, frame, refSpace) {
  for (const source of session.getInputSources()) {
    const targetRayPose = frame.getPose(inputSource.targetRaySpace, refSpace);

    if (targetRayPose) {
      if (source.targetRayMode === "tracked-pointer") {
        myRenderTargetRayAsBeam(targetRayPose);
      }
    }

    // …
  }
}
```

See the article Inputs and input sources for more details and a more complete example.

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

| Specification |
| --- |
| WebXR Device API # dom-xrinputsource-targetraymode |

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

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

See also
--------

* WebXR Device API
* Inputs and input sources
* Using gamepads in WebXR applications


XRInputSource: gamepad property - Web APIs

XRInputSource: gamepad property
===============================

The read-only `XRInputSource` property **`gamepad`** returns a `Gamepad` object describing the state of the buttons and axes on the XR input source, if it is a gamepad or comparable device. If the device isn't a gamepad-like device, this property's value is `null`.

The `Gamepad` instance returned behaves as described by the Gamepad API. However, there are a few things to note:

* `Gamepad` instances belonging to `XRInputSource` are not included in the array returned by `navigator.getGamepads()`. Gamepads are strictly associated with the WebXR hardware and are not general-purpose gaming devices.
* `Gamepad.id` is an empty string (`""`)
* `Gamepad.index` is `-1`
* `Gamepad.connected` is `true` until the `XRInputSource` is removed from the list of active XR input sources or the `XRSession` is ended.
* If an axis reported by `Gamepad.axes` represents an axis of a touchpad, the value is 0 when the associated `GamepadButton.touched` property is `false`.
* `Gamepad.mapping` returns "xr-standard".
Examples
--------

### Using a gamepad input source

```js
for (const source of frame.session.inputSources) {
  const gamepad = source.gamepad;
  if (gamepad) {
    if (gamepad.buttons[2].pressed) {
      // do something
    }
  }
}
```

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

| Specification |
| --- |
| WebXR Gamepads Module - Level 1 # dom-xrinputsource-gamepad |

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

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


AudioBufferSourceNode: loopStart property - Web APIs

AudioBufferSourceNode: loopStart property
=========================================

 The **`loopStart`** property of the `AudioBufferSourceNode` interface is a floating-point value indicating, in
 seconds, where in the `AudioBuffer` the restart of the play must happen.

The `loopStart` property's default value is `0`.

Value
-----

 A floating-point number indicating the offset, in seconds, into the audio buffer at
 which each loop should begin during playback. This value is only used when the
 `loop` parameter is `true`.

Examples
--------

### Setting `loopStart`

In this example, when the user presses "Play", we load an audio track, decode it, and put it into an `AudioBufferSourceNode`.

The example then sets the `loop` property to `true`, so the track loops, and plays the track.

The user can set the `loopStart` and `loopEnd` properties using range controls.

**Note:** You can run the full example live (or view the source.)

```js
let audioCtx;
let buffer;
let source;

const play = document.getElementById("play");
const stop = document.getElementById("stop");

const loopstartControl = document.getElementById("loopstart-control");
const loopstartValue = document.getElementById("loopstart-value");

const loopendControl = document.getElementById("loopend-control");
const loopendValue = document.getElementById("loopend-value");

async function loadAudio() {
  try {
    // Load an audio file
    const response = await fetch("rnb-lofi-melody-loop.wav");
    // Decode it
    buffer = await audioCtx.decodeAudioData(await response.arrayBuffer());
    const max = Math.floor(buffer.duration);
    loopstartControl.setAttribute("max", max);
    loopendControl.setAttribute("max", max);
  } catch (err) {
    console.error(`Unable to fetch the audio file. Error: ${err.message}`);
  }
}

play.addEventListener("click", async () => {
  if (!audioCtx) {
    audioCtx = new AudioContext();
    await loadAudio();
  }
  source = audioCtx.createBufferSource();
  source.buffer = buffer;
  source.connect(audioCtx.destination);
  source.loop = true;
  source.loopStart = loopstartControl.value;
  source.loopEnd = loopendControl.value;
  source.start();
  play.disabled = true;
  stop.disabled = false;
  loopstartControl.disabled = false;
  loopendControl.disabled = false;
});

stop.addEventListener("click", () => {
  source.stop();
  play.disabled = false;
  stop.disabled = true;
  loopstartControl.disabled = true;
  loopendControl.disabled = true;
});

loopstartControl.addEventListener("input", () => {
  source.loopStart = loopstartControl.value;
  loopstartValue.textContent = loopstartControl.value;
});

loopendControl.addEventListener("input", () => {
  source.loopEnd = loopendControl.value;
  loopendValue.textContent = loopendControl.value;
});
```

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

| Specification |
| --- |
| Web Audio API # dom-audiobuffersourcenode-loopstart |

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

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

See also
--------

* Web Audio API
* Using the Web Audio API


AudioBufferSourceNode: detune property - Web APIs

AudioBufferSourceNode: detune property
======================================

 The **`detune`** property of the
 `AudioBufferSourceNode` interface is a k-rate `AudioParam`
 representing detuning of oscillation in cents.

 For example, values of +100 and -100 detune the source up or down by one semitone,
 while +1200 and -1200 detune it up or down by one octave.

Value
-----

 A k-rate `AudioParam`
 whose value indicates the detuning of oscillation in cents.

**Note:** Though the `AudioParam` returned is read-only, the
 value it represents is not.

Examples
--------

```js
const audioCtx = new AudioContext();

const channelCount = 2;
const frameCount = audioCtx.sampleRate \* 2.0; // 2 seconds

const myArrayBuffer = audioCtx.createBuffer(
  channelCount,
  frameCount,
  audioCtx.sampleRate,
);

for (let channel = 0; channel < channelCount; channel++) {
  const nowBuffering = myArrayBuffer.getChannelData(channel);
  for (let i = 0; i < frameCount; i++) {
    nowBuffering[i] = Math.random() \* 2 - 1;
  }
}

const source = audioCtx.createBufferSource();
source.buffer = myArrayBuffer;
source.connect(audioCtx.destination);
source.detune.value = 100; // value in cents
source.start();
```

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

| Specification |
| --- |
| Web Audio API # dom-audiobuffersourcenode-detune |

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

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

See also
--------

* Using the Web Audio API
* Web Audio API


AudioBufferSourceNode: loopEnd property - Web APIs

AudioBufferSourceNode: loopEnd property
=======================================

 The `loopEnd` property of the `AudioBufferSourceNode`
 interface specifies is a floating point number specifying, in seconds, at what offset
 into playing the `AudioBuffer` playback should loop back to the time
 indicated by the `loopStart` property.
 This is only used if the `loop` property is
 `true`.

Value
-----

 A floating-point number indicating the offset, in seconds, into the audio buffer at
 which each loop will loop return to the beginning of the loop (that is, the current play
 time gets reset to `AudioBufferSourceNode.loopStart`). This property is
 only used if the `loop` property is
 `true`.

The default value is 0.

Examples
--------

### Setting `loopEnd`

In this example, when the user presses "Play", we load an audio track, decode it, and put it into an `AudioBufferSourceNode`.

The example then sets the `loop` property to `true`, so the track loops, and plays the track.

The user can set the `loopStart` and `loopEnd` properties using range controls.

**Note:** You can run the full example live (or view the source.)

```js
let audioCtx;
let buffer;
let source;

const play = document.getElementById("play");
const stop = document.getElementById("stop");

const loopstartControl = document.getElementById("loopstart-control");
const loopstartValue = document.getElementById("loopstart-value");

const loopendControl = document.getElementById("loopend-control");
const loopendValue = document.getElementById("loopend-value");

async function loadAudio() {
  try {
    // Load an audio file
    const response = await fetch("rnb-lofi-melody-loop.wav");
    // Decode it
    buffer = await audioCtx.decodeAudioData(await response.arrayBuffer());
    const max = Math.floor(buffer.duration);
    loopstartControl.setAttribute("max", max);
    loopendControl.setAttribute("max", max);
  } catch (err) {
    console.error(`Unable to fetch the audio file. Error: ${err.message}`);
  }
}

play.addEventListener("click", async () => {
  if (!audioCtx) {
    audioCtx = new AudioContext();
    await loadAudio();
  }
  source = audioCtx.createBufferSource();
  source.buffer = buffer;
  source.connect(audioCtx.destination);
  source.loop = true;
  source.loopStart = loopstartControl.value;
  source.loopEnd = loopendControl.value;
  source.start();
  play.disabled = true;
  stop.disabled = false;
  loopstartControl.disabled = false;
  loopendControl.disabled = false;
});

stop.addEventListener("click", () => {
  source.stop();
  play.disabled = false;
  stop.disabled = true;
  loopstartControl.disabled = true;
  loopendControl.disabled = true;
});

loopstartControl.addEventListener("input", () => {
  source.loopStart = loopstartControl.value;
  loopstartValue.textContent = loopstartControl.value;
});

loopendControl.addEventListener("input", () => {
  source.loopEnd = loopendControl.value;
  loopendValue.textContent = loopendControl.value;
});
```

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

| Specification |
| --- |
| Web Audio API # dom-audiobuffersourcenode-loopend |

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

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

See also
--------

* Using the Web Audio API
* Web Audio API


AudioBufferSourceNode: AudioBufferSourceNode() constructor - Web APIs

AudioBufferSourceNode: AudioBufferSourceNode() constructor
==========================================================

 The **`AudioBufferSourceNode()`**
 constructor creates a new `AudioBufferSourceNode` object instance.

Syntax
------

```js
new AudioBufferSourceNode(context, options)
```

### Parameters

`context`

A reference to an `AudioContext`.

`options` Optional

Options are as follows:

`buffer`

An instance of `AudioBuffer` to be played.

`detune`

A value in cents to modulate the speed of audio stream rendering. Its nominal range is (-∞ to +∞). The default is `0`.

`loop`

 A boolean indicating whether the audio should play in a loop.
 The default is `false`. If the loop is dynamically modified during
 playback, the new value will take effect on the next processing block of audio.

`loopEnd`

 An optional value, in seconds, where looping should end if
 the loop attribute is `true`. The default is `0`. Its value
 is exclusive to the content of the loop. The sample frames, comprising the loop,
 run from the values `loopStart` to
 `loopEnd`-(1/`sampleRate`). It's sensible to set this to a
 value between 0 and the duration of the buffer. If `loopEnd` is less
 than 0, looping will end at 0. If `loopEnd` is greater than the
 duration of the buffer, looping will end at the end of the buffer. This attribute
 is converted to an exact sample frame offset within the buffer, by multiplying by
 the buffer's sample rate and rounding to the nearest integer value. Thus, its
 behavior is independent of the value of the `playbackRate` parameter.

`loopStart`

 An optional value in seconds, where looping should begin
 if the loop attribute is `true`. The default is `0`. It's
 sensible to set this to a value between 0 and the duration of the buffer. If
 `loopStart` is less than 0, looping will begin at 0. If
 `loopStart` is greater than the duration of the buffer, looping will
 begin at the end of the buffer. This attribute is converted to an exact sample
 frame offset within the buffer, by multiplying by the buffer's sample rate and
 rounding to the nearest integer value. Thus, its behavior is independent of the
 value of the `playbackRate` parameter.

`playbackRate`

 The speed at which to render the audio stream. Its
 default value is `1`. This parameter is k-rate. This is a compound
 parameter with detune. Its nominal range is (-∞ to +∞).

`channelCount`

 Represents an integer used to determine how many channels are used when up-mixing and down-mixing connections to any inputs to the node. (See
 `AudioNode.channelCount` for more information.) Its usage and precise
 definition depend on the value of `channelCountMode`.

`channelCountMode`

 Represents an enumerated value describing the way channels must be matched between
 the node's inputs and outputs. (See `AudioNode.channelCountMode` for more
 information including default values.)

`channelInterpretation`

 Represents an enumerated value describing the meaning of the channels. This
 interpretation will define how audio up-mixing and down-mixing will happen.
 The possible values are `"speakers"` or `"discrete"`. (See
 `AudioNode.channelCountMode` for more information including default
 values.)

### Return value

A new `AudioBufferSourceNode` object instance.

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

| Specification |
| --- |
| Web Audio API # dom-audiobuffersourcenode-constructor-audiobuffersourcenode |

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

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


AudioBufferSourceNode: start() method - Web APIs

AudioBufferSourceNode: start() method
=====================================

 The `start()` method of the `AudioBufferSourceNode`
 Interface is used to schedule playback of the audio data contained in the buffer, or
 to begin playback immediately.

Syntax
------

```js
start(when)
start(when, offset)
start(when, offset, duration)
```

### Parameters

`when` Optional

 The time, in seconds, at which the sound should begin to play, in the same time
 coordinate system used by the `AudioContext`. If `when` is
 less than (`AudioContext.currentTime`, or if it's 0, the sound begins to
 play at once. **The default value is 0.**

`offset` Optional

 An offset, specified as the number of seconds in the same time coordinate system as
 the `AudioContext`, to the time within the audio buffer that playback
 should begin. For example, to start playback halfway through a 10-second audio clip,
 `offset` should be 5. The default value, 0, will begin playback at the
 beginning of the audio buffer, and offsets past the end of the audio which will be
 played (based on the audio buffer's `duration`
 and/or the `loopEnd` property) are
 silently clamped to the maximum value allowed. The computation of the offset into the
 sound is performed using the sound buffer's natural sample rate, rather than the
 current playback rate, so even if the sound is playing at twice its normal speed, the
 midway point through a 10-second audio buffer is still 5.

`duration` Optional

 The duration of the sound to be played, specified in seconds. If this parameter
 isn't specified, the sound plays until it reaches its natural conclusion or is stopped
 using the `stop()` method. Using this
 parameter is functionally identical to calling `start(when, offset)` and
 then calling `stop(when+duration)`.

### Return value

None (`undefined`).

### Exceptions

`TypeError`

 Thrown if a negative value was specified for one or more of the three time parameters. Please
 don't attempt to tamper with the laws of temporal physics.

`InvalidStateError` `DOMException`

 Thrown if `start()` has already been called. You can only call this function once
 during the lifetime of an `AudioBufferSourceNode`.

Examples
--------

 The most simple example just starts the audio buffer playing from the beginning — you
 don't need to specify any parameters in this case:

```js
source.start();
```

 The following more complex example will, 1 second from now, start playing 10 seconds
 worth of sound starting 3 seconds into the audio buffer.

```js
source.start(audioCtx.currentTime + 1, 3, 10);
```

**Note:** For a more complete example showing `start()` in use, check out our `AudioContext.decodeAudioData()` example. You can also try the example live, and have a look at the example source.

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

| Specification |
| --- |
| Web Audio API # dom-audiobuffersourcenode-start |

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

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

See also
--------

* Using the Web Audio API


AudioBufferSourceNode: loop property - Web APIs

AudioBufferSourceNode: loop property
====================================

 The `loop` property of the `AudioBufferSourceNode`
 interface is a Boolean indicating if the audio asset must be replayed when the end of
 the `AudioBuffer` is reached.

The `loop` property's default value is `false`.

Value
-----

 A Boolean which is `true` if looping is enabled; otherwise, the value is
 `false`.

 When looping is enabled, the sound begins playing at the time specified as the start
 point when `start()` is called. When the
 time specified by the `loopEnd` property
 is reached, playback continues at the time specified by
 `loopStart`

Examples
--------

### Setting `loop`

In this example, when the user presses "Play", we load an audio track, decode it, and put it into an `AudioBufferSourceNode`.

The example then sets the `loop` property to `true`, so the track loops, and plays the track.

The user can set the `loopStart` and `loopEnd` properties using range controls.

**Note:** You can run the full example live (or view the source.)

```js
let audioCtx;
let buffer;
let source;

const play = document.getElementById("play");
const stop = document.getElementById("stop");

const loopstartControl = document.getElementById("loopstart-control");
const loopstartValue = document.getElementById("loopstart-value");

const loopendControl = document.getElementById("loopend-control");
const loopendValue = document.getElementById("loopend-value");

async function loadAudio() {
  try {
    // Load an audio file
    const response = await fetch("rnb-lofi-melody-loop.wav");
    // Decode it
    buffer = await audioCtx.decodeAudioData(await response.arrayBuffer());
    const max = Math.floor(buffer.duration);
    loopstartControl.setAttribute("max", max);
    loopendControl.setAttribute("max", max);
  } catch (err) {
    console.error(`Unable to fetch the audio file. Error: ${err.message}`);
  }
}

play.addEventListener("click", async () => {
  if (!audioCtx) {
    audioCtx = new AudioContext();
    await loadAudio();
  }
  source = audioCtx.createBufferSource();
  source.buffer = buffer;
  source.connect(audioCtx.destination);
  source.loop = true;
  source.loopStart = loopstartControl.value;
  source.loopEnd = loopendControl.value;
  source.start();
  play.disabled = true;
  stop.disabled = false;
  loopstartControl.disabled = false;
  loopendControl.disabled = false;
});

stop.addEventListener("click", () => {
  source.stop();
  play.disabled = false;
  stop.disabled = true;
  loopstartControl.disabled = true;
  loopendControl.disabled = true;
});

loopstartControl.addEventListener("input", () => {
  source.loopStart = loopstartControl.value;
  loopstartValue.textContent = loopstartControl.value;
});

loopendControl.addEventListener("input", () => {
  source.loopEnd = loopendControl.value;
  loopendValue.textContent = loopendControl.value;
});
```

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

| Specification |
| --- |
| Web Audio API # dom-audiobuffersourcenode-loop |

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

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

See also
--------

* Web Audio API
* Using the Web Audio API
* `AudioBufferSourceNode`


AudioBufferSourceNode: buffer property - Web APIs

AudioBufferSourceNode: buffer property
======================================

 The **`buffer`** property of the `AudioBufferSourceNode` interface provides the ability to play back audio
 using an `AudioBuffer` as the source of the sound data.

 If the `buffer` property is set to the value `null`, the node
 generates a single channel containing silence (that is, every sample is 0).

Value
-----

 An `AudioBuffer` which contains the data representing the sound which the
 node will play.

Examples
--------

**Note:** For a full working example, see this code running live, or view the source.

```js
const myArrayBuffer = audioCtx.createBuffer(2, frameCount, audioCtx.sampleRate);

button.onclick = () => {
  // Fill the buffer with white noise;
  //just random values between -1.0 and 1.0
  for (let channel = 0; channel < channels; channel++) {
    // This gives us the actual ArrayBuffer that contains the data
    const nowBuffering = myArrayBuffer.getChannelData(channel);
    for (let i = 0; i < frameCount; i++) {
      // Math.random() is in [0; 1.0]
      // audio needs to be in [-1.0; 1.0]
      nowBuffering[i] = Math.random() \* 2 - 1;
    }
  }

  // Get an AudioBufferSourceNode.
  // This is the AudioNode to use when we want to play an AudioBuffer
  const source = audioCtx.createBufferSource();
  // set the buffer in the AudioBufferSourceNode
  source.buffer = myArrayBuffer;
};
```

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

| Specification |
| --- |
| Web Audio API # dom-audiobuffersourcenode-buffer |

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

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

See also
--------

* Using the Web Audio API
* Web Audio API


AudioBufferSourceNode: playbackRate property - Web APIs

AudioBufferSourceNode: playbackRate property
============================================

 The **`playbackRate`** property of
 the `AudioBufferSourceNode` interface Is a k-rate `AudioParam` that
 defines the speed at which the audio asset will be played.

 A value of 1.0 indicates it should play at the same speed as its sampling rate,
 values less than 1.0 cause the sound to play more slowly, while values greater than
 1.0 result in audio playing faster than normal. The default value is `1.0`.
 When set to another value, the `AudioBufferSourceNode` resamples the audio
 before sending it to the output.

Value
-----

 An `AudioParam` whose `value` is a
 floating-point value indicating the playback rate of the audio as a decimal proportion
 of the original sampling rate.

 Consider a sound buffer containing audio sampled at 44.1 kHz (44,100 samples per
 second). Let's see what a few values of `playbackRate` do:

* A `playbackRate` of 1.0 plays the audio at full speed, or 44,100 Hz.
* A `playbackRate` of 0.5 plays the audio at half speed, or 22,050 Hz.
* A `playbackRate` of 2.0 doubles the audio's playback rate to 88,200 Hz.
Examples
--------

### Setting `playbackRate`

In this example, when the user presses "Play", we load an audio track, decode it, and put it into an `AudioBufferSourceNode`.

The example then sets the `loop` property to `true`, so the track loops, and plays the track.

The user can set the `playbackRate` property using a range control.

**Note:** You can run the full example live (or view the source.)

```js
let audioCtx;
let buffer;
let source;

const play = document.getElementById("play");
const stop = document.getElementById("stop");

const playbackControl = document.getElementById("playback-rate-control");
const playbackValue = document.getElementById("playback-rate-value");

async function loadAudio() {
  try {
    // Load an audio file
    const response = await fetch("rnb-lofi-melody-loop.wav");
    // Decode it
    buffer = await audioCtx.decodeAudioData(await response.arrayBuffer());
  } catch (err) {
    console.error(`Unable to fetch the audio file. Error: ${err.message}`);
  }
}

play.addEventListener("click", async () => {
  if (!audioCtx) {
    audioCtx = new AudioContext();
    await loadAudio();
  }
  source = audioCtx.createBufferSource();
  source.buffer = buffer;
  source.connect(audioCtx.destination);
  source.loop = true;
  source.playbackRate.value = playbackControl.value;
  source.start();
  play.disabled = true;
  stop.disabled = false;
  playbackControl.disabled = false;
});

stop.addEventListener("click", () => {
  source.stop();
  play.disabled = false;
  stop.disabled = true;
  playbackControl.disabled = true;
});

playbackControl.oninput = () => {
  source.playbackRate.value = playbackControl.value;
  playbackValue.textContent = playbackControl.value;
};
```

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

| Specification |
| --- |
| Web Audio API # dom-audiobuffersourcenode-playbackrate |

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

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

See also
--------

* Using the Web Audio API
* Web Audio API


StylePropertyMap: set() method - Web APIs

StylePropertyMap: set() method
==============================

 The **`set()`** method of the `StylePropertyMap`
 interface changes the CSS declaration with the given property.

Syntax
------

```js
set(property, value)
```

### Parameters

`property`

 An identifier indicating the stylistic feature (e.g. font, width, background
 color) to change.

`value`

The value the given property should have.

### Return value

None (`undefined`).

Examples
--------

 This example sets the `padding-top` property, with the given value, within
 the element's style attribute.

```js
// get the button element
const buttonEl = document.querySelector("button");

// set padding-top on button style attribute
buttonEl.attributeStyleMap.set("padding-top", CSS.px(10));
```

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

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-stylepropertymap-set |

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

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


StylePropertyMap: append() method - Web APIs

StylePropertyMap: append() method
=================================

 The **`append()`** method of the
 `StylePropertyMap` interface adds the passed CSS value to the
 `StylePropertyMap` with the given property.

Syntax
------

```js
append(property, value)
```

### Parameters

`property`

 An identifier indicating the stylistic feature (e.g. font, width, background
 color) to add.

`value`

The value the given property should have.

### Return value

None (`undefined`).

Examples
--------

 This example shows an extra background image value being added to the
 `background-image` property of the element, using
 `HTMLElement.attributeStyleMap`.

```js
// get the button element
const buttonEl = document.querySelector("button");

// append another value to the background-image property set on the attribute
buttonEl.attributeStyleMap.append(
  "background-image",
  "linear-gradient(180deg, blue, black)",
);
```

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

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-stylepropertymap-append |

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

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


StylePropertyMap: delete() method - Web APIs

StylePropertyMap: delete() method
=================================

 The **`delete()`** method of the
 `StylePropertyMap` interface removes the CSS declaration with the given
 property.

Syntax
------

```js
delete(property)
```

### Parameters

`property`

 An identifier indicating the stylistic feature (e.g. font, width, background
 color) to remove.

### Return value

None (`undefined`).

Examples
--------

 The following example removes the `background-image` property from the
 element's style attribute.

```js
// get the button element
const buttonEl = document.querySelector("button");

// remove background-image from style attribute
buttonEl.attributeStyleMap.delete("background-image");
```

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

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-stylepropertymap-delete |

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

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


StylePropertyMap: clear() method - Web APIs

StylePropertyMap: clear() method
================================

 The **`clear()`** method of the `StylePropertyMap`
 interface removes all declarations in the `StylePropertyMap`.

Syntax
------

```js
clear()
```

### Parameters

None.

### Return value

None (`undefined`).

Examples
--------

The following example removes all styles within the elements style attribute.

```js
// get the button element
const buttonEl = document.querySelector(".example");

// remove all styles from the style attribute
buttonEl.attributeStyleMap.clear();
```

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

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-stylepropertymap-clear |

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

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


NamedNodeMap: length property - Web APIs

NamedNodeMap: length property
=============================

 The read-only **`length`** property of the `NamedNodeMap` interface
 is the number of objects stored in the map.

Value
-----

A number containing the number of objects in the map

Example
-------

```html
<pre zero="test" one="test" two="test"></pre>
```

```js
const pre = document.querySelector("pre");
const attrMap = pre.attributes;
pre.textContent = `The 'test' attribute contains ${attrMap.length} attributes.\n`;
```

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

| Specification |
| --- |
| DOM Standard # dom-namednodemap-length |

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

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


NamedNodeMap: removeNamedItemNS() method - Web APIs

NamedNodeMap: removeNamedItemNS() method
========================================

 The **`removedNamedItemNS()`** method of the `NamedNodeMap` interface
 removes the `Attr` corresponding to the given namespace and local name from the map.

Syntax
------

```js
removeNamedItem(namespace, localName)
```

### Parameters

`namespace`

The namespace of the attribute to remove from the map

**Warning:** `namespace` is the URI of the namespace, not the prefix.

`localName`

The local name of the attribute to remove from the map.

### Return value

The removed `Attr`.

### Exceptions

`NotFoundError` `DOMException`

Thrown if there is no attribute with the given namespace and local name.

Example
-------
```

<pre></pre>
```

```js
const parser = new DOMParser();
const xmlString =
  '<warning ob:one="test" xmlns:ob="http://www.example.com/ob">Beware!</warning>';
const doc = parser.parseFromString(xmlString, "application/xml");

const pre = document.querySelector("pre");
const warning = doc.querySelector("warning");
const attrMap = warning.attributes;

let result = `The 'ob:one' attribute initially contains '${attrMap["ob:one"].value}'.\n`;

result += "We remove it.\n\n";
attrMap.removeNamedItemNS("http://www.example.com/ob", "one");

result += attrMap["ob:one"]
  ? "And 'ob:one' still exists."
  : "And 'ob:one' is no more to be found.";

pre.textContent = result;
```

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

| Specification |
| --- |
| DOM Standard # dom-namednodemap-removenameditemns |

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

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


NamedNodeMap: getNamedItem() method - Web APIs

NamedNodeMap: getNamedItem() method
===================================

The **`getNamedItem()`** method of the `NamedNodeMap` interface returns the `Attr` corresponding to the given name, or `null` if there is no corresponding attribute.

**Note:** This method is also called when you use the operator `[]` syntax.
 So, `myMap[str]`is equivalent to `myMap.getNamedItem(str)` where `str` is a string.

Syntax
------

```js
getNamedItem(name)
[name]
```

### Parameters

`name`

A string with the name of the desired attribute.

### Return value

An `Attr` corresponding to the `name` given in parameter, or `null` if none has been found.

Example
-------

```html
<pre test="test"></pre>
```

```js
const pre = document.querySelector("pre");
const attrMap = pre.attributes;
const value = attrMap.getNamedItem("test").value;
pre.textContent = `The 'test' attribute contains ${value}.
And 'boum' has ${attrMap["boum"] ? "been" : "not been"} found.`;
```

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

| Specification |
| --- |
| DOM Standard # dom-namednodemap-getnameditem |

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

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


NamedNodeMap: getNamedItemNS() method - Web APIs

NamedNodeMap: getNamedItemNS() method
=====================================

The **`getNamedItemNS()`** method of the `NamedNodeMap` interface returns the `Attr` corresponding to the given local name in the given namespace, or `null` if there is no corresponding attribute.

Syntax
------

```js
getNamedItemNS(namespace, localName)
```

### Parameters

`namespace`

A string with the namespace URI of the desired attribute.

**Warning:** `namespace` is the URI of the namespace, not the prefix.

`localName`

A string with the localName of the desired attribute.

### Return value

An `Attr` corresponding to the namespace and local name given in parameters, or `null` if none has been found.

Example
-------
```

<pre></pre>
```

```js
const parser = new DOMParser();
const xmlString =
  '<warning ob:one="test" xmlns:ob="http://www.example.com/ob">Beware!</warning>';
const doc = parser.parseFromString(xmlString, "application/xml");

const pre = document.querySelector("pre");
const warning = doc.querySelector("warning");

const value = warning.attributes.getNamedItemNS(
  "http://www.example.com/ob",
  "one",
).value;

pre.textContent = `The 'ob:one' attribute contains: ${value}.`;
```

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

| Specification |
| --- |
| DOM Standard # dom-namednodemap-getnameditemns |

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

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


NamedNodeMap: removeNamedItem() method - Web APIs

NamedNodeMap: removeNamedItem() method
======================================

 The **`removeNamedItem()`** method of the `NamedNodeMap` interface
 removes the `Attr` corresponding to the given name from the map.

Syntax
------

```js
removeNamedItem(attrName)
```

### Parameters

`attrName`

The name of the attribute to remove from the map.

### Return value

The removed `Attr`.

### Exceptions

`NotFoundError` `DOMException`

Thrown if there is no attribute with the given name.

Example
-------

```html
<pre test="testValue"></pre>
```

```js
const pre = document.querySelector("pre");
const attrMap = pre.attributes;

let result = `The 'test' attribute initially contains '${attrMap["test"].value}'.\n`;

result += "We remove it.\n\n";
attrMap.removeNamedItem("test");

result += attrMap.getNamedItem("test")
  ? "And 'test' still exists."
  : "And 'test' is no more to be found.";

pre.textContent = result;
```

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

| Specification |
| --- |
| DOM Standard # dom-namednodemap-removenameditem |

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

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


NamedNodeMap: setNamedItem() method - Web APIs

NamedNodeMap: setNamedItem() method
===================================

 The **`setNamedItem()`** method of the `NamedNodeMap` interface
 puts the `Attr` identified by its name in the map.
 If there is already an `Attr` with the same name in the map,
 it is *replaced*.

Syntax
------

```js
setNamedItem(attr)
```

### Parameters

`attr`

the attribute to insert in the map.

### Return value

Returns the old attribute if replaced, or `null` if the attribute is new.

### Exceptions

`InUseAttributeError` `DOMException`

Thrown if the attribute is still part of another map.

Example
-------

```html
<span one="one" two="two"></span>
<pre test="testValue"></pre>
```

```js
const span = document.querySelector("span");
const pre = document.querySelector("pre");
const attrMap = pre.attributes;

let result = `The '<pre>' element initially contains ${attrMap.length} attributes.\n\n`;

result += "We remove `one` from `<span>` and adds it to `<pre>`.\n";
const one = span.attributes.removeNamedItem("one");
attrMap.setNamedItem(one);
result += `The '<pre>' element now contains ${pre.attributes.length} attributes.\n\n`;

result += "We get 'two' from '<span>' and try to adds it to '<pre>'.\n";
const two = span.attributes.getNamedItem("two");
try {
  attrMap.setNamedItem(two);
} catch (error) {
  result += `An exception has been raised: ${error.name}.\n`;
}

pre.textContent = result;
```

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

| Specification |
| --- |
| DOM Standard # dom-namednodemap-setnameditem |

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

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


NamedNodeMap: item() method - Web APIs

NamedNodeMap: item() method
===========================

 The **`item()`** method of the `NamedNodeMap` interface
 returns the item in the map matching the index.

**Note:** This method is also called when you use the operator `[]` syntax.
 So, `myMap[i]`is equivalent to `myMap.item(i)` where `i` is a number.

Syntax
------

```js
item(index)
[index]
```

### Parameters

`index`

A number representing the index of the item you want to return.

### Return value

 An `Attr` or `null` if the number is greater than or equal to the `length` of
 the map.

Example
-------

```html
<pre zero="test" one="test" two="test"></pre>
```

```js
const pre = document.querySelector("pre");
const attrMap = pre.attributes;

pre.textContent = `The attribute map contains:
0: ${attrMap.item(0).name}
1: ${attrMap[1].name}
2: ${attrMap.item(2).name}`;
```

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

| Specification |
| --- |
| DOM Standard # dom-namednodemap-item |

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

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


NamedNodeMap: setNamedItemNS() method - Web APIs

NamedNodeMap: setNamedItemNS() method
=====================================

 The **`setNamedItemNS()`** method of the `NamedNodeMap` interface
 puts the `Attr` identified by its name in the map.
 If there was already an `Attr` with the same name in the map,
 it is *replaced*.

**Note:** This method is an alias of `setNamedItem()` you can use them
 interchangeably.

Syntax
------

```js
setNamedItemNS(attr)
```

### Parameters

`attr`

The attribute to insert in the map.

### Return value

Returns the old attribute if replaced, or `null` if the attribute is new.

### Exceptions

`InUseAttributeError` `DOMException`

Thrown if the attribute is still part of another map.

Example
-------

```html
<span ob:one="one"></span>
<pre></pre>
```

```js
const parser = new DOMParser();
// ob:one in <span> is not in a namespace, while ob:one in <warning>, is.
const xmlString =
  '<warning ob:one="test" xmlns:ob="http://www.example.com/ob">Beware!</warning>';
const doc = parser.parseFromString(xmlString, "application/xml");

const span = document.querySelector("span");
const pre = document.querySelector("pre");
const warning = doc.querySelector("warning");
const attrMap = span.attributes;

let result = `The '<span>' element initially contains ${attrMap.length} attribute.\n\n`;

result += "We remove `one` from '<span>' and adds it to '<pre>'.\n";
const one = warning.attributes.removeNamedItemNS(
  "http://www.example.com/ob",
  "one",
);
attrMap.setNamedItemNS(one);
result += `The '<span>' element now contains ${span.attributes.length} attributes:\n\n`;
result += "Prefix\tLocal name\tQualified name\n";
result += "=========================================\n";

for (const attr of attrMap) {
  result += `${attr.prefix}\t${attr.localName}\t\t${attr.name}\n`;
}

pre.textContent = result;
```

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

| Specification |
| --- |
| DOM Standard # dom-namednodemap-setnameditemns |

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

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


CSSGroupingRule: deleteRule() method - Web APIs

CSSGroupingRule: deleteRule() method
====================================

 The **`deleteRule()`** method of the
 `CSSGroupingRule` interface removes a CSS rule from a list of child CSS
 rules.

Syntax
------

```js
deleteRule(index)
```

### Parameters

`index`

The index of the rule to delete.

### Return value

None (`undefined`).

### Exceptions

`IndexSizeError` `DOMException`

 Thrown if *index* is greater than or equal to the number of child CSS
 rules.

`InvalidStateError` `DOMException`

Thrown if the rule being removed is an `@namespace` at-rule, and the list of child CSS rules contains anything other than `@import` at-rules and `@namespace` at-rules.

Examples
--------

```js
let myRules = document.styleSheets[0].cssRules;
myRules[0].deleteRule(2); /\* deletes the rule at index 2 \*/
```

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

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

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

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


CSSGroupingRule: cssRules property - Web APIs

CSSGroupingRule: cssRules property
==================================

 The **`cssRules`** property of the
 `CSSGroupingRule` interface returns a `CSSRuleList` containing
 a collection of `CSSRule` objects.

Value
-----

a `CSSRuleList`.

Examples
--------

```js
let myRules = document.styleSheets[0].cssRules;
console.log(myRules);
```

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

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

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

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


CSSGroupingRule: insertRule() method - Web APIs

CSSGroupingRule: insertRule() method
====================================

 The **`insertRule()`** method of the
 `CSSGroupingRule` interface adds a new CSS rule to a list of CSS rules.

Syntax
------

```js
insertRule(rule)
insertRule(rule, index)
```

### Parameters

`rule`

A string

`index` Optional

An optional index at which to insert the rule; defaults to 0.

### Return value

The index of the new rule.

### Exceptions

`IndexSizeError` `DOMException`

Thrown if *index* is greater than the number of child CSS rules.

`HierarchyRequestError` `DOMException`

 Thrown if, due to constraints specified by CSS, the new rule cannot be inserted into
 the list at the (zero-index) index position given.

`InvalidStateError` `DOMException`

Thrown if the new rule is an `@namespace` at-rule, and the list of child CSS rules contains anything other than `@import` at-rules and `@namespace` at-rules.

Examples
--------

```js
let myRules = document.styleSheets[0].cssRules;
myRules[0].insertRule(
  "html {background-color: blue;}",
  0,
); /\* inserts a rule for the HTML element at position 0 \*/
```

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

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

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

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


RTCIceCandidatePair: remote property - Web APIs

RTCIceCandidatePair: remote property
====================================

 The **`remote`** property of the
 **`RTCIceCandidatePair`** dictionary specifies the
 `RTCIceCandidate` describing the configuration of the remote end of a
 viable WebRTC connection.

Value
-----

 An `RTCIceCandidate` which describes the configuration of the remote end
 of a viable pair of ICE candidates. The `RTCIceCandidatePair` is returned by
 the `RTCIceTransport` method
 `getSelectedCandidatePair()`.

Examples
--------

 This one-line example obtains the current candidate pair and then from that gets the
 remote candidate.

```js
const candidatePair = pc
  .getSenders()[0]
  .transport.transport.getSelectedCandidatePair();
const remoteCandidate = candidatePair.remote;
```

 The `RTCIceTransport` is found by getting the list of
 `RTCRtpSender` objects for the `RTCPeerConnection`
`pc`. In the first `RTCRtpSender`, we get the
 `RTCDtlsTransport` over which the media data is being transmitted and
 finally, from that, the `RTCIceTransport`.

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

#### No specification found

No specification data found for `api.RTCIceCandidatePair.remote`.
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.


RTCIceCandidatePair: local property - Web APIs

RTCIceCandidatePair: local property
===================================

 The **`local`** property of the
 **`RTCIceCandidatePair`** dictionary specifies the
 `RTCIceCandidate` which describes the configuration of the local end of a
 viable WebRTC connection.

Value
-----

 An `RTCIceCandidate` which describes the configuration of the local end of
 a viable pair of ICE candidates. The `RTCIceCandidatePair` is returned by the
 `RTCIceTransport` method
 `getSelectedCandidatePair()`.

Examples
--------

 This one-line example obtains the current candidate pair and then from that gets the
 local candidate.

```js
const candidatePair = pc
  .getSenders()[0]
  .transport.transport.getSelectedCandidatePair();
const localCandidate = candidatePair.local;
```

 The `RTCIceTransport` is found by getting the list of
 `RTCRtpSender` objects for the `RTCPeerConnection`
`pc`. In the first `RTCRtpSender`, we get the
 `RTCDtlsTransport` over which the media data is being transmitted and
 finally, from that, the `RTCIceTransport`.

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

#### No specification found

No specification data found for `api.RTCIceCandidatePair.local`.
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.


CSSScopeRule: start property - Web APIs

CSSScopeRule: start property
============================

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

The **`start`** property of the `CSSScopeRule` interface returns a string containing the value of the `@scope` at-rule's scope root.

Value
-----

A string, or `null` if the `@scope` at-rule has no scope root defined.

Example
-------

See the main `CSSScopeRule` page for an example.

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

| Specification |
| --- |
| CSS Cascading and Inheritance Level 6 # dom-cssscoperule-start |

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

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

See also
--------

* `@scope`


CSSScopeRule: end property - Web APIs

CSSScopeRule: end property
==========================

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

The **`end`** property of the `CSSScopeRule` interface returns a string containing the value of the `@scope` at-rule's scope limit.

Value
-----

A string, or `null` if the `@scope` at-rule has no scope limit defined.

Example
-------

See the main `CSSScopeRule` page for an example.

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

| Specification |
| --- |
| CSS Cascading and Inheritance Level 6 # dom-cssscoperule-end |

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

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

See also
--------

* `@scope`


FileSystemFileHandle: createWritable() method - Web APIs

FileSystemFileHandle: createWritable() method
=============================================

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

 The **`createWritable()`** method of the `FileSystemFileHandle` interface creates a `FileSystemWritableFileStream` that can be used to write to a file.
 The method returns a `Promise` which resolves to this created stream.

 Any changes made through the stream won't be reflected in the file represented by the file handle until the stream has been closed.
 This is typically implemented by writing data to a temporary file, and only replacing the file represented by file handle with the temporary file when the writable filestream is closed.

Syntax
------

```js
createWritable()
createWritable(options)
```

### Parameters

`options` Optional

An object with the following properties:

`keepExistingData` Optional

 A `Boolean`. Default `false`.
 When set to `true` if the file exists, the existing file is first copied to the temporary file.
 Otherwise the temporary file starts out empty.

### Return value

A `Promise` which resolves to a `FileSystemWritableFileStream` object.

### Exceptions

`NotAllowedError` `DOMException`

Thrown if the `PermissionStatus.state` for the handle is not `'granted'` in `readwrite` mode.

`NotFoundError` `DOMException`

Thrown if current entry is not found.

`NoModificationAllowedError` `DOMException`

Thrown if the browser is not able to acquire a lock on the file associated with the file handle.

`AbortError` `DOMException`

Thrown if implementation-defined malware scans and safe-browsing checks fails.

Examples
--------

The following asynchronous function writes the given contents to the file handle, and thus to disk.

```js
async function writeFile(fileHandle, contents) {
  // Create a FileSystemWritableFileStream to write to.
  const writable = await fileHandle.createWritable();

  // Write the contents of the file to the stream.
  await writable.write(contents);

  // Close the file and write the contents to disk.
  await writable.close();
}
```

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

| Specification |
| --- |
| File System Standard # api-filesystemfilehandle-createwritable |

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

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

See also
--------

* File System API
* The File System Access API: simplifying access to local files


FileSystemFileHandle: getFile() method - Web APIs

FileSystemFileHandle: getFile() method
======================================

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

 The **`getFile()`** method of the
 `FileSystemFileHandle` interface returns a `Promise` which resolves to a
 `File` object representing the state on disk of the entry represented by the handle.

 If the file on disk changes or is removed after this method is called, the returned
 `File` object will likely be no longer readable.

Syntax
------

```js
getFile()
```

### Parameters

None.

### Return value

A `Promise` which resolves to a `File` object.

### Exceptions

`NotAllowedError` `DOMException`

Thrown if the `PermissionStatus.state` is not `granted` in `read` mode.

`NotFoundError` `DOMException`

Thrown if current entry is not found.

Examples
--------

 The following asynchronous function presents a file picker and once a file is chosen,
 uses the `getFile()` method to retrieve the contents.

```js
async function getTheFile() {
  // open file picker
  [fileHandle] = await window.showOpenFilePicker(pickerOpts);

  // get file contents
  const fileData = await fileHandle.getFile();
}
```

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

| Specification |
| --- |
| File System Standard # api-filesystemfilehandle-getfile |

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

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

See also
--------

* File System API
* The File System Access API: simplifying access to local files


FileSystemFileHandle: createSyncAccessHandle() method - Web APIs

FileSystemFileHandle: createSyncAccessHandle() method
=====================================================

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

 The **`createSyncAccessHandle()`** method of the
 `FileSystemFileHandle` interface returns a `Promise` which resolves to a `FileSystemSyncAccessHandle` object
 that can be used to synchronously read from and write to a file. The synchronous nature of this method brings performance advantages,
 but it is only usable inside dedicated Web Workers for files within the origin private file system.

Creating a `FileSystemSyncAccessHandle` takes an exclusive lock on the file associated with the file handle. This prevents the creation of further `FileSystemSyncAccessHandle`s or `FileSystemWritableFileStream`s for the file until the existing access handle is closed.

Syntax
------

```js
createSyncAccessHandle()
```

### Parameters

None.

### Return value

A `Promise` which resolves to a `FileSystemSyncAccessHandle` object.

### Exceptions

`NotAllowedError` `DOMException`

Thrown if the `PermissionStatus.state` for the handle is not `granted` in `readwrite` mode.

`InvalidStateError` `DOMException`

Thrown if the `FileSystemSyncAccessHandle` object does not represent a file in the origin private file system.

`NotFoundError` `DOMException`

Thrown if current entry is not found.

`NoModificationAllowedError` `DOMException`

Thrown if the browser is not able to acquire a lock on the file associated with the file handle.

Examples
--------

The following asynchronous event handler function is contained inside a Web Worker. The snippet inside it creates a synchronous file access handle.

```js
onmessage = async (e) => {
  // Retrieve message sent to work from main script
  const message = e.data;

  // Get handle to draft file
  const root = await navigator.storage.getDirectory();
  const draftHandle = await root.getFileHandle("draft.txt", { create: true });
  // Get sync access handle
  const accessHandle = await draftHandle.createSyncAccessHandle();

  // …

  // Always close FileSystemSyncAccessHandle if done.
  accessHandle.close();
};
```

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

| Specification |
| --- |
| File System Standard # api-filesystemfilehandle-createsyncaccesshandle |

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

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

See also
--------

* File System API
* The File System Access API: simplifying access to local files


InstallEvent: InstallEvent() constructor - Web APIs

InstallEvent: InstallEvent() constructor
========================================

**Deprecated:** This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.

**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 **`InstallEvent()`** constructor creates a new `InstallEvent` object.

Syntax
------

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

### Parameters

`type`

 A string with the name of the event.
 It is case-sensitive and browsers always set it to `install`.

`options` Optional

An object that, *in addition of the properties defined in `Event()`*, can contain any custom settings that you want to apply to the event object. Currently no possible options are mandatory, but this has been defined for forward compatibility.

Return value
------------

A new `InstallEvent` object.

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

*This feature is no more on the standard track.*

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

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

See also
--------

* `Promise`
* Fetch API


DocumentFragment: DocumentFragment() constructor - Web APIs

DocumentFragment: DocumentFragment() constructor
================================================

 The **`DocumentFragment()`** constructor returns a new, empty
 `DocumentFragment` object.

Syntax
------

```js
new DocumentFragment()
```

### Parameters

None.

### Return value

A new `DocumentFragment` object.

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-documentfragment-documentfragment① |

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

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


DocumentFragment: getElementById() method - Web APIs

DocumentFragment: getElementById() method
=========================================

The **`getElementById()`** method of the `DocumentFragment` returns an `Element` object representing the element whose `id` property matches the specified string. Since element IDs are required to be unique if specified, they're a useful way to get access to a specific element quickly.

If you need to get access to an element which doesn't have an ID, you can use `querySelector()` to find the element using any selector.

**Note:** IDs should be unique inside a document fragment. If two or more elements in a document fragment have the same ID, this method returns the first element found.

Syntax
------

```js
getElementById(id)
```

**Note:** The capitalization of `"Id"` in the name of this method *must* be correct for the code to function; `getElementByID()` is *not* valid and will not work, however natural it may seem.

### Parameters

`id`

The ID of the element to locate. The ID is a case-sensitive string which is unique within the document fragment: only one element should have any given ID.

### Return value

An `Element` object describing the DOM element object matching the specified ID, or `null` if no matching element was found in the document fragment.

Examples
--------

### Extend a list of elements

In this example, the document contains a list with a single item `Cherry`. We also create a document fragment containing four more items, `Apple`, `Orange`, `Banana`, and `Melon`.

We then log the result of using `getElementById()` to look for `Apple` and `Cherry` in the document and in the fragment. At this point, `Cherry` appears only in the document while `Apple` appears only in the fragment.

If you click "Add fragment to document", we append the fragment to the list inside the document, and again log the result of looking for both `Apple` and `Cherry` in the document and in the fragment. This time, both `Apple` and `Cherry` appear in the document, and neither appear in the fragment.

This is because appending a fragment to a document moves the fragment's nodes into the DOM, leaving behind an empty `DocumentFragment`.

#### HTML

```html
<button id="add">Add fragment to document</button>
<button id="reset">Reset example</button> <br />
List content:
<ul>
  <li id="Cherry">Cherry</li>
</ul>
Fragment content:
<ul id="fragment"></ul>
Current status:
<pre id="log" />
```

```
button {
  margin-bottom: 10px;
}
```

#### JavaScript

```js
// Create the document fragment with its initial content
const fragment = new DocumentFragment();
["Apple", "Orange", "Banana", "Melon"].forEach((fruit) => {
  const li = document.createElement("li");
  li.textContent = fruit;
  li.id = fruit;
  fragment.append(li);
});

// When the button is clicked, add the fragment to the list
document.getElementById("add").addEventListener("click", () => {
  document.querySelector("ul").append(fragment);
  displayStatus();
});

// Log the results of both getElementById()
function displayStatus() {
  const log = document.getElementById("log");
  log.textContent = "";
  ["Apple", "Cherry"].forEach((id) => {
    log.textContent += `document.getElementById("${id}") ${
 document.getElementById(id) ? "Yes" : "No"
 }\n`;
    log.textContent += `fragment.getElementById("${id}") ${
 fragment.getElementById(id) ? "Yes" : "No"
 }\n`;
  });

  // Empty the fragment viewer and fill it with the current content
  const fragmentViewer = document.getElementById("fragment");
  while (fragmentViewer.hasChildNodes()) {
    fragmentViewer.removeChild(fragmentViewer.lastChild);
  }
  for (entry of fragment.children) {
    fragmentViewer.appendChild(entry.cloneNode(true));
  }
}

// Log the initial state
displayStatus();

// Hook the reset button
document.getElementById("reset").addEventListener("click", () => {
  document.location.reload();
});
```

#### Result

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

| Specification |
| --- |
| DOM Standard # dom-nonelementparentnode-getelementbyid |

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

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

See also
--------

* `Document.getElementById()`


DocumentFragment: querySelector() method - Web APIs

DocumentFragment: querySelector() method
========================================

 The **`DocumentFragment.querySelector()`** method returns the
 first element, or `null` if no matches are found, within the
 `DocumentFragment` (using depth-first pre-order traversal of the
 document's nodes) that matches the specified group of selectors.

 If the selector matches an ID and this ID is erroneously used several times in the
 document, it returns the first matching element.

 If the selectors specified in parameter are invalid a `DOMException` with
 a `SYNTAX_ERR` value is raised.

Syntax
------

```js
querySelector(selectors)
```

### Parameters

`selectors`

 A string containing one or more CSS selectors separated by
 commas.

### Return value

 An `Element` object representing the first element in the document
 that matches the specified set of CSS selectors, or `null` is returned if there are no matches.

Examples
--------

### Basic example

 In this basic example, the first element in the `DocumentFragment` with
 the class "`myclass`" is returned:

```js
const el = documentfragment.querySelector(".myclass");
```

### CSS syntax and the method's argument

 The string argument pass to `querySelector` must follow the CSS syntax. To
 match ID or selectors that do not follow the CSS syntax (by using semicolon or space
 inappropriately for example), it's mandatory to escape the wrong character with a
 double back slash:

```html
<div id="foo\bar"></div>
<div id="foo:bar"></div>

<script>
 document.querySelector("#foo\bar"); // Does not match anything
 document.querySelector("#foo\\\\bar"); // Match the first div
 document.querySelector("#foo:bar"); // Does not match anything
 document.querySelector("#foo\\:bar"); // Match the second div
</script>
```

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-parentnode-queryselector① |

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

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

See also
--------

* The `DocumentFragment` interface it belongs to.


DocumentFragment: children property - Web APIs

DocumentFragment: children property
===================================

 The read-only **`children`** property returns a live `HTMLCollection`
 which contains all of the child `elements` of the document fragment upon which it was called.

Value
-----

 An `HTMLCollection` which is a live, ordered collection of the DOM
 elements which are children of the document fragment. You can access the
 individual child nodes in the collection by using either the
 `item()` method on the collection, or by using
 JavaScript array-style notation.

 If the document fragment has no element children, then `children` is an empty list with a
 `length` of `0`.

Examples
--------

```js
let fragment = new DocumentFragment();
fragment.children; // HTMLCollection []

let paragraph = document.createElement("p");
fragment.appendChild(paragraph);

fragment.children; // HTMLCollection [<p>]
```

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-parentnode-children① |

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

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

See also
--------

* `Node.childNodes`


DocumentFragment: prepend() method - Web APIs

DocumentFragment: prepend() method
==================================

 The **`DocumentFragment.prepend()`** method
 inserts a set of `Node` objects or string objects before
 the first child of the document fragment. String objects
 are inserted as equivalent `Text` nodes.

This method prepends a child to a `DocumentFragment`. To prepend to an arbitrary element in the tree, see `Element.prepend()`.

Syntax
------

```js
prepend(param1)
prepend(param1, param2)
prepend(param1, param2, /\* …, \*/ paramN)
```

### Parameters

`param1`, …, `paramN`

A set of `Node` or string objects to insert.

### Return value

None (`undefined`).

### Exceptions

`HierarchyRequestError` `DOMException`

Thrown when the node cannot be inserted at the specified point in the hierarchy.

Examples
--------

### Prepending an element to a document fragment

```js
let fragment = new DocumentFragment();
let div = document.createElement("div");
let p = document.createElement("p");
fragment.append(p);
fragment.prepend(div);

fragment.children; // HTMLCollection [<div>, <p>]
```

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-parentnode-prepend① |

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

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

See also
--------

* `DocumentFragment.append()`
* `Element.prepend()`


DocumentFragment: querySelectorAll() method - Web APIs

DocumentFragment: querySelectorAll() method
===========================================

 The **`DocumentFragment.querySelectorAll()`** method returns a
 `NodeList` of elements within the `DocumentFragment` (using
 depth-first pre-order traversal of the document's nodes) that matches the specified
 group of selectors.

 If the selectors specified in parameter are invalid a `DOMException` with
 a `SYNTAX_ERR` value is raised.

Syntax
------

```js
querySelectorAll(selectors)
```

### Parameters

`selectors`

 A string containing one or more CSS selectors separated by
 commas.

### Return value

 A non-live `NodeList` containing one `Element` object for
 each element that matches at least one of the specified selectors or an empty
 `NodeList` in case of no matches.

Examples
--------

 This example returns a list of all `div` elements within the
 `DocumentFragment` with a class of either "`note`" or
 "`alert`":

```js
const matches = documentfrag.querySelectorAll("div.note, div.alert");
```

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-parentnode-queryselectorall① |

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

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

See also
--------

* The `DocumentFragment` interface it belongs to.


DocumentFragment: childElementCount property - Web APIs

DocumentFragment: childElementCount property
============================================

 The **`DocumentFragment.childElementCount`** read-only property
 returns the number of child elements of a `DocumentFragment`.

To get the number of children of a specific element, see `Element.childElementCount`.

Value
-----

A number representing the number of children of the document fragment.

Examples
--------

```js
let fragment = new DocumentFragment();
fragment.childElementCount; // 0

let paragraph = document.createElement("p");
fragment.appendChild(paragraph);

fragment.childElementCount; // 1
```

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

| Specification |
| --- |
| DOM Standard # dom-parentnode-childelementcount |

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

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

See also
--------

* `Element.childElementCount`
* `Document.childElementCount`


DocumentFragment: firstElementChild property - Web APIs

DocumentFragment: firstElementChild property
============================================

 The **`DocumentFragment.firstElementChild`** read-only property
 returns the document fragment's first child `Element`, or `null` if there
 are no child elements.

Value
-----

An `Element` that is the first child `Element` of the object, or `null` if there are none.

Examples
--------

```js
let fragment = new DocumentFragment();
fragment.firstElementChild; // null

let paragraph = document.createElement("p");
fragment.appendChild(paragraph);

fragment.firstElementChild; // <p>
```

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-parentnode-firstelementchild① |

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

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

See also
--------

* `Element.firstElementChild`


DocumentFragment: lastElementChild property - Web APIs

DocumentFragment: lastElementChild property
===========================================

 The **`DocumentFragment.lastElementChild`** read-only property
 returns the document fragment's last child `Element`, or `null` if there
 are no child elements.

Value
-----

An `Element` that is the last child `Element` of the object, or `null` if there are none.

Examples
--------

```js
let fragment = new DocumentFragment();
fragment.lastElementChild; // null

let paragraph = document.createElement("p");
fragment.appendChild(paragraph);

fragment.lastElementChild; // <p>
```

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-parentnode-lastelementchild① |

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

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

See also
--------

* `Element.lastElementChild`