recursal/MDN huggingface dataset:
RTCIceTransport: selectedcandidatepairchange event
==================================================

A **`selectedcandidatepairchange`** event is sent to an `RTCIceTransport` when the ICE agent selects a new pair of candidates that describe the endpoints of a viable connection.

The pair of candidates is in turn described by an `RTCIceCandidatePair` object which contains one `RTCIceCandidate` representing the local end of the connection, and another representing the remote end of the connection.

Together, the candidates can be used to establish a connection to be used by the `RTCIceTransport`, and, by extension, by an `RTCPeerConnection`.

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("selectedcandidatepairchange", (event) => {});

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

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

A generic `Event`.

Examples
--------

This example creates an event handler for `selectedcandidatepairchange` that updates a display providing the user information about the progress of the ICE negotiation for an `RTCPeerConnection` called `pc`.


```js
let iceTransport = pc.getSenders[0].transport.iceTransport;
let localProtoElem = document.getElementById("local-protocol");
let remoteProtoElem = document.getElementById("remote-protocol");

iceTransport.addEventListener(
  "selectedcandidatepairchange",
  (ev) => {
    let pair = iceTransport.getSelectedCandidatePair();
    localProtoElem.innerText = pair.local.protocol.toUpperCase();
    remoteProtoElem.innerText = pair.remote.protocol.toUpperCase();
  },
  false,
);
```


This can also be done by setting the `onselectedcandidatepairchange` event handler property directly.


```js
let iceTransport = pc.getSenders[0].transport.iceTransport;
let localProtoElem = document.getElementById("local-protocol");
let remoteProtoElem = document.getElementById("remote-protocol");

iceTransport.onselectedcandidatepairchange = (ev) => {
  let pair = iceTransport.getSelectedCandidatePair();
  localProtoElem.innerText = pair.local.protocol.toUpperCase();
  remoteProtoElem.innerText = pair.remote.protocol.toUpperCase();
};
```

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # event-icetransport-selectedcandidatepairchange |
| WebRTC: Real-Time Communication in Browsers # dom-rtcicetransport-onselectedcandidatepairchange |

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

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

See also
--------

* WebRTC API
* WebRTC connectivity
### Related RTCIceTransport events

* `statechange`
* `gatheringstatechange`
### Related RTCPeerConnection events

* `negotiationneeded`
* `signalingstatechange`
* `iceconnectionstatechange`
* `icegatheringstatechange`
* `connectionstatechange`
RTCIceTransport: role property
==============================

 The read-only **`RTCIceTransport`**
 property **`role`** indicates which ICE role
 the transport is fulfilling: that of the controlling agent, or the agent that is being
 controlled.

 You can learn more about ICE roles in
 Choosing a candidate pair.

Value
-----

A string specifying whether the `RTCIceTransport` represents the controlling agent or the controlled agent.

The value must be one of the following:

`"controlled"`

The transport is the controlled agent.

`"controlling"`

The `RTCIceTransport` object is serving as the controlling agent.

`"unknown"`

The role has not yet been determined.

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-icetransport-role |

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
RTCIceTransport: gatheringState property
========================================

The read-only property **`gatheringState`** property of the `RTCIceTransport` interface returns a string that indicates the current gathering state of the ICE agent: `"new"`, `"gathering"`, or `"complete"`.

Value
-----

A string that indicates the current state of the ICE agent's candidate gathering process:

`"new"`

The `RTCIceTransport` is newly created and has not yet started to gather ICE candidates.

`"gathering"`

The transport is in the process of gathering candidates.

`"complete"`

The transport has finished gathering ICE candidates and has sent the end-of-candidates indicator to the remote device. The transport won't gather any further candidates unless an ICE restart occurs, at which point the gathering process starts over from scratch.

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-icetransport-gatheringstate |

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
RTCIceTransport: getLocalParameters() method
============================================

 The **`RTCIceTransport`** method
 **`getLocalParameters()`** returns an
 `RTCIceParameters` object which provides information uniquely identifying
 the local peer for the duration of the ICE session.

 The local peer's parameters are obtained during ICE signaling and delivered to the
 transport when the client calls `RTCPeerConnection.setLocalDescription()`.

Syntax
------


```js
getLocalParameters()
```

### Parameters

None.

### Return value

 An `RTCIceParameters` object indicating the
 `usernameFragment` and
 `password` which uniquely identify the local
 peer for the duration of the ICE session.

Returns `null` if the parameters have not yet been received.

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcicetransport-getlocalparameters |

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
RTCIceTransport: statechange event
==================================

A **`statechange`** event occurs when the `RTCIceTransport` changes state. The `state` can be used to determine how far through the process of examining, verifying, and selecting a valid candidate pair is prior to successfully connecting the two peers for WebRTC communications.

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("statechange", (event) => {});

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

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

A generic `Event`.

Examples
--------

Given an `RTCPeerConnection`, `pc`, the following code creates an event handler that calls a function named `handleFailure()` if the ICE transport enters a failure state.


```js
let iceTransport = pc.getSenders()[0].transport.iceTransport;

iceTransport.addEventListener(
  "statechange",
  (ev) => {
    if (iceTransport.state === "failed") {
      handleFailure(pc);
    }
  },
  false,
);
```


The same code, using the `onstatechange` event handler property, looks like this:


```js
let iceTransport = pc.getSenders()[0].transport.iceTransport;

iceTransport.onstatechange = (ev) => {
  if (iceTransport.state === "failed") {
    handleFailure(pc);
  }
};
```

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # event-icetransport-statechange |
| WebRTC: Real-Time Communication in Browsers # dom-rtcicetransport-onstatechange |

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

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

See also
--------

* WebRTC API
* WebRTC connectivity
### Related RTCIceTransport events

* `gatheringstatechange`
* `selectedcandidatepairchange`
### Related RTCPeerConnection events

* `negotiationneeded`
* `signalingstatechange`
* `iceconnectionstatechange`
* `icegatheringstatechange`
* `connectionstatechange`
RTCIceTransport: getSelectedCandidatePair() method
==================================================

 The `RTCIceTransport` method
 **`getSelectedCandidatePair()`** returns an
 `RTCIceCandidatePair` object containing the current best-choice pair
 of ICE candidates describing the configuration of the endpoints of the transport.

Syntax
------


```js
getSelectedCandidatePair()
```

### Parameters

None.

### Return value

 A `RTCIceCandidatePair` object describing the configurations of the
 currently-selected candidate pair's two endpoints.
 `local` describes the configuration of the
 local end of the connection, while `remote`
 describes the remote peer's configuration.

The return value is `null` if no pair of candidates has been selected yet.

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

 As the ICE agent performs negotiation of a `RTCPeerConnection`, it gathers
 and analyzes candidate configurations from each the two peers. As soon as it finds an
 acceptable matching pair of candidates, meeting the requirements for the connection, a
 `selectedcandidatepairchange` event is fired at the
 `RTCIceTransport`. From that time forward, the best matching pair of
 candidates will always be available by calling
 `getSelectedCandidatePair()`.

 As ICE negotiation continues, any time a pair of candidates is discovered that is
 better than the currently-selected pair, the new pair is selected, replacing the
 previous pairing, and the `selectedcandidatepairchange` event is fired again.

**Note:** It's possible for one of the configurations in the selected candidate pair to remain unchanged when a new pairing is chosen.

Examples
--------

See `RTCIceTransport.onselectedcandidatepairchange` for example code.

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcicetransport-getselectedcandidatepair |

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
RTCIceTransport: getLocalCandidates() method
============================================

 The **`RTCIceTransport`** method
 **`getLocalCandidates()`** returns an array of
 `RTCIceCandidate` objects, one for each of the candidates that have been
 gathered by the local device during the current ICE agent
 session.

 The local candidates are placed in this list by the ICE agent prior to being delivered
 to the local client's code in an `icecandidate` event so that the client can
 forward the candidates to the remote peer.

Syntax
------


```js
getLocalCandidates()
```

### Parameters

None.

### Return value

 A JavaScript `Array` containing one `RTCIceCandidate` object
 for each candidate that has been identified so far during the ICE candidate gathering
 session.

 You can't correlate these local candidates with matching remote candidates. To find the
 best match found so far, call `RTCIceTransport.getSelectedCandidatePair()`.

Examples
--------

 This simple example gets the local candidate list from the
 `RTCIceTransport` for the first `RTCRtpSender` on the
 `RTCPeerConnection`, then outputs to the console all of the candidates in
 the list.


```js
const localCandidates = pc
  .getSenders()[0]
  .transport.transport.getLocalCandidates();

localCandidates.forEach((candidate, index) => {
  console.log(`Candidate ${index}: ${candidate.candidate}`);
});
```

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcicetransport-getlocalcandidates |

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
ElementInternals: validity property
===================================

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 **`validity`** read-only property of the `ElementInternals` interface returns a `ValidityState` object which represents the different validity states the element can be in, with respect to constraint validation.

Value
-----

A `ValidityState` object.

### Exceptions

`NotSupportedError` `DOMException`

Thrown if the element does not have its `formAssociated` property set to `true`.

Examples
--------

The following example shows a custom checkbox component with `formAssociated` set to `true`, the value of `validity.valid` is logged to the console.


```js
class CustomCheckbox extends HTMLElement {
  static formAssociated = true;

  constructor() {
    super();
    this.internals_ = this.attachInternals();
  }

  // …
}

window.customElements.define("custom-checkbox", CustomCheckbox);

let element = document.getElementById("custom-checkbox");
console.log(element.internals_.validity.valid);
```

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

| Specification |
| --- |
| HTML Standard # dom-elementinternals-validity |

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
ElementInternals: ariaColCount property
=======================================

The **`ariaColCount`** property of the `ElementInternals` interface reflects the value of the `aria-colcount` attribute, which defines the number of columns in a table, grid, or treegrid.

**Note:** Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the Accessibility Object Model explainer.

Value
-----

A string.

Examples
--------

In this example the `aria-colcount` attribute is set to "3".


```js
this.internals_.ariaColCount = "3";
```

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

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # dom-ariamixin-ariacolcount |

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

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

* ARIA: table role
ElementInternals: ariaMultiSelectable property
==============================================

The **`ariaMultiSelectable`** property of the `ElementInternals` interface reflects the value of the `aria-multiselectable` attribute, which indicates that the user may select more than one item from the current selectable descendants.

**Note:** Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the Accessibility Object Model explainer.

Value
-----

A string with one of the following values:

`"true"`

More than one item may be selected at a time.

`"false"`

Only one item may be selected.

Examples
--------

In this example the value of `ariaMultiSelectable` is set to "true".


```js
this.internals_.ariaMultiSelectable = "true";
```

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

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # dom-ariamixin-ariamultiselectable |

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

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

See also
--------

* ARIA: listbox role
ElementInternals: ariaLive property
===================================

The **`ariaLive`** property of the `ElementInternals` interface reflects the value of the `aria-live` attribute, which indicates that an element will be updated, and describes the types of updates the user agents, assistive technologies, and user can expect from the live region.

**Note:** Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the Accessibility Object Model explainer.

Value
-----

A string with one of the following values:

`"assertive"`

Indicates that updates to the region have the highest priority and should be presented the user immediately.

`"off"`

Indicates that updates to the region should not be presented to the user unless the user is currently focused on that region.

`"polite"`

Indicates that updates to the region should be presented at the next graceful opportunity, such as at the end of speaking the current sentence or when the user pauses typing.

Examples
--------

In this example the value of `ariaLive` is set to "assertive".


```js
this.internals_.ariaLive = "assertive";
```

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

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # dom-ariamixin-arialive |

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
ElementInternals: ariaSetSize property
======================================

The **`ariaSetSize`** property of the `ElementInternals` interface reflects the value of the `aria-setsize` attribute, which defines the number of items in the current set of listitems or treeitems.

**Note:** Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the Accessibility Object Model explainer.

Value
-----

A string containing an integer.

Examples
--------

In this example the value of `ariaSetSize` is set to "4".


```js
this.internals_.ariaSetSize = "4";
```

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

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # dom-ariamixin-ariasetsize |

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

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

See also
--------

* ARIA: tab role
ElementInternals: ariaAutoComplete property
===========================================

The **`ariaAutoComplete`** property of the `ElementInternals` interface reflects the value of the `aria-autocomplete` attribute, which indicates whether inputting text could trigger display of one or more predictions of the user's intended value for a combobox, searchbox, or textbox and specifies how predictions would be presented if they were made.

**Note:** Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the Accessibility Object Model explainer.

Value
-----

A string with one of the following values:

`"inline"`

When a user is providing input, text suggesting one way to complete the provided input may be dynamically inserted after the caret.

`"list"`

When a user is providing input, an element containing a collection of values that could complete the provided input may be displayed.

`"both"`

When a user is providing input, an element containing a collection of values that could complete the provided input may be displayed. If displayed, one value in the collection is automatically selected, and the text needed to complete the automatically selected value appears after the caret in the input.

`"none"`

When a user is providing input, there is no display of an automatic suggestion that attempts to predict how the user intends to complete the input.

Examples
--------

In this example the value of `ariaAutoComplete` is set to "inline".


```js
this.internals_.ariaAutoComplete = "inline";
```

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

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # dom-ariamixin-ariaautocomplete |

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
ElementInternals: ariaPlaceholder property
==========================================

The **`ariaPlaceholder`** property of the `ElementInternals` interface reflects the value of the `aria-placeholder` attribute, which defines a short hint intended to aid the user with data entry when the control has no value.

**Note:** Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the Accessibility Object Model explainer.

Value
-----

A string.

Examples
--------

In this example the value of `ariaPlaceholder` is set to "12345".


```js
this.internals_.ariaPlaceholder = "12345";
```

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

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # dom-ariamixin-ariaplaceholder |

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

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

See also
--------

* ARIA: textbox role
ElementInternals: ariaLabel property
====================================

}
The **`ariaLabel`** property of the `ElementInternals` interface reflects the value of the `aria-label` attribute, which defines a string value that labels the current Element.

**Note:** Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the Accessibility Object Model explainer.

Value
-----

A string.

Examples
--------

In this example the value of `ariaLabel` is set to "close".


```js
this.internals_.ariaLabel = "close";
```

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

| Specification |
| --- |
| Accessible Rich Internet Applications (WAI-ARIA) # dom-ariamixin-arialabel |

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
ElementInternals: 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 **`checkValidity()`** method of the `ElementInternals` interface checks if the element meets any constraint validation rules applied to it.

If `checkValidity` returns `false` then a cancelable invalid event is fired on the element.

Syntax
------


```js
checkValidity()
```

### Parameters

None.

### Return value

A boolean value, `true` if the element meets all validation constraints.

### Exceptions

`NotSupportedError` `DOMException`

Thrown if the element does not have its `formAssociated` property set to `true`.

Examples
--------

In the following example `ElementInternals.setValidity()` is used to indicate that the element does not meet validation rules. Calling `checkValidity()` returns `false`. After calling `setValidity` again, this time indicating that all rules are marked false, `checkValidity()` returns `true`.


```js
let element = document.getElementById("join-checkbox");
element.internals_.setValidity({ valueMissing: true }, "my message");
console.log(element.internals_.checkValidity()); // false
element.internals_.setValidity({});
console.log(element.internals_.checkValidity()); // true
```

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

| Specification |
| --- |
| HTML Standard # dom-elementinternals-checkvalidity |

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

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