RTCDataChannel: id property - Web APIs

RTCDataChannel: id property
===========================

 The read-only `RTCDataChannel` property
 **`id`** returns an ID number (between 0 and 65,534) which
 uniquely identifies the `RTCDataChannel`. This ID is set at the
 time the data channel is created, either by the user agent (if
 `RTCDataChannel.negotiated` is `false`) or by the site or app
 script (if `negotiated` is `true`).

 Each `RTCPeerConnection` can therefore have up to a theoretical maximum of
 65,534 data channels on it, although the actual maximum may vary from browser to
 browser.

Value
-----

 An `unsigned short` value (that is, an integer between 0 and 65,535) which
 uniquely identifies the data channel.

 While the `label` property doesn't have to be
 unique, this ID number is guaranteed to be unique among all data channels. Additionally,
 known implementations of WebRTC use the same ID on both peers. A unique ID makes it
 easier for your code to do its own out-of-band data channel-related signaling.

This can be also useful for logging and debugging purposes.

Example
-------

```js
const pc = new RTCPeerConnection();
const dc = pc.createDataChannel("my channel");

console.log(`Channel id: ${dc.id}`);
```

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcdatachannel-id |

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

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

See also
--------

* WebRTC
* `RTCDataChannel`
* `RTCPeerConnection.createDataChannel()`


RTCDataChannel: readyState property - Web APIs

RTCDataChannel: readyState property
===================================

The read-only `RTCDataChannel` property **`readyState`** returns a string which indicates the state of the data channel's underlying data connection.

Values
------

A string indicating the current state of the underlying data transport, which is one of the following values:

`connecting`

 The user agent (browser) is in the process of creating the underlying data transport;
 this is the state of a new `RTCDataChannel` after being created by `RTCPeerConnection.createDataChannel()`,
 on the peer which started the connection process.

`open`

 The underlying data transport has been established
 and data can be transferred bidirectionally across it.
 This is the default state of a new `RTCDataChannel` created by the WebRTC layer
 when the remote peer created the channel
 and delivered it to the site or app
 in a `datachannel` event.

`closing`

 The process of closing the underlying data transport has begun.
 It is no longer possible to queue new messages to be sent,
 but previously queued messages may still be send or received
 before entering the `closed` state.

`closed`

 The underlying data transport has closed,
 or the attempt to make the connection failed.

Example
-------

```js
const dataChannel = peerConnection.createDataChannel("File Transfer");
const sendQueue = [];

function sendMessage(msg) {
  switch (dataChannel.readyState) {
    case "connecting":
      console.log(`Connection not open; queueing: ${msg}`);
      sendQueue.push(msg);
      break;
    case "open":
      sendQueue.forEach((msg) => dataChannel.send(msg));
      break;
    case "closing":
      console.log(`Attempted to send message while closing: ${msg}`);
      break;
    case "closed":
      console.log("Error! Attempt to send while connection closed.");
      break;
  }
}
```

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-datachannel-readystate |

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

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

See also
--------

* WebRTC
* Using WebRTC data channels
* `RTCDataChannel`
* `RTCPeerConnection.createDataChannel()`


RTCDataChannel: bufferedamountlow event - Web APIs

RTCDataChannel: bufferedamountlow event
=======================================

A **`bufferedamountlow`** event is sent to an `RTCDataChannel` when the number of bytes currently in the outbound data transfer buffer falls below the threshold specified in `bufferedAmountLowThreshold`. `bufferedamountlow` events aren't sent if `bufferedAmountLowThreshold` is 0.

This event is not cancelable and does not bubble.

Syntax
------

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

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

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

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

A generic `Event`.

Examples
--------

This example sets up a handler for `bufferedamountlow` to request more data any time the data channel's buffer falls below the number of bytes specified by `bufferedAmountLowThreshold`, which we have set to 65536. In other words, we'll try to keep at least 64kB of data in the buffer, reading 64kB at a time from the source.

```js
let pc = new RTCPeerConnection();
let dc = pc.createDataChannel("SendFile");
// source data object
let source = (dc.bufferedAmountLowThreshold = 65536);

pc.addEventListener(
  "bufferedamountlow",
  (ev) => {
    if (source.position <= source.length) {
      dc.send(source.readFile(65536));
    }
  },
  false,
);
```

After creating the `RTCPeerConnection`, this calls `RTCPeerConnection.createDataChannel()` to create the data channel. Then a listener is created for `bufferedamountlow` to refill the incoming data buffer any time its contents fall below 65536 bytes.

You can also set up a listener for `bufferedamountlow` using its event handler property, `onbufferedamountlow`:

```js
pc.onbufferedamountlow = (ev) => {
  if (source.position <= source.length) {
    dc.send(source.readFile(65536));
  }
};
```

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # event-datachannel-bufferedamountlow |
| WebRTC: Real-Time Communication in Browsers # dom-rtcdatachannel-onbufferedamountlow |

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

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

See also
--------

* WebRTC API
* `RTCDataChannel`
* `RTCDataChannel.bufferedAmountLowThreshold`


RTCDataChannel: bufferedAmount property - Web APIs

RTCDataChannel: bufferedAmount property
=======================================

 The read-only `RTCDataChannel` property
 **`bufferedAmount`** returns the number of bytes of data
 currently queued to be sent over the data channel. The queue may build up as a
 result of calls to the `send()` method. This only
 includes data buffered by the user agent itself; it doesn't include any framing overhead
 or buffering done by the operating system or network hardware.

 The user agent may implement the process of actually sending data in any way it
 chooses; this may be done periodically during the event loop or truly asynchronously. As
 messages are actually sent, this value is reduced accordingly.

**Note:** Closing the data channel doesn't reset this count, even though the user agent purges
 the queued messages. However, even after closing the channel, attempts to send
 messages continue to add to the `bufferedAmount` value, even though the
 messages are neither sent nor buffered.

 Whenever this value decreases to fall to or below the value specified in the
 `bufferedAmountLowThreshold`
 property, the user agent fires the `bufferedamountlow` event. This event may
 be used, for example, to implement code which queues more messages to be sent whenever
 there's room to buffer them.

Value
-----

 The number of bytes of data currently queued to be sent over the data channel but have
 not yet been sent.

Example
-------

 The snippet below includes a function which changes the contents of a block with the ID
 "bufferSize" to a string indicating the number of bytes currently buffered on an
 `RTCDataChannel`.

```js
const dc = peerConnection.createDataChannel("File Transfer");

// …

function showBufferedAmount(channel) {
  const el = document.getElementById("bufferSize");

  el.innerText = `${channel.bufferedAmount} bytes`;
}
```

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-datachannel-bufferedamount |

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

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

See also
--------

* WebRTC
* Using WebRTC data channels
* `RTCDataChannel`
* `RTCDataChannel.bufferedAmountLowThreshold`
* `bufferedamountlow` event


RTCDataChannel: maxRetransmits property - Web APIs

RTCDataChannel: maxRetransmits property
=======================================

 The read-only `RTCDataChannel` property
 **`maxRetransmits`** returns the maximum number of times the
 browser should try to retransmit a message before giving up, as set when the data
 channel was created, or `null`, which indicates that there is no
 maximum. This can only be set when the `RTCDataChannel` is created
 by calling `RTCPeerConnection.createDataChannel()`, using the
 `maxRetransmits` field in the specified `options`.

Value
-----

 The maximum number of times the browser will try to retransmit a message before giving
 up, or `null` if not set when
 `RTCPeerConnection.createDataChannel()` was called. The default is
 `null`.

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-datachannel-maxretransmits |

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

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

See also
--------

* WebRTC
* `RTCDataChannel`
* `RTCDataChannel.maxPacketLifetime`
* `RTCPeerConnection.createDataChannel()`


RTCDataChannel: open event - Web APIs

RTCDataChannel: open event
==========================

The WebRTC **`open`** event is sent to an `RTCDataChannel` object's `onopen` event handler when the underlying transport used to send and receive the data channel's messages is opened or reopened.

This event is not cancelable and does not bubble.

Syntax
------

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

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

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

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

An `RTCDataChannelEvent`. Inherits from `Event`.

Event

RTCDataChannelEventEvent properties
----------------

*Also inherits properties from its parent interface, `Event`.*

`channel` Read only

Returns the `RTCDataChannel` associated with the event.

Examples
--------

This example adds to the `RTCDataChannel` `dc` a handler for the `open` event that adjusts the user interface to indicate that a chat window is ready to be used after a connection has been established. It enables the message input box and send button as well as enabling the disconnect button and disabling the connect button. Finally, the message input box is focused so the user can immediately begin to type.

```js
dc.addEventListener(
  "open",
  (ev) => {
    messageInputBox.disabled = false;
    sendMessageButton.disabled = false;
    disconnectButton.disabled = false;
    connectButton.disabled = true;

    messageInputBox.focus();
  },
  false,
);
```

This can also be done by directly setting the value of the channel's `onopen` event handler property.

```js
dc.onopen = (ev) => {
  messageInputBox.disabled = false;
  sendMessageButton.disabled = false;
  disconnectButton.disabled = false;
  connectButton.disabled = true;

  messageInputBox.focus();
};
```

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

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

See also
--------

* WebRTC API
* A simple RTCDataChannel example
* Related events: `message`, `close`, and `error`


RTCDataChannel: binaryType property - Web APIs

RTCDataChannel: binaryType property
===================================

 The property **`binaryType`** on the
 `RTCDataChannel` interface is a string which specifies
 the type of object which should be used to represent binary data received
 on the `RTCDataChannel`. Values allowed by the
 `WebSocket.binaryType` property are also permitted here:
 `blob` if `Blob` objects are being used or
 `arraybuffer` if `ArrayBuffer` objects are being used. The
 default is `blob`.

 When a binary message is received on the data channel, the resulting
 `message` event's `MessageEvent.data` property is an object of
 the type specified by the `binaryType`.

Value
-----

A string that can have one of these values:

`"blob"`

Received binary messages' contents will be contained in `Blob` objects.

`"arraybuffer"`

 Received binary messages' contents will be contained in `ArrayBuffer`
 objects.

Example
-------

 This code configures a data channel to receive binary data in
 `ArrayBuffer` objects, and establishes a listener for `message`
 events which constructs a string representing the received data as a list of hexadecimal
 byte values.

```js
const dc = peerConnection.createDataChannel("Binary");
dc.binaryType = "arraybuffer";

dc.onmessage = (event) => {
  const byteArray = new Uint8Array(event.data);
  let hexString = "";

  byteArray.forEach((byte) => {
    hexString += `${byte.toString(16)} `;
  });
};
```

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-datachannel-binarytype |

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

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

See also
--------

* WebRTC
* Using WebRTC data channels
* `RTCDataChannel`
* `RTCDataChannel.send()`


VideoColorSpace: transfer property - Web APIs

VideoColorSpace: transfer property
==================================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
The **`transfer`** read-only property of the `VideoColorSpace` interface returns the opto-electronic transfer characteristics of the video.

Value
-----

A string containing one of the following values:

`"bt709"`

Transfer characteristics used by BT.709.

`"smpte170m"`

Transfer characteristics used by BT.601 NTSC.

`"iec61966-2-1"`

Transfer characteristics used by sRGBA.

Examples
--------

In the following example, `colorSpace` is a `VideoColorSpace` object returned from `VideoFrame`. The value of `transfer` is printed to the console.

```js
let colorSpace = VideoFrame.colorSpace;
console.log(colorSpace.transfer);
```

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

| Specification |
| --- |
| WebCodecs # dom-videocolorspace-transfer |

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

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


VideoColorSpace: VideoColorSpace() constructor - Web APIs

VideoColorSpace: VideoColorSpace() constructor
==============================================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
The **`VideoColorSpace()`** constructor creates a new `VideoColorSpace` object which represents a video color space.

Syntax
------

```js
new VideoColorSpace()
new VideoColorSpace(options)
```

### Parameters

All values default to `null` when they are not present.

`options` Optional

An object containing the following:

`primaries` Optional

One of the following strings:

* `"bt709"`
* `"bt470bg"`
* `"smpte170m"`

`transfer` Optional

One of the following strings:

* `"bt709"`
* `"smpte170m"`
* `"iec61966-2-1"`

`matrix` Optional

One of the following strings:

* `"rgb"`
* `"bt709"`
* `"bt470bg"`
* `"smpte170m"`

`fullRange` Optional

A `Boolean`, `true` if full-range color values are used in the video.

Examples
--------

The following example creates a new `VideoColorSpace` object with `VideoColorSpace.primaries` set to `"bt709"`, and `VideoColorSpace.primaries` set to `true`.

```js
const options = {
  primaries: "bt709",
  fullRange: true,
};

const colorSpace = new VideoColorSpace(options);
console.log(colorSpace);
```

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

| Specification |
| --- |
| WebCodecs # dom-videocolorspace-videocolorspace |

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

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


VideoColorSpace: fullRange property - Web APIs

VideoColorSpace: fullRange property
===================================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
The **`fullRange`** read-only property of the `VideoColorSpace` interface returns `true` if full-range color values are used.

Value
-----

A `Boolean`, `true` if full-range color values are used.

Examples
--------

In the following example, `colorSpace` is a `VideoColorSpace` object returned from `VideoFrame`. The value of `fullRange` is printed to the console.

```js
let colorSpace = VideoFrame.colorSpace;
console.log(colorSpace.fullRange);
```

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

| Specification |
| --- |
| WebCodecs # dom-videocolorspace-fullrange |

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

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


VideoColorSpace: primaries property - Web APIs

VideoColorSpace: primaries property
===================================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
The **`primaries`** read-only property of the `VideoColorSpace` interface returns the color gamut of the video.

Value
-----

A string containing one of the following values:

`"bt709"`

Color primaries used by BT.709 and sRGB.

`"bt470bg"`

Color primaries used by BT.601 PAL.

`"smpte170m"`

Color primaries used by BT.601 NTSC.

Examples
--------

In the following example, `colorSpace` is a `VideoColorSpace` object returned from `VideoFrame`. The value of `primaries` is printed to the console.

```js
let colorSpace = VideoFrame.colorSpace;
console.log(colorSpace.primaries);
```

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

| Specification |
| --- |
| WebCodecs # dom-videocolorspace-primaries |

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

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


VideoColorSpace: toJSON() method - Web APIs

VideoColorSpace: toJSON() method
================================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
The **`toJSON()`** method of the `VideoColorSpace` interface is a *serializer* that returns a JSON representation of the `VideoColorSpace` object.

Syntax
------

```js
toJSON()
```

### Parameters

None.

### Return value

A JSON object.

Examples
--------

In the following example, `colorSpace` is a `VideoColorSpace` object returned from `VideoFrame`. This object is then printed to the console as JSON.

```js
let colorSpace = VideoFrame.colorSpace;
console.log(colorSpace.toJSON());
```

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

| Specification |
| --- |
| WebCodecs # dom-videocolorspace-tojson |

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

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


VideoColorSpace: matrix property - Web APIs

VideoColorSpace: matrix property
================================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
The **`matrix`** read-only property of the `VideoColorSpace` interface returns the matrix coefficient of the video. Matrix coefficients describe the relationship between sample component values and color coordinates.

Value
-----

A string containing one of the following values:

`"rgb"`

Matrix coefficients used by sRGB.

`"bt709"`

Matrix coefficients used by BT.709.

`"bt470bg"`

Matrix coefficients used by BT.601 PAL.

`"smpte170m"`

Matrix coefficients used by BT.601 NTSC.

Examples
--------

In the following example, `colorSpace` is a `VideoColorSpace` object returned from `VideoFrame`. The value of `matrix` is printed to the console.

```js
let colorSpace = VideoFrame.colorSpace;
console.log(colorSpace.matrix);
```

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

| Specification |
| --- |
| WebCodecs # dom-videocolorspace-matrix |

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

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


HTMLFormElement: elements property - Web APIs

HTMLFormElement: elements property
==================================

 The `HTMLFormElement` property
 **`elements`** returns an
 `HTMLFormControlsCollection` listing all the form controls contained in
 the `<form>` element.

 Independently, you can obtain just the
 number of form controls using the `length`
 property.

 You can access a particular form control in the returned collection by using either an
 index or the element's `name` or `id` attributes.

 Prior to HTML 5, the returned object was an `HTMLCollection`, on which
 `HTMLFormControlsCollection` is based.

**Note:** Similarly, you can get a list of all of the forms contained within a given document using the document's `forms` property.

Value
-----

 An `HTMLFormControlsCollection` containing all non-image controls in the form.
 This is a live collection; if form controls are added to or removed from the form, this collection will update to reflect the change.

 The form controls in the returned collection are in the same order in which they appear in the form by following a preorder, depth-first traversal of the tree.
 This is called **tree order**.

Only the following elements are returned:

* `<button>`
* `<fieldset>`
* `<input>` (with the exception that any whose `type` is `"image"` are omitted for historical reasons)
* `<object>`
* `<output>`
* `<select>`
* `<textarea>`
Examples
--------

### Quick syntax example

In this example, we see how to obtain the list of form controls as well as how to access its members by index and by name or ID.

```html
<form id="my-form">
  <label>
    Username:
    <input type="text" name="username" />
  </label>
  <label>
    Full name:
    <input type="text" name="full-name" />
  </label>
  <label>
    Password:
    <input type="password" name="password" />
  </label>
</form>
```

```js
const inputs = document.getElementById("my-form").elements;
const inputByIndex = inputs[0];
const inputByName = inputs["username"];
```

### Accessing form controls

 This example gets the form's element list, then iterates over the list, looking for
 `<input>` elements of type
 `"text"` so that some
 form of processing can be performed on them.

```js
const inputs = document.getElementById("my-form").elements;

// Iterate over the form controls
for (let i = 0; i < inputs.length; i++) {
  if (inputs[i].nodeName === "INPUT" && inputs[i].type === "text") {
    // Update text input
    inputs[i].value.toLocaleUpperCase();
  }
}
```

### Disabling form controls

```js
const inputs = document.getElementById("my-form").elements;

// Iterate over the form controls
for (let i = 0; i < inputs.length; i++) {
  // Disable all form controls
  inputs[i].setAttribute("disabled", "");
}
```

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

| Specification |
| --- |
| HTML Standard # dom-form-elements-dev |

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

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


HTMLFormElement: encoding property - Web APIs

HTMLFormElement: encoding property
==================================

The **`HTMLFormElement.encoding`** property is an alternative name for the `enctype` element on the DOM `HTMLFormElement` object.

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

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


HTMLFormElement: submit event - Web APIs

HTMLFormElement: submit event
=============================

The **`submit`** event fires when a `<form>` is submitted.

Note that the `submit` event fires on the `<form>` element itself, and not on any `<button>` or `<input type="submit">` inside it. However, the `SubmitEvent` which is sent to indicate the form's submit action has been triggered includes a `submitter` property, which is the button that was invoked to trigger the submit request.

The `submit` event fires when:

* the user clicks a submit button,
* the user presses `Enter` while editing a field (e.g. <input type="text">) in a form,
* a script calls the `form.requestSubmit()` method

However, the event is *not* sent to the form when a script calls the `form.submit()` method directly.

**Note:** Trying to submit a form that does not pass validation triggers an `invalid` event. In this case, the validation prevents form submission, and thus there is no `submit` event.

Syntax
------

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

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

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

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

A `SubmitEvent`. Inherits from `Event`.

Event

SubmitEventEvent properties
----------------

*In addition to the properties listed below, this interface inherits the properties of its parent interface, `Event`.*

`submitter` Read only

An `HTMLElement` object which identifies the button or other element which was invoked to trigger the form being submitted.

Examples
--------

This example uses `EventTarget.addEventListener()` to listen for form submit, and logs the current `Event.timeStamp` whenever that occurs, then prevents the default action of submitting the form.

### HTML

```html
<form id="form">
  <label>Test field: <input type="text" /></label>
  <br /><br />
  <button type="submit">Submit form</button>
</form>
<p id="log"></p>
```

### JavaScript

```js
function logSubmit(event) {
  log.textContent = `Form Submitted! Timestamp: ${event.timeStamp}`;
  event.preventDefault();
}

const form = document.getElementById("form");
const log = document.getElementById("log");
form.addEventListener("submit", logSubmit);
```

### Result

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

| Specification |
| --- |
| HTML Standard # event-submit |
| HTML Standard # handler-onsubmit |

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

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

See also
--------

* HTML `<form>` element
* Related event: `invalid`


HTMLFormElement: requestSubmit() method - Web APIs

HTMLFormElement: requestSubmit() method
=======================================

 The `HTMLFormElement` method **`requestSubmit()`** requests
 that the form be submitted using a specific submit button.

Syntax
------

```js
requestSubmit()
requestSubmit(submitter)
```

### Parameters

`submitter` Optional

A submit button that is a member of the form.

If the `submitter` specifies `form*` attributes, they will override the form's submission behavior (e.g. `formmethod="POST"`).

If the `submitter` has a `name` attribute or is an `<input type="image">`, its data will be included in the form submission (e.g. `btnName=btnValue`).

If you omit the `submitter` parameter, the form element itself is used as the submitter.

### Return value

None (`undefined`).

### Exceptions

`TypeError`

Thrown if the specified `submitter` is not a submit button.

`NotFoundError` `DOMException`

 Thrown if the specified `submitter` isn't a member of the form on
 which `requestSubmit()` was called. The submitter must be either a
 descendant of the form element or must have a `form`
 attribute referring to the form.

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

 The obvious question is: Why does this method exist, when we've had the
 `submit()` method since the dawn of time?

 The answer is simple. `submit()` submits the form, but that's all it
 does. `requestSubmit()`, on the other hand, acts as if a submit button were
 clicked. The form's content is validated, and the form is submitted only if validation
 succeeds. Once the form has been submitted, the
 `submit` event is sent back to the form
 object.

Examples
--------

 In the example below, the form is submitted by attempting to send the request using
 `requestSubmit()` if it's available. If a submit button with the
 ID `main-submit` is found, that's used to submit the form. Otherwise, the
 form is submitted with no `submitter` parameter, so it's submitted directly
 by the form itself.

 If, on the other hand, `requestSubmit()` isn't available, this code falls
 back to calling the form's `submit()` method.

```js
let myForm = document.querySelector("form");
let submitButton = myForm.querySelector("#main-submit");

if (myForm.requestSubmit) {
  if (submitButton) {
    myForm.requestSubmit(submitButton);
  } else {
    myForm.requestSubmit();
  }
} else {
  myForm.submit();
}
```

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

| Specification |
| --- |
| HTML Standard # dom-form-requestsubmit-dev |

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

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


HTMLFormElement: reportValidity() method - Web APIs

HTMLFormElement: reportValidity() method
========================================

Baseline 2023
-------------

Newly availableSince March 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback

 The **`HTMLFormElement.reportValidity()`** method returns
 `true` if the element's child controls satisfy their validation constraints.
 When `false` is returned, cancelable
 `invalid` events are fired for
 each invalid child and validation problems are reported to the user.

Syntax
------

```js
reportValidity()
```

### Return value

`true` or `false`

Example
-------

```js
document.forms["myform"].addEventListener(
  "submit",
  () => {
    document.forms["myform"].reportValidity();
  },
  false,
);
```

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

| Specification |
| --- |
| HTML Standard # dom-cva-reportvalidity-dev |

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

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


HTMLFormElement: formdata event - Web APIs

HTMLFormElement: formdata event
===============================

The **`formdata`** event fires after the entry list representing the form's data is constructed. This happens when the form is submitted, but can also be triggered by the invocation of a `FormData()` constructor.

This event is not cancelable and does not bubble.

Syntax
------

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

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

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

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

A `FormDataEvent`. Inherits from `Event`.

Event

FormDataEventEvent properties
----------------

*Inherits properties from its parent interface, `Event`.*

`FormDataEvent.formData`

Contains the `FormData` object representing the data contained in the form when the event was fired.

Examples
--------

```js
// grab reference to form

const formElem = document.querySelector("form");

// submit handler

formElem.addEventListener("submit", (e) => {
  // on form submission, prevent default
  e.preventDefault();

  console.log(formElem.querySelector('input[name="field1"]')); // FOO
  console.log(formElem.querySelector('input[name="field2"]')); // BAR

  // construct a FormData object, which fires the formdata event
  const formData = new FormData(formElem);
  // formdata gets modified by the formdata event
  console.log(formData.get("field1")); // foo
  console.log(formData.get("field2")); // bar
});

// formdata handler to retrieve data

formElem.addEventListener("formdata", (e) => {
  console.log("formdata fired");

  // modifies the form data
  const formData = e.formData;
  // formdata gets modified by the formdata event
  formData.set("field1", formData.get("field1").toLowerCase());
  formData.set("field2", formData.get("field2").toLowerCase());
});
```

The `onformdata` version would look like this:

```js
formElem.onformdata = (e) => {
  console.log("formdata fired");

  // modifies the form data
  const formData = e.formData;
  formData.set("field1", formData.get("field1").toLowerCase());
  formData.set("field2", formData.get("field2").toLowerCase());
};
```

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

| Specification |
| --- |
| HTML Standard # event-formdata |

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

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

See also
--------

* HTML `<form>` element
* `FormDataEvent`


HTMLFormElement: enctype property - Web APIs

HTMLFormElement: enctype property
=================================

 The **`HTMLFormElement.enctype`** property is the MIME type of content that is used
 to submit the form to the server. Possible values are:

* `application/x-www-form-urlencoded`: The initial default type.
* `multipart/form-data`: The type that allows file `<input>`
 element(s) to upload file data.
* `text/plain`: Ambiguous format, human-readable content not reliably interpretable by computer.

 This value can be overridden by a `formenctype` attribute
 on a `<button>` or `<input>` element.

Value
-----

A string.

Examples
--------

```js
form.enctype = "application/x-www-form-urlencoded";
```

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

| Specification |
| --- |
| HTML Standard # dom-fs-enctype |

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

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


HTMLFormElement: target property - Web APIs

HTMLFormElement: target property
================================

 The **`target`** property of the `HTMLFormElement`
 interface represents the target of the form's action (i.e., the frame in which to render
 its output).

Value
-----

A string.

Examples
--------

```js
myForm.target = document.frames[1].name;
```

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

| Specification |
| --- |
| HTML Standard # dom-fs-target |

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

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


HTMLFormElement: submit() method - Web APIs

HTMLFormElement: submit() method
================================

 The **`HTMLFormElement.submit()`** method submits a given
 `<form>`.

 This method is similar, but not identical to, activating a form's submit
 `<button>`. When invoking this method directly, however:

* No `submit` event is raised. In particular, the form's `onsubmit` event handler is not run.
* Constraint validation is not triggered.

 The `HTMLFormElement.requestSubmit()` method is identical to activating a
 form's submit `<button>` and does not have these differences.

A form control (such as a submit button) with a `name` or `id` of `submit` will mask the form's `submit` method. Trying to call `myForm.submit();` throws an error "submit is not a function" because in this case `submit` refers to the form control which has a `name` or `id` of `submit`.

`<input>` with attribute type="submit" will not be submitted with the
 form when using **`HTMLFormElement.submit()`**, but it would be
 submitted when you do it with original HTML form submit.

Syntax
------

```js
submit()
```

### Parameters

None.

### Return value

None (`undefined`).

Examples
--------

```js
document.forms["myform"].submit();
```

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

| Specification |
| --- |
| HTML Standard # dom-form-submit-dev |

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

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


HTMLFormElement: method property - Web APIs

HTMLFormElement: method property
================================

 The **`HTMLFormElement.method`** property represents the
 HTTP method used to submit the `<form>`.

Unless explicitly specified, the default method is 'get'.

Value
-----

A string.

Examples
--------

```js
document.forms["myform"].method = "post";

const formElement = document.createElement("form"); // Create a form
document.body.appendChild(formElement);
console.log(formElement.method); // 'get'
```

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

| Specification |
| --- |
| HTML Standard # dom-fs-method |

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

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


HTMLFormElement: action property - Web APIs

HTMLFormElement: action property
================================

 The **`HTMLFormElement.action`** property represents the action
 of the `<form>` element.

 The action of a form is the program that is executed on the server when the form is
 submitted. This property can be retrieved or set.

Value
-----

A string.

Examples
--------

```js
form.action = "/cgi-bin/publish";
```

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

| Specification |
| --- |
| HTML Standard # dom-fs-action |

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

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


HTMLFormElement: name property - Web APIs

HTMLFormElement: name property
==============================

 The **`HTMLFormElement.name`** property represents the name of
 the current `<form>` element as a string.

 If your `<form>` element contains an element named *name* then
 that element overrides the `form.name` property, so that you can't access it.

Value
-----

A string.

Examples
--------

```js
const form1name = document.getElementById("form1").name;

if (form1name !== document.form.form1) {
  // Browser doesn't support this form of reference
}
```

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

| Specification |
| --- |
| HTML Standard # dom-form-name |

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

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


HTMLFormElement: reset() method - Web APIs

HTMLFormElement: reset() method
===============================

 The **`HTMLFormElement.reset()`** method restores a form
 element's default values. This method does the same thing as clicking the form's
 `<input type="reset">` control.

 If a form control (such as a reset button) has a name or id of *reset* it will
 mask the form's reset method. It does not reset other attributes in the input, such as
 `disabled`.

 Note that if `setAttribute()` is called to set
 the value of a particular attribute, a subsequent call to `reset()` won't
 reset the attribute to its default value, but instead will keep the attribute at
 whatever value the `setAttribute()` call set it to.

Syntax
------

```js
reset()
```

### Parameters

None.

### Return value

None (`undefined`).

Examples
--------

```js
document.getElementById("myform").reset();
```

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

| Specification |
| --- |
| HTML Standard # dom-form-reset-dev |

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

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


HTMLFormElement: acceptCharset property - Web APIs

HTMLFormElement: acceptCharset property
=======================================

 The **`HTMLFormElement.acceptCharset`** property represents a
 list of the supported character encodings for the given `<form>` element. This list can be
 comma-separated or space-separated.

Value
-----

A string.

Examples
--------

```js
let inputs = document.forms["myform"].acceptCharset;
```

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

| Specification |
| --- |
| HTML Standard # dom-form-acceptcharset |

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

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


HTMLFormElement: length property - Web APIs

HTMLFormElement: length property
================================

 The **`HTMLFormElement.length`**
 read-only property returns the number of controls in the `<form>`
 element.

 You can access the list of the form's controls using the
 `elements` property.

 This includes both elements that are descendants of the `<form>`
 element as well as elements that are made members of the form using their
 `form` property.

 Elements that are considered for this property are: `<button>`,
 `<fieldset>`, `<input>` (with the exception
 that any whose type is "image" are omitted for historical reasons),
 `<object>`, `<output>`, `<select>`,
 and `<textarea>`.

Value
-----

A number.

Examples
--------

```js
if (document.getElementById("form1").length > 1) {
  // more than one form control here
}
```

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

| Specification |
| --- |
| HTML Standard # dom-form-length-dev |

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

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


HTMLFormElement: reset event - Web APIs

HTMLFormElement: reset event
============================

The **`reset`** event fires when a `<form>` is reset.

Syntax
------

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

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

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

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

A generic `Event`.

Examples
--------

This example uses `EventTarget.addEventListener()` to listen for form resets, and logs the current `Event.timeStamp` whenever that occurs.

### HTML

```html
<form id="form">
  <label>Test field: <input type="text" /></label>
  <br /><br />
  <button type="reset">Reset form</button>
</form>
<p id="log"></p>
```

### JavaScript

```js
function logReset(event) {
  log.textContent = `Form reset! Timestamp: ${event.timeStamp}`;
}

const form = document.getElementById("form");
const log = document.getElementById("log");
form.addEventListener("reset", logReset);
```

### Result

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

| Specification |
| --- |
| HTML Standard # event-reset |

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

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

See also
--------

* HTML `<form>` element


ReadableStreamDefaultController: enqueue() method - Web APIs

ReadableStreamDefaultController: enqueue() method
=================================================

 The **`enqueue()`** method of the
 `ReadableStreamDefaultController` interface enqueues a given chunk in the
 associated stream.

Syntax
------

```js
enqueue(chunk)
```

### Parameters

`chunk`

The chunk to enqueue.

### Return value

None (`undefined`).

### Exceptions

`TypeError`

Thrown if the source object is not a `ReadableStreamDefaultController`.

Examples
--------

 In the following simple example, a custom `ReadableStream` is created using
 a constructor (see our Simple random stream example for the full code). The `start()` function generates a
 random string of text every second and enqueues it into the stream — see
 `controller.enqueue(string)`. A `cancel()` function is also
 provided to stop the generation if `ReadableStream.cancel()` is called for
 any reason.

 When a button is pressed, the generation is stopped, the stream is closed using
 `ReadableStreamDefaultController.close()`, and another function is run,
 which reads the data back out of the stream.

```js
let interval;
const stream = new ReadableStream({
  start(controller) {
    interval = setInterval(() => {
      let string = randomChars();

      // Add the string to the stream
      controller.enqueue(string);

      // show it on the screen
      let listItem = document.createElement("li");
      listItem.textContent = string;
      list1.appendChild(listItem);
    }, 1000);

    button.addEventListener("click", () => {
      clearInterval(interval);
      fetchStream();
      controller.close();
    });
  },
  pull(controller) {
    // We don't really need a pull in this example
  },
  cancel() {
    // This is called if the reader cancels,
    // so we should stop generating strings
    clearInterval(interval);
  },
});
```

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

| Specification |
| --- |
| Streams Standard # ref-for-rs-default-controller-enqueue① |

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

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

See also
--------

* Using readable streams
* `ReadableStreamDefaultController`


ReadableStreamDefaultController: close() method - Web APIs

ReadableStreamDefaultController: close() method
===============================================

 The **`close()`** method of the
 `ReadableStreamDefaultController` interface closes the associated stream.

 Readers will still be able to read any previously-enqueued chunks from the stream,
 but once those are read, the stream will become closed. If you want to completely get
 rid of the stream and discard any enqueued chunks, you'd use
 `ReadableStream.cancel()` or
 `ReadableStreamDefaultReader.cancel()`.

Syntax
------

```js
close()
```

### Parameters

None.

### Return value

None (`undefined`).

### Exceptions

`TypeError`

Thrown if the source object is not a `ReadableStreamDefaultController`.

Examples
--------

 In the following simple example, a custom `ReadableStream` is created using
 a constructor (see our Simple random stream example for the full code). The `start()` function generates a
 random string of text every second and enqueues it into the stream. A
 `cancel()` function is also provided to stop the generation if
 `ReadableStream.cancel()` is called for any reason.

 When a button is pressed, the generation is stopped, the stream is closed using
 `ReadableStreamDefaultController.close()`, and another function is run,
 which reads the data back out of the stream.

```js
let interval;
const stream = new ReadableStream({
  start(controller) {
    interval = setInterval(() => {
      let string = randomChars();

      // Add the string to the stream
      controller.enqueue(string);

      // show it on the screen
      let listItem = document.createElement("li");
      listItem.textContent = string;
      list1.appendChild(listItem);
    }, 1000);

    button.addEventListener("click", () => {
      clearInterval(interval);
      fetchStream();
      controller.close();
    });
  },
  pull(controller) {
    // We don't really need a pull in this example
  },
  cancel() {
    // This is called if the reader cancels,
    // so we should stop generating strings
    clearInterval(interval);
  },
});
```

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

| Specification |
| --- |
| Streams Standard # ref-for-rs-default-controller-close① |

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

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

See also
--------

* Using readable streams
* `ReadableStreamDefaultController`


ReadableStreamDefaultController: error() method - Web APIs

ReadableStreamDefaultController: error() method
===============================================

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

**Note:** The `error()` method can be called
 more than once, and can be called when the stream is not readable.

Syntax
------

```js
error(e)
```

### Parameters

`e`

The error you want future interactions to fail with.

### Return value

None (`undefined`).

### Exceptions

`TypeError`

Thrown if the source object is not a `ReadableStreamDefaultController`.

Examples
--------

 The A readable stream with an underlying push source and backpressure support example in the spec
 provides a good example of using
 `ReadablestreamDefaultController.desiredSize` to manually detect when the
 stream is full and apply backpressure, and also of using `error()` to
 manually trigger a stream error if another part of the system it relies on fails.

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

| Specification |
| --- |
| Streams Standard # rs-default-controller-error |

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

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

See also
--------

* Using readable streams
* `ReadableStreamDefaultController`


ReadableStreamDefaultController: desiredSize property - Web APIs

ReadableStreamDefaultController: desiredSize property
=====================================================

 The **`desiredSize`** read-only property of the
 `ReadableStreamDefaultController` interface returns the desired size
 required to fill the stream's internal queue.

Value
-----

An integer. Note that this can be negative if the queue is over-full.

Examples
--------

 The A readable stream with an underlying push source and backpressure support example in the spec
 provides a good example of using `desiredSize` to manually detect when the
 stream is full and apply backpressure, and also of using
 `ReadablestreamDefaultController.error()` to manually trigger a stream
 error if another part of the system it relies on fails.

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

| Specification |
| --- |
| Streams Standard # ref-for-rs-default-controller-desired-size② |

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

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

See also
--------

* Using readable streams
* `ReadableStreamDefaultController`


RTCSctpTransport: transport property - Web APIs

RTCSctpTransport: transport property
====================================

The **`transport`** read-only property of the `RTCSctpTransport` interface returns a `RTCDtlsTransport` object representing the DTLS transport used for the transmission and receipt of data packets.

Value
-----

A `RTCDtlsTransport` object representing the DTLS transport used for the transmission and receipt of data packets.

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcsctptransport-transport |

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

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

See also
--------

* `RTCSctpTransport`


RTCSctpTransport: statechange event - Web APIs

RTCSctpTransport: statechange event
===================================

A **`statechange`** event is sent to an `RTCSctpTransport` to provide notification when the `RTCSctpTransport.state` property has changed.

Syntax
------

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

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

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

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

A generic `Event`.

Examples
--------

Given an `RTCSctpTransport`, `transport`, and an `updateStatus()` function that presents connection state information to the user, this code sets up an event handler to let the user know when the transport is connected.

```js
pc.addEventListener(
  "statechange",
  (event) => {
    switch (transport.state) {
      case "connected":
        updateStatus("Connection started");
        break;
    }
  },
  false,
);
```

Using `onstatechange`, it looks like this:

```js
transport.onstatechange = (event) => {
  switch (transport.state) {
    case "connected":
      updateStatus("Connection started");
      break;
  }
};
```

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

#### No specification found

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

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

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

See also
--------

* WebRTC API
* `RTCSctpTransport.state`


RTCSctpTransport: maxMessageSize property - Web APIs

RTCSctpTransport: maxMessageSize property
=========================================

The **`maxMessageSize`** read-only property of the `RTCSctpTransport` interface indicates the maximum size of a message that can be sent using the `RTCDataChannel.send()` method.

Value
-----

An integer value giving the maximum size, in bytes, of a message which can be sent using the `RTCDataChannel.send()` method.

Examples
--------

This example shows how you might split up a string into small enough parts to send based on maximum message size.

```js
// Function splits strings to a specified size and returns array.
function splitStringToMax(str, maxLength) {
  const result = [];
  let i = 0;
  while (i < str.length) {
    result.push(str.substring(i, i + maxLength));
    i += maxLength;
  }
  return result;
}

const peerConnection = new RTCPeerConnection(options);
const channel = peerConnection.createDataChannel("chat");
channel.onopen = (event) => {
  const maximumMessageSize = peerConnection.sctp.maxMessageSize;
  const textToSend = "This is my possibly overly long string!";
  splitStringToMax(textToSend, maximumMessageSize).forEach((elem) => {
    channel.send(elem);
  });
};
```

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcsctptransport-maxmessagesize |

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

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

See also
--------

* `RTCSctpTransport`
* Understanding message size limits section of Using WebRTC data channels


RTCSctpTransport: state property - Web APIs

RTCSctpTransport: state property
================================

The **`state`** read-only property of the `RTCSctpTransport` interface provides information which describes a Stream Control Transmission Protocol (SCTP) transport state.

Value
-----

A string whose value is one of the following:

`connecting`

The initial state when the connection is being established.

`connected`

The connection is open for data transmission.

`closed`

The connection is closed and can no longer be used.

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcsctptransport-state |

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

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

See also
--------

* `RTCSctpTransport`


RTCSctpTransport: maxChannels property - Web APIs

RTCSctpTransport: maxChannels property
======================================

The **`maxChannels`** read-only property of the `RTCSctpTransport` interface indicates the maximum number of `RTCDataChannel` objects that can be opened simultaneously.

Value
-----

An integer value indicating the maximum number of `RTCDataChannel` objects that can be opened simultaneously, or `null` before the SCTP transport goes into the "connected" state.

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcsctptransport-maxchannels |

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

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


SpeechSynthesisEvent: SpeechSynthesisEvent() constructor - Web APIs

SpeechSynthesisEvent: SpeechSynthesisEvent() constructor
========================================================

The **`SpeechSynthesisEvent()`** constructor creates a new `SpeechSynthesisEvent` object.

**Note:** A web developer doesn't typically need to call this constructor, as the browser creates these objects itself when firing events.

Syntax
------

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

### Parameters

`type`

 A string with the name of the event.
 It is case-sensitive and browsers set it to `start`, `end`, `error`, `pause`, `resume`, `mark`, or `boundary`.

`options`

An object that, *in addition to the properties defined in `Event()`*, has the following properties:

`utterance`

A `SpeechSynthesisUtterance` object, which is the speech request the event was triggered on.

`charIndex` Optional

The index position of the character in `SpeechSynthesisUtterance.text` that was being spoken when the event was triggered. Its default value is `0`.

`charLength` Optional

The number of characters left to be spoken after the character at the `charIndex` position. Its default value is `0`.

`elapsedTime` Optional

The elapsed time in seconds, after the `SpeechSynthesisUtterance.text` started being spoken, at which the event was triggered. Its default value is `0`.

`name` Optional

The name associated with certain types of events: the name of the SSML marker reached in the case of a `mark` event, or the type of boundary reached in the case of a `boundary` event. It defaults to the empty string (`""`).

### Return value

A new `SpeechSynthesisEvent` object.

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

| Specification |
| --- |
| Web Speech API # dom-speechsynthesisevent-speechsynthesisevent |

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

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

See also
--------

* `SpeechSynthesisErrorEvent`


SpeechSynthesisEvent: charIndex property - Web APIs

SpeechSynthesisEvent: charIndex property
========================================

The **`charIndex`** read-only property of the `SpeechSynthesisUtterance` interface returns the index position of the character in `SpeechSynthesisUtterance.text` that was being spoken when the event was triggered.

Value
-----

A number.

Examples
--------

```js
utterThis.onpause = (event) => {
  const char = event.utterance.text.charAt(event.charIndex);
  console.log(
    `Speech paused at character ${event.charIndex} of "${event.utterance.text}", which is "${char}".`,
  );
};
```

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

| Specification |
| --- |
| Web Speech API # dom-speechsynthesisevent-charindex |

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

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

See also
--------

* Web Speech API


SpeechSynthesisEvent: utterance property - Web APIs

SpeechSynthesisEvent: utterance property
========================================

The **`utterance`** read-only property of the `SpeechSynthesisUtterance` interface returns the `SpeechSynthesisUtterance` instance that the event was triggered on.

Value
-----

A `SpeechSynthesisUtterance` object.

Examples
--------

```js
utterThis.onpause = (event) => {
  const char = event.utterance.text.charAt(event.charIndex);
  console.log(
    `Speech paused at character ${event.charIndex} of "${event.utterance.text}", which is "${char}".`,
  );
};
```

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

| Specification |
| --- |
| Web Speech API # dom-speechsynthesisevent-utterance |

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

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

See also
--------

* Web Speech API


SpeechSynthesisEvent: name property - Web APIs

SpeechSynthesisEvent: name property
===================================

 The **`name`** read-only property of the `SpeechSynthesisUtterance` interface returns the name associated with certain types of events occurring as the `SpeechSynthesisUtterance.text` is being spoken:
 the name of the SSML marker reached in the case of a `mark` event, or the type of boundary reached in the case of a `boundary` event.

Value
-----

A string.

Examples
--------

```js
utterThis.onboundary = (event) => {
  console.log(
    `${event.name} boundary reached after ${event.elapsedTime} seconds.`,
  );
};
```

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

| Specification |
| --- |
| Web Speech API # dom-speechsynthesisevent-name |

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

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

See also
--------

* Web Speech API


SpeechSynthesisEvent: elapsedTime property - Web APIs

SpeechSynthesisEvent: elapsedTime property
==========================================

The **`elapsedTime`** read-only property of the `SpeechSynthesisEvent` returns the elapsed time in seconds, after the `SpeechSynthesisUtterance.text` started being spoken, at which the event was triggered.

Value
-----

A float containing the elapsed time, in seconds.

**Note:** Early versions of the specification required the elapsed time in milliseconds.
 Check the compatibility table below for your browser.

Examples
--------

```js
utterThis.onboundary = (event) => {
  console.log(
    `${event.name} boundary reached after ${event.elapsedTime} seconds.`,
  );
};
```

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

| Specification |
| --- |
| Web Speech API # dom-speechsynthesisevent-elapsedtime |

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

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

See also
--------

* Web Speech API


SpeechSynthesisEvent: charLength property - Web APIs

SpeechSynthesisEvent: charLength property
=========================================

The read-only **`charLength`** property of the `SpeechSynthesisEvent` interface returns the number of characters left to be spoken after the character at the `charIndex` position.

If the speech engine can't determine it, it returns 0.

Value
-----

An integer.

Examples
--------

```js
utterThis.onpause = (event) => {
  const char = event.utterance.text.charAt(event.charIndex);
  const charLeft = event.charLength;
  if (charLeft) {
    console.log(
      `Speech paused. There are still ${charLeft} characters to be spoken.`,
    );
  } else {
    console.log(
      "Speech paused. The underlying speech engine can't tell how many characters are left.",
    );
  }
};
```

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

| Specification |
| --- |
| Web Speech API # dom-speechsynthesisevent-charlength |

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

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


HTMLSelectElement: selectedOptions property - Web APIs

HTMLSelectElement: selectedOptions property
===========================================

 The **read-only** `HTMLSelectElement` property
 **`selectedOptions`** contains a list of the
 `<option>` elements contained within the `<select>`
 element that are currently selected. The list of selected options is an
 `HTMLCollection` object with one entry per currently selected option.

 An option is considered selected if it has an `HTMLOptionElement.selected`
 attribute.

Value
-----

 An `HTMLCollection` which lists every currently selected
 `HTMLOptionElement` which is either a child of the
 `HTMLSelectElement` or of an `HTMLOptGroupElement` within the
 `<select>` element.

 In other words, any option contained within the `<select>` element may
 be part of the results, but option groups are not included in the list.

 If no options are currently selected, the collection is empty and returns a
 `length` of 0.

Examples
--------

 In this example, a `<select>` element with a number of options is used
 to let the user order various food items.

### HTML

 The HTML that creates the selection box and the `<option>` elements
 representing each of the food choices looks like this:

```html
<label for="foods">What do you want to eat?</label><br />
<select id="foods" name="foods" size="7" multiple>
  <option value="1">Burrito</option>
  <option value="2">Cheeseburger</option>
  <option value="3">Double Bacon Burger Supreme</option>
  <option value="4">Pepperoni Pizza</option>
  <option value="5">Taco</option>
</select>
<br />
<button name="order" id="order">Order Now</button>
<p id="output"></p>
```

 The `<select>` element is set to allow multiple items to be selected,
 and it is 7 rows tall. Note also the `<button>`, whose role it is to
 trigger fetching the `HTMLCollection` of selected elements using the
 `selected` property.

### JavaScript

 The JavaScript code that establishes the event handler for the button, as well as the
 event handler itself, looks like this:

```js
let orderButton = document.getElementById("order");
let itemList = document.getElementById("foods");
let outputBox = document.getElementById("output");

orderButton.addEventListener(
  "click",
  () => {
    let collection = itemList.selectedOptions;
    let output = "";

    for (let i = 0; i < collection.length; i++) {
      if (output === "") {
        output = "Your order for the following items has been placed: ";
      }
      output += collection[i].label;

      if (i === collection.length - 2 && collection.length < 3) {
        output += " and ";
      } else if (i < collection.length - 2) {
        output += ", ";
      } else if (i === collection.length - 2) {
        output += ", and ";
      }
    }

    if (output === "") {
      output = "You didn't order anything!";
    }

    outputBox.innerHTML = output;
  },
  false,
);
```

 This script sets up a `click` event listener on the "Order Now" button. When
 clicked, the event handler fetches the list of selected options using
 `selectedOptions`, then iterates over the options in the list. A string is
 constructed to list the ordered items, with logic to build the list using proper English
 grammar rules (including a serial comma).

### Result

The resulting content looks like this in action:

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

| Specification |
| --- |
| HTML Standard # dom-select-selectedoptions-dev |

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

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

See also
--------

* Drop-down controls


HTMLSelectElement: showPicker() method - Web APIs

HTMLSelectElement: showPicker() method
======================================

The **`HTMLSelectElement.showPicker()`** method displays the browser picker for a `select` element.

This is the same picker that would normally be displayed when the element is selected, but can be triggered from a button press or other user interaction.

Syntax
------

```js
showPicker()
```

### Parameters

None.

### Return value

None (`undefined`).

### Exceptions

`InvalidStateError` `DOMException`

Thrown if the element is not mutable, meaning that the user cannot modify it and/or that it cannot be automatically prefilled.

`NotAllowedError` `DOMException`

Thrown if not explicitly triggered by a user action such as a touch gesture or mouse click (the picker requires Transient activation).

`NotSupportedError` `DOMException`

Thrown if the element associated with the picker is not being rendered.

`SecurityError` `DOMException`

Thrown if called in a cross-origin iframe.

Security considerations
-----------------------

Transient user activation is required.
 The user has to interact with the page or a UI element in order for this feature to work.

The method is only allowed to be called in same-origin iframes; an exception is thrown if this is called in a cross-origin iframe.

Examples
--------

### Feature detection

The code below shows how to check if `showPicker()` is supported:

```js
if ("showPicker" in HTMLSelectElement.prototype) {
  // showPicker() is supported.
}
```

### Launching the picker

This example shows how to use a button to launch the picker for a `<select>` element with two options.

#### HTML

```html
<p>
  <select>
    <option value="1">One</option>
    <option value="2">Two</option>
  </select>
  <button type="button">Show Picker</button>
</p>
```

#### JavaScript

 The code gets the `<button>` and adds a listener for its `click` event.
 The event handler gets the `<select>` element and calls `showPicker()` on it.

```js
const button = document.querySelector("button");
button.addEventListener("click", (event) => {
  const select = event.srcElement.previousElementSibling;
  try {
    select.showPicker();
  } catch (error) {
    window.alert(error);
  }
});
```

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

| Specification |
| --- |
| HTML Standard # dom-select-showpicker |

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

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

See also
--------

* `<select>`
* `HTMLSelectElement`
* `HTMLInputElement.showPicker()`


HTMLSelectElement: item() method - Web APIs

HTMLSelectElement: item() method
================================

 The **`HTMLSelectElement.item()`** method returns the
 `Element` corresponding to the `HTMLOptionElement` whose
 position in the options list corresponds to the index given in the parameter, or
 `null` if there are none.

 In JavaScript, using the array bracket syntax with an `unsigned long`, like
 `selectElt[index]` is equivalent to
 `selectElt.namedItem(index)`.

Syntax
------

```js
item(index)
// or collection[index]
```

### Parameters

* `index` is an `unsigned long`.
### Return value

* `item` is a `HTMLOptionElement`.
Examples
--------

### HTML

```html
<form>
  <select id="myFormControl">
    <option id="o1">Opt 1</option>
    <option id="o2">Opt 2</option>
  </select>
</form>
```

### JavaScript

```js
// Returns the HTMLOptionElement representing #o2
elem1 = document.forms[0]["myFormControl"][1];
```

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

| Specification |
| --- |
| HTML Standard # dom-select-item-dev |

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

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

See also
--------

* `HTMLSelectElement` that implements it.


HTMLSelectElement: form property - Web APIs

HTMLSelectElement: form property
================================

 The **`HTMLSelectElement.form`** read-only property returns a
 `HTMLFormElement` representing the form that this element is associated
 with. If the element is not associated with a `<form>` element, then
 it returns `null`.

Value
-----

A `HTMLFormElement`.

Examples
--------

```html
<form id="pet-form">
  <label for="pet-select">Choose a pet</label>
  <select name="pets" id="pet-select">
    <option value="dog">Dog</option>
    <option value="cat">Cat</option>
    <option value="parrot">Parrot</option>
  </select>

  <button type="submit">Submit</button>
</form>

<label for="lunch-select">Choose your lunch</label>
<select name="lunch" id="lunch-select">
  <option value="salad">Salad</option>
  <option value="sandwich">Sandwich</option>
</select>

<script>
 const petSelect = document.getElementById("pet-select");
 const petForm = petSelect.form; // <form id="pet-form">

 const lunchSelect = document.getElementById("lunch-select");
 const lunchForm = lunchSelect.form; // null
</script>
```

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

| Specification |
| --- |
| HTML Standard # dom-fae-form-dev |

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

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


HTMLSelectElement: remove() method - Web APIs

HTMLSelectElement: remove() method
==================================

 The **`HTMLSelectElement.remove()`** method removes the element
 at the specified index from the options collection for this select element.

Syntax
------

```js
remove(index)
```

### Parameters

* `index` is a zero-based long for the index of the `HTMLOptionElement`
 to remove from the collection. If the index is not found the method has no effect.
### Return value

None (`undefined`).

Examples
--------

```html
<select id="existingList" name="existingList">
  <option value="1">Option: Value 1</option>
  <option value="2">Option: Value 2</option>
  <option value="3">Option: Value 3</option>
</select>
```

```js
let sel = document.getElementById("existingList");
sel.remove(1);
```

HTML is now:

```html
<select id="existingList" name="existingList">
  <option value="1">Option: Value 1</option>
  <option value="3">Option: Value 3</option>
</select>
```

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

| Specification |
| --- |
| HTML Standard # dom-select-remove |

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

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

See also
--------

* `Element.remove`, the method that gets called when remove is called
 without arguments on a `HTMLSelectElement`.
* `HTMLSelectElement` that implements it.


HTMLSelectElement: type property - Web APIs

HTMLSelectElement: type property
================================

 The **`HTMLSelectElement.type`**
 read-only property returns the form control's `type`.

Value
-----

One of the following:

* `"select-multiple"` if multiple values can be selected.
* `"select-one"` if only one value can be selected.
Examples
--------

```js
switch (select.type) {
  case "select-multiple":
    // Multiple values may be selected
    break;
  case "select-one":
    // Only one value may be selected
    break;
  default:
  // Non-standard value (or this isn't a SELECT element)
}
```

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

| Specification |
| --- |
| HTML Standard # dom-select-type-dev |

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

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

See also
--------

* The `<select>` HTML element, implementing this interface.


HTMLSelectElement: add() method - Web APIs

HTMLSelectElement: add() method
===============================

 The **`HTMLSelectElement.add()`** method adds an element to the
 collection of `option` elements for this `select` element.

Syntax
------

```js
add(item)
add(item, before)
```

### Parameters

`item`

 An `HTMLOptionElement` or
 `HTMLOptGroupElement`

`before` Optional

 An element of the collection, or an index of type
 *long*, representing the *item* should be inserted before. If this
 parameter is `null` (or the index does not exist), the new element is
 appended to the end of the collection.

### Return value

None (`undefined`).

### Exceptions

`HierarchyRequestError` `DOMException`

Thrown if the *item* passed to the method is an ancestor of the `HTMLSelectElement`.

Examples
--------

### Creating Elements from Scratch

```js
const sel = document.createElement("select");
const opt1 = document.createElement("option");
const opt2 = document.createElement("option");

opt1.value = "1";
opt1.text = "Option: Value 1";

opt2.value = "2";
opt2.text = "Option: Value 2";

sel.add(opt1, null);
sel.add(opt2, null);

/\*
 Produces the following, conceptually:

 <select>
 <option value="1">Option: Value 1</option>
 <option value="2">Option: Value 2</option>
 </select>
\*/
```

The before parameter is optional. So the following is accepted.

```js
sel.add(opt1);
sel.add(opt2);
```

### Append to an Existing Collection

```js
const sel = document.getElementById("existingList");

const opt = document.createElement("option");
opt.value = "3";
opt.text = "Option: Value 3";

sel.add(opt, null);

/\*
 Takes the existing following select object:

 <select id="existingList">
 <option value="1">Option: Value 1</option>
 <option value="2">Option: Value 2</option>
 </select>

 And changes it to:

 <select id="existingList">
 <option value="1">Option: Value 1</option>
 <option value="2">Option: Value 2</option>
 <option value="3">Option: Value 3</option>
 </select>
\*/
```

The before parameter is optional. So the following is accepted.

```js
sel.add(opt);
```

### Inserting to an Existing Collection

```js
const sel = document.getElementById("existingList");

const opt = document.createElement("option");
opt.value = "3";
opt.text = "Option: Value 3";

sel.add(opt, sel.options[1]);

/\*
 Takes the existing following select object:

 <select id="existingList">
 <option value="1">Option: Value 1</option>
 <option value="2">Option: Value 2</option>
 </select>

 And changes it to:

 <select id="existingList">
 <option value="1">Option: Value 1</option>
 <option value="3">Option: Value 3</option>
 <option value="2">Option: Value 2</option>
 </select>
\*/
```

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

| Specification |
| --- |
| HTML Standard # dom-select-add-dev |

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

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


HTMLSelectElement: checkValidity() method - Web APIs

HTMLSelectElement: checkValidity() method
=========================================

Baseline 2023
-------------

Newly availableSince March 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback

 The **`HTMLSelectElement.checkValidity()`** method checks
 whether the element has any constraints and whether it satisfies them. If the element
 fails its constraints, the browser fires a cancelable `invalid` event at the
 element, and then returns `false`.

Syntax
------

```js
checkValidity()
```

### Parameters

None.

### Return value

Returns `true` if the value of the element has no validity problems; otherwise returns `false`.

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

| Specification |
| --- |
| HTML Standard # dom-cva-checkvalidity-dev |

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

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

See also
--------

* Form validation


HTMLSelectElement: options property - Web APIs

HTMLSelectElement: options property
===================================

 The **`HTMLSelectElement.options`** read-only property returns
 a `HTMLOptionsCollection` of the `<option>` elements
 contained by the `<select>` element.

Value
-----

 A `HTMLOptionsCollection` containing the `<option>`
 elements contained by the `<select>` element.

Examples
--------

### HTML

```html
<label for="test">Label</label>
<select id="test">
  <option value="1">Option 1</option>
  <option value="2">Option 2</option>
</select>
```

### JavaScript

```js
window.addEventListener("DOMContentLoaded", () => {
  const select = document.getElementById("test");
  for (const option of select.options) {
    console.log(option.label); // "Option 1" and "Option 2"
  }
});
```

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

| Specification |
| --- |
| HTML Standard # dom-select-options-dev |

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

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


HTMLSelectElement: selectedIndex property - Web APIs

HTMLSelectElement: selectedIndex property
=========================================

 The **`HTMLSelectElement.selectedIndex`** property is a
 `long` that reflects the index of the first or last selected
 `<option>` element, depending on the value of `multiple`. The
 value `-1` indicates that no element is selected.

Value
-----

A number.

Examples
--------

### HTML

```html
<p id="p">selectedIndex: 0</p>

<select id="select">
  <option selected>Option A</option>
  <option>Option B</option>
  <option>Option C</option>
  <option>Option D</option>
  <option>Option E</option>
</select>
```

### JavaScript

```js
const selectElem = document.getElementById("select");
const pElem = document.getElementById("p");

// When a new <option> is selected
selectElem.addEventListener("change", () => {
  const index = selectElem.selectedIndex;
  // Add that data to the <p>
  pElem.textContent = `selectedIndex: ${index}`;
});
```

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

| Specification |
| --- |
| HTML Standard # dom-select-selectedindex-dev |

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

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


HTMLSelectElement: labels property - Web APIs

HTMLSelectElement: labels property
==================================

 The **`HTMLSelectElement.labels`** read-only property returns a
 `NodeList` of the `<label>` elements associated with the
 `<select>` element.

Value
-----

 A `NodeList` containing the `<label>` elements associated
 with the `<select>` element.

Examples
--------

### HTML

```html
<label id="label1" for="test">Label 1</label>
<select id="test">
  <option value="1">Option 1</option>
  <option value="2">Option 2</option>
</select>
<label id="label2" for="test">Label 2</label>
```

### JavaScript

```js
window.addEventListener("DOMContentLoaded", () => {
  const select = document.getElementById("test");
  for (const label of select.labels) {
    console.log(label.textContent); // "Label 1" and "Label 2"
  }
});
```

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

| Specification |
| --- |
| HTML Standard # dom-lfe-labels-dev |

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

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


HTMLSelectElement: namedItem() method - Web APIs

HTMLSelectElement: namedItem() method
=====================================

 The **`HTMLSelectElement.namedItem()`** method returns the
 `HTMLOptionElement` corresponding to the `HTMLOptionElement`
 whose `name` or `id` match the specified name, or
 `null` if no option matches.

In JavaScript, using `selectElt.namedItem('value')` is equivalent to `selectElt.options.namedItem('value')`.

Syntax
------

```js
namedItem(str)
```

### Parameters

* `str` is a string.
### Return value

* `item` is a `HTMLOptionElement`.
Examples
--------

### HTML

```html
<form>
  <select id="myFormControl">
    <option id="o1">Opt 1</option>
    <option id="o2">Opt 2</option>
  </select>
</form>
```

### JavaScript

```js
let selectElt = document.getElementById("myFormControl");
elem1 = selectElt.namedItem("o1"); // Returns the HTMLOptionElement representing #o1
```

But, you cannot write:

```js
let selectElt = document.getElementById("myFormControl");
elem1 = selectElt.o1; // Returns undefined
elem1 = selectElt["o1"]; // Returns undefined
```

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

| Specification |
| --- |
| HTML Standard # dom-select-nameditem-dev |

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

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

See also
--------

* `HTMLSelectElement` that implements it.


HTMLSelectElement: disabled property - Web APIs

HTMLSelectElement: disabled property
====================================

 The **`HTMLSelectElement.disabled`** property is a boolean value that reflects the
 `disabled`
 HTML attribute, which indicates whether the control is disabled. If it is disabled, it
 does not accept clicks. A disabled element is unusable and un-clickable.

Value
-----

A boolean value.

Examples
--------

### HTML

```html
<label>
  Allow drinks?
  <input id="allow-drinks" type="checkbox" />
</label>

<label for="drink-select">Drink selection:</label>
<select id="drink-select" disabled>
  <option value="1">Water</option>
  <option value="2">Beer</option>
  <option value="3">Pepsi</option>
  <option value="4">Whisky</option>
</select>
```

### JavaScript

```js
const allowDrinksCheckbox = document.getElementById("allow-drinks");
const drinkSelect = document.getElementById("drink-select");

allowDrinksCheckbox.addEventListener(
  "change",
  (event) => {
    drinkSelect.disabled = !event.target.checked;
  },
  false,
);
```

### Result

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

| Specification |
| --- |
| HTML Standard # dom-fe-disabled |

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

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


HTMLSelectElement: setCustomValidity() method - Web APIs

HTMLSelectElement: setCustomValidity() method
=============================================

Baseline 2023
-------------

Newly availableSince March 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback

 The **`HTMLSelectElement.setCustomValidity()`** method sets the
 custom validity message for the selection element to the specified message. Use the
 empty string to indicate that the element does *not* have a custom validity
 error.

Syntax
------

```js
setCustomValidity(string)
```

### Parameters

* `string` is the string containing the error message.
### Return value

None (`undefined`).

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

| Specification |
| --- |
| HTML Standard # dom-cva-setcustomvalidity-dev |

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

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

See also
--------

* Form validation.


MediaKeys: setServerCertificate() method - Web APIs

MediaKeys: setServerCertificate() method
========================================

 The **`MediaKeys.setServerCertificate()`** method provides a
 server certificate to be used to encrypt messages to the license server.

Syntax
------

```js
setServerCertificate(serverCertificate)
```

### Parameters

`serverCertificate`

An `ArrayBuffer`, a `TypedArray`, or a `DataView` object containing the server certificate. The contents are Key System-specific. It MUST NOT contain executable code.

### Return value

A `Promise` that resolves to a boolean. If the Key System implementation represented by this object's content decryption module's implementation value does not support server certificates, return a promise resolved with false.

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

| Specification |
| --- |
| Encrypted Media Extensions # dom-mediakeys-setservercertificate |

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

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


MediaKeys: createSession() method - Web APIs

MediaKeys: createSession() method
=================================

 The `MediaKeys.createSession()` method returns a new
 `MediaKeySession` object, which represents a context for message exchange
 with a content decryption module (CDM).

Syntax
------

```js
createSession()
createSession(mediaKeySessionType)
```

### Parameters

`mediaKeySessionType` Optional

A string. Either "temporary" or "persistent-license". The default value is "temporary".

### Return value

A new `MediaKeySession` object.

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

| Specification |
| --- |
| Encrypted Media Extensions # dom-mediakeys-createsession |

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

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


MIDIMessageEvent: data property - Web APIs

MIDIMessageEvent: data property
===============================

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

The **`data`** read-only property of the `MIDIMessageEvent` interface returns the MIDI data bytes of a single MIDI message.

Value
-----

A `Uint8Array`.

Examples
--------

In the following example `midimessage` events are listened for on all input ports. When a message is received the value of `data` is printed to the console.

```js
inputs.forEach((input) => {
  input.onmidimessage = (message) => {
    console.log(message.data);
  };
});
```

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

| Specification |
| --- |
| Web MIDI API # dom-midimessageevent-data |

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

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


MIDIMessageEvent: MIDIMessageEvent() constructor - Web APIs

MIDIMessageEvent: MIDIMessageEvent() constructor
================================================

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

The **`MIDIMessageEvent()`** constructor creates a new `MIDIMessageEvent` object. Typically this constructor is not used as events are created when a `MIDIInput` finishes receiving one or more MIDI messages.

Syntax
------

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

### Parameters

`type`

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

`options` Optional

An object that, *in addition of the properties defined in `Event()`*, can have the following properties:

`data`

A `Uint8Array` instance containing the data bytes of the MIDI message.

### Return value

A new `MIDIMessageEvent` object.

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

| Specification |
| --- |
| Web MIDI API # dom-midimessageevent-constructor |

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

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


USBConnectionEvent: USBConnectionEvent() constructor - Web APIs

USBConnectionEvent: USBConnectionEvent() constructor
====================================================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

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

 The **`USBConnectionEvent()`** constructor creates a new `USBConnectionEvent` object.
 This constructor is not typically used,
 it is created by the browser in response to the connection and disconnection of a USB device.

Syntax
------

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

### Parameters

`type`

 A string with the name of the event.
 It is case-sensitive and browsers set it to `connect` or `disconnect`.

`options`

An object that, *in addition of the properties defined in `Event()`*, can have the following properties:

`device`

A `USBDevice` representing the USB device being connected or disconnected.

### Return value

A new `USBConnectionEvent` object.

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

| Specification |
| --- |
| WebUSB API # dom-usbconnectionevent-usbconnectionevent |

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

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


USBConnectionEvent: device property - Web APIs

USBConnectionEvent: device property
===================================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

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

The **`device`** read-only property of the `USBConnectionEvent` interface returns a `USBDevice` object representing the device being connected or disconnected.

Value
-----

A `USBDevice` object.

Examples
--------

Connecting a USB device fires the `connect` event. The current `USBDevice` is returned by calling `event.device`.

```js
navigator.usb.addEventListener("connect", (event) => {
  console.log(event.device);
});
```

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

| Specification |
| --- |
| WebUSB API # dom-usbconnectionevent-device |

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

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


StaticRange: endOffset property - Web APIs

StaticRange: endOffset property
===============================

 The **`endOffset`** property of the `StaticRange`
 interface returns the offset into the end node of the range's end position.

Value
-----

 An integer value indicating the number of characters into the `Node`
 indicated by `endContainer` at which the final
 character of the range is located.

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-range-endoffset① |

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

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


StaticRange: StaticRange() constructor - Web APIs

StaticRange: StaticRange() constructor
======================================

 The **`StaticRange()`** constructor
 creates a new `StaticRange` object representing a span of content within
 the DOM.

 This constructor includes properties identifying the start and end positions of
 the range as well as a Boolean indicating whether or not the range is
 **collapsed** (that is, empty).

Syntax
------

```js
new StaticRange(rangeSpec)
```

### Parameters

`rangeSpec`

 The required `rangeSpec` parameter is an object
 containing the four following properties:

`startContainer`

The `Node` in which the starting point of the range is located.

`startOffset`

 The offset into the starting node at which the first character of the range is
 found.

`endContainer`

The `Node` in which the end point of the range is located.

`endOffset`

 The offset into the node indicated by `endOffset` at which the last
 character in the range is located.

### Return value

 A new `StaticRange` object initialized with the values given in
 the `rangeSpec` object.

### Exceptions

`InvalidNodeTypeError`

 A `DOMException` fired if either or both of the
 `startContainer` and/or `endContainer` are a type of node which
 you can't include in a range. Those node types
 are `Node.DOCUMENT_TYPE_NODE` (representing the `DocumentType`
 node derived from the DTD identified using the `doctype`
 preamble in the HTML, for example) and the `Attr` node describing an
 attribute of an element on the DOM.

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

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

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

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


StaticRange: collapsed property - Web APIs

StaticRange: collapsed property
===============================

 The **`collapsed`** read-only property
 of the `StaticRange` interface returns `true` if the range's
 start position and end position are the same.

Value
-----

 A boolean value which is `true` if the range
 is **collapsed**. A collapsed range is one in which the start and end
 positions are the same, resulting in a zero-character-long range.

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-range-collapsed① |

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

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


StaticRange: startOffset property - Web APIs

StaticRange: startOffset property
=================================

 The read-only **`startOffset`**
 property of the `StaticRange` interface returns the offset into the start
 node of the range's start position.

Value
-----

 An integer value indicating the number of characters into the `Node`
 indicated by `startContainer` at which the
 first character of the range is located.

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-range-startoffset① |

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

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


StaticRange: endContainer property - Web APIs

StaticRange: endContainer property
==================================

The **`endContainer`** property of the `StaticRange` interface returns the end `Node` for the range.

Value
-----

The DOM `Node` which contains the final character of the range.

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-range-endcontainer① |

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

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


StaticRange: startContainer property - Web APIs

StaticRange: startContainer property
====================================

 The read-only **`startContainer`**
 property of the `StaticRange` interface returns the start
 `Node` for the range.

Value
-----

The DOM `Node` inside which the start position of the range is found.

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-range-startcontainer① |

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

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


FocusEvent: relatedTarget property - Web APIs

FocusEvent: relatedTarget property
==================================

 The **`FocusEvent.relatedTarget`** read-only property is the
 secondary target, depending on the type of event:

| Event name | `target` | `relatedTarget` |
| --- | --- | --- |
| `blur` | The `EventTarget` losing focus | The `EventTarget` receiving focus (if any). |
| `focus` | The `EventTarget` receiving focus | The `EventTarget` losing focus (if any) |
| `focusin` | The `EventTarget` receiving focus | The `EventTarget` losing focus (if any) |
| `focusout` | The `EventTarget` losing focus | The `EventTarget` receiving focus (if any) |

 Note that many elements can't have focus, which is a common reason for `relatedTarget` to be
 `null`. `relatedTarget` may also be set to `null` for
 security reasons, like when tabbing in or out of a page.

`MouseEvent.relatedTarget` is a similar property for mouse events.

Value
-----

An instance of `EventTarget`.

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

| Specification |
| --- |
| UI Events # dom-focusevent-relatedtarget |

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

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

See also
--------

* The `FocusEvent` interface it belongs to.


FocusEvent: FocusEvent() constructor - Web APIs

FocusEvent: FocusEvent() constructor
====================================

 The **`FocusEvent()`** constructor returns a newly created
 `FocusEvent` object with an optional `EventTarget`. When the
 event has both a source and a destination, the `relatedTarget` value must be
 set to the other target.

Syntax
------

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

### Parameters

*The `FocusEvent()` constructor also inherits arguments from
`UIEvent()` and from `Event()`.*

`type`

 A string with the name of the event.
 It is case-sensitive and browsers set it to `blur`, `focus`, `focusin`, or `focusout`.

`options` Optional

An object that, in addition of the properties defined in `UIEvent()`, can have the following properties:

`relatedTarget` Optional

An `EventTarget` representing the secondary target of a `FocusEvent`. It defaults to `null`.

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

| Specification |
| --- |
| UI Events # dom-focusevent-focusevent |

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

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

See also
--------

* The `FocusEvent` interface it belongs to.


XRLayerEvent: layer property - Web APIs

XRLayerEvent: layer property
============================

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

The **`layer`** property of the `XRLayerEvent` interface is a reference to the `XRLayer` which generated the event.

Value
-----

An `XRLayer`.

Examples
--------

### Using the `layer` property

In this example, the `layer` property is used to obtain the `XRLayer` object that sent the event.

```js
myLayer.addEventListener("redraw", (e) => {
  if (typeof e.layer === "XRQuadLayer") {
    // redraw quad layer
  }
});
```

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

| Specification |
| --- |
| WebXR Layers API Level 1 # dom-xrlayerevent-layer |

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

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

See also
--------

* `XRLayer`