Element: compositionend event - Web APIs

Element: compositionend event
=============================

The **`compositionend`** event is fired when a text composition system such as an input method editor completes or cancels the current composition session.

For example, this event could be fired after a user finishes entering a Chinese character using a Pinyin IME.

Syntax
------

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

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

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

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

A `CompositionEvent`. Inherits from `UIEvent` and `Event`.

Event

UIEvent

CompositionEventEvent properties
----------------

*This interface also inherits properties of its parent, `UIEvent`, and its ancestor — `Event`.*

`CompositionEvent.data` Read only

Returns the characters generated by the input method that raised the event; its varies depending on the type of event that generated the `CompositionEvent` object.

`CompositionEvent.locale` Read only
Deprecated

Returns the locale of current input method (for example, the keyboard layout locale if the composition is associated with IME).

Examples
--------

```js
const inputElement = document.querySelector('input[type="text"]');

inputElement.addEventListener("compositionend", (event) => {
  console.log(`generated characters were: ${event.data}`);
});
```

### Live example

#### HTML

```html
<div class="control">
  <label for="example">
    First select textbox, then to open IME:
    <ul>
      <li>on macOS type <kbd>option</kbd> + <kbd>`</kbd></li>
      <li>on Windows type <kbd>windows</kbd> + <kbd>.</kbd></li>
    </ul>
  </label>
  <input type="text" id="example" name="example" />
</div>

<div class="event-log">
  <label for="eventLog">Event log:</label>
  <textarea
 readonly
 class="event-log-contents"
 rows="8"
 cols="25"
 id="eventLog"></textarea>
  <button class="clear-log">Clear</button>
</div>
```

```
body {
  padding: 0.2rem;
  display: grid;
  grid-template-areas: "control log";
}

.control {
  grid-area: control;
}

.event-log {
  grid-area: log;
}

.event-log-contents {
  resize: none;
}

label,
button {
  display: block;
}

input[type="text"] {
  margin: 0.5rem 0;
}

kbd {
  border-radius: 3px;
  padding: 1px 2px 0;
  border: 1px solid black;
}
```

#### JavaScript

```js
const inputElement = document.querySelector('input[type="text"]');
const log = document.querySelector(".event-log-contents");
const clearLog = document.querySelector(".clear-log");

clearLog.addEventListener("click", () => {
  log.textContent = "";
});

function handleEvent(event) {
  log.textContent += `${event.type}: ${event.data}\n`;
}

inputElement.addEventListener("compositionstart", handleEvent);
inputElement.addEventListener("compositionupdate", handleEvent);
inputElement.addEventListener("compositionend", handleEvent);
```

#### Result

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

| Specification |
| --- |
| UI Events # event-type-compositionend |

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

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

See also
--------

* Related events: `compositionstart`, `compositionupdate`.


Element: replaceWith() method - Web APIs

Element: replaceWith() method
=============================

 The **`Element.replaceWith()`** method replaces this
 `Element` in the children list of its parent with a set of
 `Node` or string objects. String
 objects are inserted as equivalent `Text` nodes.

Syntax
------

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

### Parameters

`param1`, …, `paramN`

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

### Return value

None (`undefined`).

### Exceptions

`HierarchyRequestError` `DOMException`

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

Examples
--------

### Using `replaceWith()`

```js
const div = document.createElement("div");
const p = document.createElement("p");
div.appendChild(p);
const span = document.createElement("span");

p.replaceWith(span);

console.log(div.outerHTML);
// "<div><span></span></div>"
```

### `replaceWith()` is unscopable

 The `replaceWith()` method is not scoped into the `with`
 statement. See `Symbol.unscopables` for more information.

```js
with (node) {
  replaceWith("foo");
}
// ReferenceError: replaceWith is not defined
```

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-childnode-replacewith① |

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

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

See also
--------

* `Node.replaceChild()`
* `NodeList`


Element: clientWidth property - Web APIs

Element: clientWidth property
=============================

 The **`Element.clientWidth`** property is zero for inline
 elements and elements with no CSS; otherwise, it's the inner width of an element in
 pixels. It includes padding but excludes borders, margins, and vertical scrollbars (if
 present).

 When `clientWidth` is used on the root element (the
 `<html>` element), (or on `<body>` if the document is
 in quirks mode), the viewport's width (excluding any scrollbar) is returned. This is a special case of `clientWidth`.

**Note:** This property will round the value to an integer. If you need
 a fractional value, use `element.getBoundingClientRect()`.

Value
-----

A number.

Examples
--------

![An example element with large padding, border and margin. clientWidth is the inner width of the element including its padding, and excluding its margin, border, and vertical scrollbar.](/en-US/docs/Web/API/Element/clientWidth/dimensions-client.png)

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

| Specification |
| --- |
| CSSOM View Module # dom-element-clientwidth |

### Notes

`clientWidth` was first introduced in the MS IE DHTML object model.

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

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

See also
--------

* `HTMLElement.offsetWidth`
* `Element.scrollWidth`
* Determining the dimensions of elements


Element: ariaSetSize property - Web APIs

Element: ariaSetSize property
=============================

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

Value
-----

A string containing an integer.

Examples
--------

In this example the `aria-setsize` attribute on the element with an ID of `tab-id` is set to "3", to inform a device that there are currently 3 tabs in the group. Using `ariaSetSize` we update the value to "4".

```html
<button
 role="tab"
 aria-selected="true"
 aria-setsize="3"
 aria-controls="tabpanel-id"
 id="tab-id">
  Tab label
</button>
```

```js
let el = document.getElementById("tab-id");
console.log(el.ariaSetSize); // 3
el.ariaSetSize = "4";
console.log(el.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


Element: contextmenu event - Web APIs

Element: contextmenu event
==========================

The **`contextmenu`** event fires when the user attempts to open a context menu. This event is typically triggered by clicking the right mouse button, or by pressing the context menu key.

In the latter case, the context menu is displayed at the bottom left of the focused element, unless the element is a tree, in which case the context menu is displayed at the bottom left of the current row.

Any right-click event that is not disabled (by calling the click event's `preventDefault()` method) will result in a `contextmenu` event being fired at the targeted element.

**Note:** An exception to this in Firefox: if the user holds down the `Shift` key while right-clicking, then the context menu will be shown without a `contextmenu` event being fired.

Syntax
------

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

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

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

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

A `PointerEvent`. Inherits from `MouseEvent`.

Event

UIEvent

MouseEvent

PointerEvent

**Note:** In earlier versions of the specification the event type for this event was a `MouseEvent`, and this is still the type passed in Firefox and Safari.

Event properties
----------------

*This interface inherits properties from `MouseEvent` and `Event`.*

`PointerEvent.altitudeAngle` Read only
Experimental

Represents the angle between a transducer (a pointer or stylus) axis and the X-Y plane of a device screen.

`PointerEvent.azimuthAngle` Read only
Experimental

Represents the angle between the Y-Z plane and the plane containing both the transducer (a pointer or stylus) axis and the Y axis.

`PointerEvent.pointerId` Read only

A unique identifier for the pointer causing the event.

`PointerEvent.width` Read only

The width (magnitude on the X axis), in CSS pixels, of the contact geometry of the pointer.

`PointerEvent.height` Read only

The height (magnitude on the Y axis), in CSS pixels, of the contact geometry of the pointer.

`PointerEvent.pressure` Read only

The normalized pressure of the pointer input in the range `0` to `1`, where `0` and `1` represent the minimum and maximum pressure the hardware is capable of detecting, respectively.

`PointerEvent.tangentialPressure` Read only

The normalized tangential pressure of the pointer input (also known as barrel pressure or cylinder stress) in the range `-1` to `1`, where `0` is the neutral position of the control.

`PointerEvent.tiltX` Read only

The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the Y axis.

`PointerEvent.tiltY` Read only

The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the X axis.

`PointerEvent.twist` Read only

The clockwise rotation of the pointer (e.g. pen stylus) around its major axis in degrees, with a value in the range `0` to `359`.

`PointerEvent.pointerType` Read only

Indicates the device type that caused the event (mouse, pen, touch, etc.).

`PointerEvent.isPrimary` Read only

Indicates if the pointer represents the primary pointer of this pointer type.

Examples
--------

### Canceling the `contextmenu` event

In this example, the default action of the `contextmenu` event is canceled using `preventDefault()` when the `contextmenu` event is fired at the first paragraph. As a result, the first paragraph will do nothing when right-clicked, while the second paragraph will show the standard context menu offered by your browser.

**Note:** In Firefox, if you hold down the `Shift` key while right-clicking, then the context menu is shown without the `contextmenu` event being fired. Therefore, canceling the event does not stop the context menu from being shown.

#### HTML

```html
<p id="noContextMenu">The context menu has been disabled on this paragraph.</p>
<p>But it has not been disabled on this one.</p>
```

#### JavaScript

```js
const noContext = document.getElementById("noContextMenu");

noContext.addEventListener("contextmenu", (e) => {
  e.preventDefault();
});
```

#### Result

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

| Specification |
| --- |
| UI Events # event-type-contextmenu |

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

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

See also
--------

* Introduction to events
* `auxclick`
* `click`
* `dblclick`
* `mousedown`
* `mouseup`
* `pointerdown`
* `pointerup`


Element: transitionrun event - Web APIs

Element: transitionrun event
============================

The **`transitionrun`** event is fired when a CSS transition is first created, i.e. before any `transition-delay` has begun.

This event is not cancelable.

Syntax
------

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

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

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

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

A `TransitionEvent`. Inherits from `Event`.

Event

TransitionEventEvent properties
----------------

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

`TransitionEvent.propertyName` Read only

A string containing the name CSS property associated with the transition.

`TransitionEvent.elapsedTime` Read only

A `float` giving the amount of time the transition has been running, in seconds, when this event fired. This value is not affected by the `transition-delay` property.

`TransitionEvent.pseudoElement` Read only

A string, starting with `::`, containing the name of the pseudo-element the animation runs on. If the transition doesn't run on a pseudo-element but on the element, an empty string: `''`.

Examples
--------

This code adds a listener to the `transitionrun` event:

```js
el.addEventListener("transitionrun", () => {
  console.log(
    "Transition is running but hasn't necessarily started transitioning yet",
  );
});
```

The same, but using the `ontransitionrun` property instead of `addEventListener()`:

```js
el.ontransitionrun = () => {
  console.log(
    "Transition started running, and will start transitioning when the transition delay has expired",
  );
};
```

### Live example

In the following example, we have a simple `<div>` element, styled with a transition that includes a delay:

```html
<div class="transition">Hover over me</div>
<div class="message"></div>
```

```css
.transition {
  width: 100px;
  height: 100px;
  background: rgb(255 0 0 / 100%);
  transition-property: transform, background;
  transition-duration: 2s;
  transition-delay: 1s;
}

.transition:hover {
  transform: rotate(90deg);
  background: rgb(255 0 0 / 0%);
}
```

To this, we'll add some JavaScript to indicate where the `transitionstart` and `transitionrun` events fire.

```js
const el = document.querySelector(".transition");
const message = document.querySelector(".message");

el.addEventListener("transitionrun", () => {
  message.textContent = "transitionrun fired";
});

el.addEventListener("transitionstart", () => {
  message.textContent = "transitionstart fired";
});

el.addEventListener("transitionend", () => {
  message.textContent = "transitionend fired";
});
```

The difference is that:

* `transitionrun` fires when the transition is created (i.e. at the start of any delay).
* `transitionstart` fires when the actual animation has begun (i.e. at the end of any delay).

The `transitionrun` will occur even if the transition is canceled before the delay expires. If there is no transition delay or if transition-delay is negative, both `transitionrun` and `transitionstart` are fired.

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

| Specification |
| --- |
| CSS Transitions # transitionrun |

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

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

See also
--------

* The `TransitionEvent` interface
* CSS properties: `transition`, `transition-delay`, `transition-duration`, `transition-property`, `transition-timing-function`
* Related events: `transitionend`, `transitionstart`, `transitioncancel`


Encoding API Encodings - Web APIs

Encoding API Encodings
======================

 The constructors for the Encoding API interfaces `TextDecoder` and `TextDecoderStream` can be passed an optional `label`, representing the encoding to be used.
 The default is `UTF-8`.

 The following table lists all encoding names and labels that user agents must support, as defined in the Encoding Spec.
 These are generally applicable anywhere character encodings are used.

| Label | Encoding |
| --- | --- |
|
 "`unicode-1-1-utf-8`", "`utf-8`",
 "`utf8`"
  | `'utf-8'` |
|
 "`866`", "`cp866`", "`csibm866`",
 "`ibm866`"
  | ibm866 |
|
 "`csisolatin2`", "`iso-8859-2`",
 "`iso-ir-101`", "`iso8859-2`",
 "`iso88592`", "`iso_8859-2`",
 "`iso_8859-2:1987`", "`l2`", "`latin2`"
  | iso-8859-2 |
|
 "`csisolatin3`", "`iso-8859-3`",
 "`iso-ir-109`", "`iso8859-3`",
 "`iso88593`", "`iso_8859-3`",
 "`iso_8859-3:1988`", "`l3`", "`latin3`"
  | iso-8859-3 |
|
 "`csisolatin4`", "`iso-8859-4`",
 "`iso-ir-110`", "`iso8859-4`",
 "`iso88594`", "`iso_8859-4`",
 "`iso_8859-4:1988`", "`l4`", "`latin4`"
  | iso-8859-4 |
|
 "`csisolatincyrillic`", "`cyrillic`",
 "`iso-8859-5`", "`iso-ir-144`",
 "`iso88595`", "`iso_8859-5`",
 "`iso_8859-5:1988`"
  | iso-8859-5 |
|
 "`arabic`", "`asmo-708`",
 "`csiso88596e`", "`csiso88596i`",
 "`csisolatinarabic`", "`ecma-114`",
 "`iso-8859-6`", "`iso-8859-6-e`",
 "`iso-8859-6-i`", "`iso-ir-127`",
 "`iso8859-6`", "`iso88596`",
 "`iso_8859-6`", "`iso_8859-6:1987`"
  | iso-8859-6 |
|
 "`csisolatingreek`", "`ecma-118`",
 "`elot_928`", "`greek`", "`greek8`",
 "`iso-8859-7`", "`iso-ir-126`",
 "`iso8859-7`", "`iso88597`",
 "`iso_8859-7`", "`iso_8859-7:1987`",
 "`sun_eu_greek`"
  | iso-8859-7 |
|
 "`csiso88598e`", "`csisolatinhebrew`",
 "`hebrew`", "`iso-8859-8`",
 "`iso-8859-8-e`", "`iso-ir-138`",
 "`iso8859-8`", "`iso88598`",
 "`iso_8859-8`", "`iso_8859-8:1988`",
 "`visual`"
  | iso-8859-8 |
|
 "`csiso88598i`", "`iso-8859-8-i`",
 "`logical`"
  | iso-8859-8i |
|
 "`csisolatin6`", "`iso-8859-10`",
 "`iso-ir-157`", "`iso8859-10`",
 "`iso885910`", "`l6`", "`latin6`"
  | iso-8859-10 |
|
 "`iso-8859-13`", "`iso8859-13`",
 "`iso885913`"
  | iso-8859-13 |
|
 "`iso-8859-14`", "`iso8859-14`",
 "`iso885914`"
  | iso-8859-14 |
|
 "`csisolatin9`", "`iso-8859-15`",
 "`iso8859-15`", "`iso885915`", "`l9`",
 "`latin9`"
  | iso-8859-15 |
| "`iso-8859-16`" | iso-8859-16 |
|
 "`cskoi8r`", "`koi`", "`koi8`",
 "`koi8-r`", "`koi8_r`"
  | koi8-r |
| "`koi8-u`" | koi8-u |
|
 "`csmacintosh`", "`mac`",
 "`macintosh`", "`x-mac-roman`"
  | macintosh |
|
 "`dos-874`", "`iso-8859-11`",
 "`iso8859-11`", "`iso885911`",
 "`tis-620`", "`windows-874`"
  | windows-874 |
|
 "`cp1250`", "`windows-1250`",
 "`x-cp1250`"
  | windows-1250 |
|
 "`cp1251`", "`windows-1251`",
 "`x-cp1251`"
  | windows-1251 |
|
 "`ansi_x3.4-1968`", "`ascii`",
 "`cp1252`", "`cp819`", "`csisolatin1`",
 "`ibm819`", "`iso-8859-1`",
 "`iso-ir-100`", "`iso8859-1`",
 "`iso88591`", "`iso_8859-1`",
 "`iso_8859-1:1987`", "`l1`",
 "`latin1`", "`us-ascii`",
 "`windows-1252`", "`x-cp1252`"
  | windows-1252 |
|
 "`cp1253`", "`windows-1253`",
 "`x-cp1253`"
  | windows-1253 |
|
 "`cp1254`", "`csisolatin5`",
 "`iso-8859-9`", "`iso-ir-148`",
 "`iso8859-9`", "`iso88599`",
 "`iso_8859-9`", "`iso_8859-9:1989`",
 "`l5`", "`latin5`", "`windows-1254`",
 "`x-cp1254`"
  | windows-1254 |
|
 "`cp1255`", "`windows-1255`",
 "`x-cp1255`"
  | windows-1255 |
|
 "`cp1256`", "`windows-1256`",
 "`x-cp1256`"
  | windows-1256 |
|
 "`cp1257`", "`windows-1257`",
 "`x-cp1257`"
  | windows-1257 |
|
 "`cp1258`", "`windows-1258`",
 "`x-cp1258`"
  | windows-1258 |
| "`x-mac-cyrillic`", "`x-mac-ukrainian`" | x-mac-cyrillic |
|
 "`chinese`", "`csgb2312`",
 "`csiso58gb231280`", "`gb2312`",
 "`gb_2312`", "`gb_2312-80`", "`gbk`",
 "`iso-ir-58`", "`x-gbk`"
  | gbk |
| "`gb18030`" | gb18030 |
| "`hz-gb-2312`" | hz-gb-2312 |
|
 "`big5`", "`big5-hkscs`", "`cn-big5`",
 "`csbig5`", "`x-x-big5`"
  | big5 |
|
 "`cseucpkdfmtjapanese`", "`euc-jp`",
 "`x-euc-jp`"
  | euc-jp |
| "`csiso2022jp`", "`iso-2022-jp`" | iso-2022-jp |
|
 "`csshiftjis`", "`ms_kanji`",
 "`shift-jis`", "`shift_jis`", "`sjis`",
 "`windows-31j`", "`x-sjis`"
  | shift-jis |
|
 "`cseuckr`", "`csksc56011987`",
 "`euc-kr`", "`iso-ir-149`", "`korean`",
 "`ks_c_5601-1987`", "`ks_c_5601-1989`",
 "`ksc5601`", "`ksc_5601`",
 "`windows-949`"
  | euc-kr |
| "`csiso2022kr`", "`iso-2022-kr`" | iso-2022-kr |
| "`utf-16be`" | utf-16be |
| "`utf-16`", "`utf-16le`" | utf-16le |
| "`x-user-defined`" | `'x-user-defined'` |
| "`iso-2022-cn`", "`iso-2022-cn-ext`" | `'replacement'` |


SpeechSynthesisUtterance: boundary event - Web APIs

SpeechSynthesisUtterance: boundary event
========================================

The **`boundary`** event of the Web Speech API is fired when the spoken utterance reaches a word or sentence boundary.

Syntax
------

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

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

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

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

A `SpeechSynthesisEvent`. Inherits from `Event`.

Event

SpeechSynthesisEventEvent properties
----------------

*In addition to the properties listed below, properties from the parent interface, `Event`, are available.*

`charIndex` Read only

Returns the index position of the character in the `SpeechSynthesisUtterance.text` that was being spoken when the event was triggered.

`elapsedTime` Read only

Returns the elapsed time in seconds after the `SpeechSynthesisUtterance.text` started being spoken that the event was triggered at.

`name` Read only

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.

`utterance` Read only

Returns the `SpeechSynthesisUtterance` instance that the event was triggered on.

Examples
--------

You can use the `boundary` event in an `addEventListener` method:

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

Or use the `onboundary` event handler property:

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

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

| Specification |
| --- |
| Web Speech API # eventdef-speechsynthesisutterance-boundary |
| Web Speech API # dom-speechsynthesisutterance-onboundary |

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

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

See also
--------

* Web Speech API


SpeechSynthesisUtterance: lang property - Web APIs

SpeechSynthesisUtterance: lang property
=======================================

The **`lang`** property of the `SpeechSynthesisUtterance` interface gets and sets the language of the utterance.

If unset, the app's (i.e. the `<html>` `lang` value) lang will be used, or the user-agent default if that is unset too.

Value
-----

A string representing a BCP 47 language tag.

Examples
--------

```js
const synth = window.speechSynthesis;

const inputForm = document.querySelector("form");
const inputTxt = document.querySelector("input");
const voiceSelect = document.querySelector("select");

const voices = synth.getVoices();

// ...

inputForm.onsubmit = (event) => {
  event.preventDefault();

  const utterThis = new SpeechSynthesisUtterance(inputTxt.value);
  const selectedOption =
    voiceSelect.selectedOptions[0].getAttribute("data-name");
  for (let i = 0; i < voices.length; i++) {
    if (voices[i].name === selectedOption) {
      utterThis.voice = voices[i];
    }
  }
  utterThis.lang = "en-US";
  synth.speak(utterThis);
  inputTxt.blur();
};
```

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

| Specification |
| --- |
| Web Speech API # dom-speechsynthesisutterance-lang |

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

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

See also
--------

* Web Speech API


SpeechSynthesisUtterance: mark event - Web APIs

SpeechSynthesisUtterance: mark event
====================================

The **`mark`** event of the Web Speech API `SpeechSynthesisUtterance` object is fired when the spoken utterance reaches a named SSML "mark" tag.

Syntax
------

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

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

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

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

A `SpeechSynthesisEvent`. Inherits from `Event`.

Event

SpeechSynthesisEventEvent properties
----------------

*In addition to the properties listed below, properties from the parent interface, `Event`, are available.*

`charIndex` Read only

Returns the index position of the character in the `SpeechSynthesisUtterance.text` that was being spoken when the event was triggered.

`elapsedTime` Read only

Returns the elapsed time in seconds after the `SpeechSynthesisUtterance.text` started being spoken that the event was triggered at.

`name` Read only

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.

`utterance` Read only

Returns the `SpeechSynthesisUtterance` instance that the event was triggered on.

Examples
--------

You can use the `mark` event in an `addEventListener` method:

```js
utterThis.addEventListener("mark", (event) => {
  console.log(`A mark was reached: ${event.name}`);
});
```

Or use the `onmark` event handler property:

```js
utterThis.onmark = (event) => {
  console.log(`A mark was reached: ${event.name}`);
};
```

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

| Specification |
| --- |
| Web Speech API # eventdef-speechsynthesisutterance-mark |
| Web Speech API # dom-speechsynthesisutterance-onmark |

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

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

See also
--------

* Web Speech API


SpeechSynthesisUtterance: volume property - Web APIs

SpeechSynthesisUtterance: volume property
=========================================

The **`volume`** property of the `SpeechSynthesisUtterance` interface gets and sets the volume that the utterance will be spoken at.

If not set, the default value 1 will be used.

Value
-----

A float that represents the volume value, between 0 (lowest) and 1 (highest.)

If SSML is used, this value will be overridden by prosody tags in the markup.

Examples
--------

```js
const synth = window.speechSynthesis;

const inputForm = document.querySelector("form");
const inputTxt = document.querySelector("input");
const voiceSelect = document.querySelector("select");

const voices = synth.getVoices();

// ...

inputForm.onsubmit = (event) => {
  event.preventDefault();

  const utterThis = new SpeechSynthesisUtterance(inputTxt.value);
  const selectedOption =
    voiceSelect.selectedOptions[0].getAttribute("data-name");
  for (let i = 0; i < voices.length; i++) {
    if (voices[i].name === selectedOption) {
      utterThis.voice = voices[i];
    }
  }
  utterThis.volume = 0.5;
  synth.speak(utterThis);
  inputTxt.blur();
};
```

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

| Specification |
| --- |
| Web Speech API # dom-speechsynthesisutterance-volume |

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

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

See also
--------

* Web Speech API


SpeechSynthesisUtterance: pause event - Web APIs

SpeechSynthesisUtterance: pause event
=====================================

The **`pause`** event of the Web Speech API `SpeechSynthesisUtterance` object is fired when the utterance is paused part way through.

Syntax
------

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

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

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

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

A `SpeechSynthesisEvent`. Inherits from `Event`.

Event

SpeechSynthesisEventEvent properties
----------------

*In addition to the properties listed below, properties from the parent interface, `Event`, are available.*

`charIndex` Read only

Returns the index position of the character in the `SpeechSynthesisUtterance.text` that was being spoken when the event was triggered.

`elapsedTime` Read only

Returns the elapsed time in seconds after the `SpeechSynthesisUtterance.text` started being spoken that the event was triggered at.

`name` Read only

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.

`utterance` Read only

Returns the `SpeechSynthesisUtterance` instance that the event was triggered on.

Examples
--------

You can use the `pause` event in an `addEventListener` method:

```js
utterThis.addEventListener("pause", (event) => {
  console.log(`Speech paused after ${event.elapsedTime} seconds.`);
});
```

Or use the `onpause` event handler property:

```js
utterThis.onpause = (event) => {
  console.log(`Speech paused after ${event.elapsedTime} seconds.`);
};
```

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

| Specification |
| --- |
| Web Speech API # eventdef-speechsynthesisutterance-pause |
| Web Speech API # dom-speechsynthesisutterance-onpause |

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

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

See also
--------

* Web Speech API


SpeechSynthesisUtterance: start event - Web APIs

SpeechSynthesisUtterance: start event
=====================================

The **`start`** event of the Web Speech API `SpeechSynthesisUtterance` object is fired when the utterance has begun to be spoken.

Syntax
------

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

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

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

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

A `SpeechSynthesisEvent`. Inherits from `Event`.

Event

SpeechSynthesisEventEvent properties
----------------

*In addition to the properties listed below, properties from the parent interface, `Event`, are available.*

`charIndex` Read only

Returns the index position of the character in the `SpeechSynthesisUtterance.text` that was being spoken when the event was triggered.

`elapsedTime` Read only

Returns the elapsed time in seconds after the `SpeechSynthesisUtterance.text` started being spoken that the event was triggered at.

`name` Read only

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.

`utterance` Read only

Returns the `SpeechSynthesisUtterance` instance that the event was triggered on.

Examples
--------

You can use the `start` event in an `addEventListener` method:

```js
utterThis.addEventListener("start", (event) => {
  console.log(`We have started uttering this speech: ${event.utterance.text}`);
});
```

Or use the `onstart` event handler property:

```js
utterThis.onstart = (event) => {
  console.log(`We have started uttering this speech: ${event.utterance.text}`);
};
```

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

| Specification |
| --- |
| Web Speech API # eventdef-speechsynthesisutterance-start |
| Web Speech API # dom-speechsynthesisutterance-onstart |

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

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

See also
--------

* Web Speech API


SpeechSynthesisUtterance: SpeechSynthesisUtterance() constructor - Web APIs

SpeechSynthesisUtterance: SpeechSynthesisUtterance() constructor
================================================================

The `SpeechSynthesisUtterance()` constructor of the `SpeechSynthesisUtterance` interface returns a new `SpeechSynthesisUtterance` object instance.

Syntax
------

```js
new SpeechSynthesisUtterance(text)
```

### Parameters

`text`

A string containing the text that will be synthesized when the utterance is spoken.

Examples
--------

The following snippet is excerpted from our Speech synthesizer demo.

```js
const synth = window.speechSynthesis;

const inputForm = document.querySelector("form");
const inputTxt = document.querySelector("input");
const voiceSelect = document.querySelector("select");

const voices = synth.getVoices();

// ...

inputForm.onsubmit = (event) => {
  event.preventDefault();

  const utterThis = new SpeechSynthesisUtterance(inputTxt.value);
  const selectedOption =
    voiceSelect.selectedOptions[0].getAttribute("data-name");
  for (let i = 0; i < voices.length; i++) {
    if (voices[i].name === selectedOption) {
      utterThis.voice = voices[i];
    }
  }
  synth.speak(utterThis);
  inputTxt.blur();
};
```

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

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

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

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

See also
--------

* Web Speech API


SpeechSynthesisUtterance: rate property - Web APIs

SpeechSynthesisUtterance: rate property
=======================================

The **`rate`** property of the `SpeechSynthesisUtterance` interface gets and sets the speed at which the utterance will be spoken at.

If unset, a default value of 1 will be used.

Value
-----

 A float representing the rate value.
 It can range between 0.1 (lowest) and 10 (highest), with 1 being the default rate for the current platform or voice, which should correspond to a normal speaking rate.
 Other values act as a percentage relative to this, so for example 2 is twice as fast, 0.5 is half as fast, etc.

 Some speech synthesis engines or voices may constrain the minimum and maximum rates further.
 If SSML is used, this value will be overridden by prosody tags in the markup.

Examples
--------

### Adjusting playback rate

In this example we can adjust the playback rate using the slider, then play the utterance with the "Play" button.

#### HTML

```html
<p id="text">It was a dark and stormy night.</p>

<div id="rate-control">
  <label for="rate">Rate:</label>
  <input type="range" min="0.5" max="2" value="1" step="0.1" id="rate" />
</div>

<button id="play">Play</button>
```

#### CSS

```css
body {
  font-family: sans-serif;
}

#rate-control {
  display: flex;
  align-items: center;
  gap: 1rem;
  margin: 1rem 0;
}
```

#### JavaScript

```js
const synth = window.speechSynthesis;

const text = document.querySelector("#text");
const play = document.querySelector("#play");
const rate = document.querySelector("#rate");

function speak() {
  if (synth.speaking) {
    synth.cancel();
  }
  const utterThis = new SpeechSynthesisUtterance(text.textContent);
  utterThis.addEventListener("error", () => {
    console.error("SpeechSynthesisUtterance error");
  });
  utterThis.rate = rate.value;
  synth.speak(utterThis);
}

play.addEventListener("click", speak);
```

#### Output

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

| Specification |
| --- |
| Web Speech API # dom-speechsynthesisutterance-rate |

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

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

See also
--------

* Web Speech API


SpeechSynthesisUtterance: voice property - Web APIs

SpeechSynthesisUtterance: voice property
========================================

The **`voice`** property of the `SpeechSynthesisUtterance` interface gets and sets the voice that will be used to speak the utterance.

 This should be set to one of the `SpeechSynthesisVoice` objects returned by `SpeechSynthesis.getVoices()`.
 If not set by the time the utterance is spoken, the voice used will be the most suitable default voice available for the utterance's `lang` setting.

Value
-----

A `SpeechSynthesisVoice` object.

Examples
--------

```js
const synth = window.speechSynthesis;

const inputForm = document.querySelector("form");
const inputTxt = document.querySelector("input");
const voiceSelect = document.querySelector("select");

const voices = synth.getVoices();

// ...

inputForm.onsubmit = (event) => {
  event.preventDefault();

  const utterThis = new SpeechSynthesisUtterance(inputTxt.value);
  const selectedOption =
    voiceSelect.selectedOptions[0].getAttribute("data-name");
  for (let i = 0; i < voices.length; i++) {
    if (voices[i].name === selectedOption) {
      utterThis.voice = voices[i];
    }
  }
  synth.speak(utterThis);
  inputTxt.blur();
};
```

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

| Specification |
| --- |
| Web Speech API # dom-speechsynthesisutterance-voice |

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

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

See also
--------

* Web Speech API


SpeechSynthesisUtterance: end event - Web APIs

SpeechSynthesisUtterance: end event
===================================

The **`end`** event of the Web Speech API `SpeechSynthesisUtterance` object is fired when the utterance has finished being spoken.

Syntax
------

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

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

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

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

A `SpeechSynthesisEvent`. Inherits from `Event`.

Event

SpeechSynthesisEventEvent properties
----------------

*In addition to the properties listed below, properties from the parent interface, `Event`, are available.*

`charIndex` Read only

Returns the index position of the character in the `SpeechSynthesisUtterance.text` that was being spoken when the event was triggered.

`elapsedTime` Read only

Returns the elapsed time in seconds after the `SpeechSynthesisUtterance.text` started being spoken that the event was triggered at.

`name` Read only

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.

`utterance` Read only

Returns the `SpeechSynthesisUtterance` instance that the event was triggered on.

Examples
--------

You can use the `end` event in an `addEventListener` method:

```js
utterThis.addEventListener("end", (event) => {
  console.log(
    `Utterance has finished being spoken after ${event.elapsedTime} seconds.`,
  );
});
```

Or use the `onend` event handler property:

```js
utterThis.onend = (event) => {
  console.log(
    `Utterance has finished being spoken after ${event.elapsedTime} seconds.`,
  );
};
```

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

| Specification |
| --- |
| Web Speech API # eventdef-speechsynthesisutterance-end |
| Web Speech API # dom-speechsynthesisutterance-onend |

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

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

See also
--------

* Web Speech API


SpeechSynthesisUtterance: error event - Web APIs

SpeechSynthesisUtterance: error event
=====================================

The **`error`** event of the Web Speech API `SpeechSynthesisUtterance` object is fired when an error occurs that prevents the utterance from being successfully spoken.

Syntax
------

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

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

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

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

A `SpeechSynthesisErrorEvent`. Inherits from `SpeechSynthesisEvent` and `Event`.

Event

SpeechSynthesisEvent

SpeechSynthesisErrorEventEvent properties
----------------

*In addition to the properties listed below, properties from the parent interface, `Event`, are available.*

`charIndex` Read only

Returns the index position of the character in the `SpeechSynthesisUtterance.text` that was being spoken when the event was triggered.

`elapsedTime` Read only

Returns the elapsed time in seconds after the `SpeechSynthesisUtterance.text` started being spoken that the event was triggered at.

`error` Read only

Returns an error code indicating what has gone wrong with a speech synthesis attempt.

`name` Read only

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.

`utterance` Read only

Returns the `SpeechSynthesisUtterance` instance that the event was triggered on.

Examples
--------

You can use the `error` event in an `addEventListener` method:

```js
utterThis.addEventListener("error", (event) => {
  console.log(
    `An error has occurred with the speech synthesis: ${event.error}`,
  );
});
```

Or use the `onerror` event handler property:

```js
utterThis.onerror = (event) => {
  console.log(
    `An error has occurred with the speech synthesis: ${event.error}`,
  );
};
```

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

| Specification |
| --- |
| Web Speech API # eventdef-speechsynthesisutterance-error |
| Web Speech API # dom-speechsynthesisutterance-onerror |

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

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

See also
--------

* Web Speech API


SpeechSynthesisUtterance: pitch property - Web APIs

SpeechSynthesisUtterance: pitch property
========================================

The **`pitch`** property of the `SpeechSynthesisUtterance` interface gets and sets the pitch at which the utterance will be spoken at.

If unset, a default value of 1 will be used.

Value
-----

 A float representing the pitch value.
 It can range between 0 (lowest) and 2 (highest), with 1 being the default pitch for the current platform or voice. Some speech synthesis engines or voices may constrain the minimum and maximum rates further.
 If SSML is used, this value will be overridden by prosody tags in the markup.

Examples
--------

```js
const synth = window.speechSynthesis;

const inputForm = document.querySelector("form");
const inputTxt = document.querySelector("input");
const voiceSelect = document.querySelector("select");

const voices = synth.getVoices();

// ...

inputForm.onsubmit = (event) => {
  event.preventDefault();

  const utterThis = new SpeechSynthesisUtterance(inputTxt.value);
  const selectedOption =
    voiceSelect.selectedOptions[0].getAttribute("data-name");
  for (let i = 0; i < voices.length; i++) {
    if (voices[i].name === selectedOption) {
      utterThis.voice = voices[i];
    }
  }
  utterThis.pitch = 1.5;
  synth.speak(utterThis);
  inputTxt.blur();
};
```

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

| Specification |
| --- |
| Web Speech API # dom-speechsynthesisutterance-pitch |

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

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

See also
--------

* Web Speech API


SpeechSynthesisUtterance: text property - Web APIs

SpeechSynthesisUtterance: text property
=======================================

 The **`text`** property of the
 `SpeechSynthesisUtterance` interface gets and sets the text that will be synthesized when the utterance is spoken.

 The text may be provided as plain text, or a well-formed SSML document.
 The SSML tags will be stripped away by devices that don't support SSML.

Value
-----

 A string representing the text to the synthesized.
 The maximum length of the text that can be spoken in each utterance is 32,767 characters.

Examples
--------

```js
const synth = window.speechSynthesis;

const inputForm = document.querySelector("form");
const inputTxt = document.querySelector("input");
const voiceSelect = document.querySelector("select");

const voices = synth.getVoices();

// ...

inputForm.onsubmit = (event) => {
  event.preventDefault();

  const utterThis = new SpeechSynthesisUtterance(inputTxt.value);
  const selectedOption =
    voiceSelect.selectedOptions[0].getAttribute("data-name");
  for (let i = 0; i < voices.length; i++) {
    if (voices[i].name === selectedOption) {
      utterThis.voice = voices[i];
    }
  }
  console.log(utterThis.text);
  synth.speak(utterThis);
  inputTxt.blur();
};
```

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

| Specification |
| --- |
| Web Speech API # dom-speechsynthesisutterance-text |

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

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

See also
--------

* Web Speech API


SpeechSynthesisUtterance: resume event - Web APIs

SpeechSynthesisUtterance: resume event
======================================

The **`resume`** event of the Web Speech API `SpeechSynthesisUtterance` object is fired when a paused utterance is resumed.

Syntax
------

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

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

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

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

A `SpeechSynthesisEvent`. Inherits from `Event`.

Event

SpeechSynthesisEventEvent properties
----------------

*In addition to the properties listed below, properties from the parent interface, `Event`, are available.*

`charIndex` Read only

Returns the index position of the character in the `SpeechSynthesisUtterance.text` that was being spoken when the event was triggered.

`elapsedTime` Read only

Returns the elapsed time in seconds after the `SpeechSynthesisUtterance.text` started being spoken that the event was triggered at.

`name` Read only

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.

`utterance` Read only

Returns the `SpeechSynthesisUtterance` instance that the event was triggered on.

Examples
--------

You can use the `resume` event in an `addEventListener` method:

```js
utterThis.addEventListener("resume", (event) => {
  console.log(`Speech resumed after ${event.elapsedTime} seconds.`);
});
```

Or use the `onresume` event handler property:

```js
utterThis.onresume = (event) => {
  console.log(`Speech resumed after ${event.elapsedTime} seconds.`);
};
```

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

| Specification |
| --- |
| Web Speech API # eventdef-speechsynthesisutterance-resume |
| Web Speech API # dom-speechsynthesisutterance-onresume |

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

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

See also
--------

* Web Speech API


CryptoKey: algorithm property - Web APIs

CryptoKey: algorithm property
=============================

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

The read-only **`algorithm`** property of the `CryptoKey` interface returns an object describing the algorithm for which this key can be used, and any associated extra parameters.

The object returned depends of the algorithm used to generate the key.

Value
-----

An object matching:

* `AesKeyGenParams` if the algorithm is any of the AES variants.
* `RsaHashedKeyGenParams` if the algorithm is any of the RSA variants.
* `EcKeyGenParams` if the algorithm is any of the EC variants.
* `HmacKeyGenParams` if the algorithm is HMAC.
Examples
--------

```js
const rawKey = window.crypto.getRandomValues(new Uint8Array(16));

// Import an AES secret key from an ArrayBuffer containing the raw bytes.
// Takes an ArrayBuffer string containing the bytes, and returns a Promise
// that will resolve to a CryptoKey representing the secret key.
function importSecretKey(rawKey) {
  return window.crypto.subtle.importKey("raw", rawKey, "AES-GCM", true, [
    "encrypt",
    "decrypt",
  ]);
}

const key = importSecretKey(rawKey);
console.log(`This key is to be used with the ${key.algorithm} algorithm.`);
```

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

| Specification |
| --- |
| Web Cryptography API # dom-cryptokey-algorithm |

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

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


CryptoKey: usages property - Web APIs

CryptoKey: usages property
==========================

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

The read-only **`usages`** property of the `CryptoKey` interface indicates what can be done with the key.

Value
-----

An `Array` of strings from the following list:

* `"encrypt"`: The key may be used to `encrypt` messages.
* `"decrypt"`: The key may be used to `decrypt` messages.
* `"sign"`: The key may be used to `sign` messages.
* `"verify"`: The key may be used to `verify` signatures.
* `"deriveKey"`: The key may be used in `deriving a new key`.
* `"deriveBits"`: The key may be used in `deriving bits`.
* `"wrapKey"`: The key may be used to `wrap a key`.
* `"unwrapKey"`: The key may be used to `unwrap a key`.
Examples
--------

```js
const rawKey = window.crypto.getRandomValues(new Uint8Array(16));

// Import an AES secret key from an ArrayBuffer containing the raw bytes.
// Takes an ArrayBuffer string containing the bytes, and returns a Promise
// that will resolve to a CryptoKey representing the secret key.
function importSecretKey(rawKey) {
  return window.crypto.subtle.importKey("raw", rawKey, "AES-GCM", true, [
    "encrypt",
    "decrypt",
  ]);
}

const key = importSecretKey(rawKey);
console.log(
  `The following usages are reported for this key: ${key.usages.toString()}`,
);
```

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

| Specification |
| --- |
| Web Cryptography API # dom-cryptokey-usages |

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

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


CryptoKey: extractable property - Web APIs

CryptoKey: extractable property
===============================

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

The read-only **`extractable`** property of the `CryptoKey` interface indicates whether or not the key may be extracted using `SubtleCrypto.exportKey()` or `SubtleCrypto.wrapKey()`.

If the key cannot be exported, `exportKey()` or `wrapKey()` will throw an exception if used to extract it.

Value
-----

A boolean value that is `true` if the key can be exported and `false` if not.

Examples
--------

In this example, the *Export* button is disabled, and no listener added, if the key cannot be exported.

```js
// Export the given key and write it into the "exported-key" space.
async function exportCryptoKey(key) {
  const exported = await window.crypto.subtle.exportKey("raw", key);
  const exportedKeyBuffer = new Uint8Array(exported);

  const exportKeyOutput = document.querySelector(".exported-key");
  exportKeyOutput.textContent = `[${exportedKeyBuffer}]`;
}

// Enable or disable the exportButton if the key is extractable or not
function setExportButton(key) {
  const exportButton = document.querySelector(".raw");

  // Disable the button if the key is not extractable
  exportButton.disabled = !key.extractable;
  if (key.extractable) {
    // Add an event listener to extract the key
    exportButton.addEventListener("click", () => {
      exportCryptoKey(key);
    });
  }
}

// Generate an encrypt/decrypt secret key,
// then enable and set up an event listener on the "Export" button.
window.crypto.subtle
  .generateKey(
    {
      name: "AES-GCM",
      length: 256,
    },
    true,
    ["encrypt", "decrypt"],
  )
  .then(setExportButton(key));
```

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

| Specification |
| --- |
| Web Cryptography API # dom-cryptokey-extractable |

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

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


CryptoKey: type property - Web APIs

CryptoKey: type property
========================

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

The read-only **`type`** property of the `CryptoKey` interface indicates which kind of key is represented by the object. It can have the following values:

* `"secret"`: This key is a secret key for use with a symmetric algorithm.
* `"private"`: This key is the private half of an asymmetric algorithm's `CryptoKeyPair`.
* `"public"`: This key is the public half of an asymmetric algorithm's `CryptoKeyPair`.
Value
-----

One of the following strings: `"secret"`, `"private"`, or `"public"`.

Examples
--------

This function verifies a message using `SubtleCrypto.verify()` and a public key given in the parameter. If the key is not a public key, it always returns `"invalid"`, as such verification is fundamentally insecure.

```js
async function verifyMessage(publicKey) {
  const signatureValue = document.querySelector(
    ".rsassa-pkcs1 .signature-value",
  );
  signatureValue.classList.remove("valid", "invalid");

  let result = false; // By default, it is invalid

  if (publicKey.type === "public") {
    const encoded = getMessageEncoding();
    result = await window.crypto.subtle.verify(
      "RSASSA-PKCS1-v1\_5",
      publicKey,
      signature,
      encoded,
    );
  }

  signatureValue.classList.add(result ? "valid" : "invalid");
}
```

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

| Specification |
| --- |
| Web Cryptography API # dom-cryptokey-type |

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

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


TaskController: TaskController() constructor - Web APIs

TaskController: TaskController() 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 **`TaskController()`** constructor creates a new `TaskController` object, optionally setting the initial priority of its associated `signal`.

If no priority is set, the signal priority defaults to `user-visible`

Syntax
------

```js
new TaskController()
new TaskController(options)
```

### Parameters

`options` Optional

An object with the following properties:

`priority` Optional

 The priority of the signal associated with this `TaskController`.
 One of: `"user-blocking"`, `"user-visible"` (default), `"background"`.

Examples
--------

This code shows how to construct a task controller that has a signal with default priority (`user-visible`).

```js
const controller = new TaskController();
```

To construct a task controller that has a specific signal priority, pass the `priority` as a property of the optional argument.

```js
controller2 = new TaskController({ priority: "user-blocking" });
```

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

| Specification |
| --- |
| Prioritized Task Scheduling # dom-taskcontroller-taskcontroller |

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

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


TaskController: setPriority() method - Web APIs

TaskController: setPriority() 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 **`setPriority()`** method of the `TaskController` interface can be called to set a new priority for this controller's `signal`.
 If a prioritized task is configured to use the signal, this will also change the task priority.

 Observers are notified of priority changes by dispatching a `prioritychange` event.
 The method will only notify if the priority actually changes (the event is not fired if the priority would not be changed by the call).

 Note that task priority can only be changed for tasks with mutable priorities.
 If the task is immutable, the function call is ignored.

Syntax
------

```js
setPriority(priority)
```

### Parameters

`priority`

 The priority of the task.
 One of: `"user-blocking"`, `"user-visible"`, `"background"`.

### Return Value

None (`undefined`).

### Exceptions

`NotAllowedError` `DOMException`

A priority change has been started when one is already running.

Examples
--------

 First we create a task controller.
 In this case we don't specify a priority, so it will default to `user-visible`.

```js
// Create a TaskController with default priority: 'user-visible'
const controller = new TaskController();
```

Then we pass the controller's signal to the `Scheduler.postTask()` method.

```js
// Post task passing the controller's signal.
// The signal priority sets the initial priority of the task
scheduler
  .postTask(() => "Task execute", { signal: controller.signal })
  .then((taskResult) => {
    console.log(`${taskResult}`);
  }) // Run on success)
  .catch((error) => {
    console.log(`Catch error: ${error}`);
  }); // Run on fail
```

The controller can then be used to change the priority

```js
// Change the priority to 'background' using the controller
controller.setPriority("background");
```

Additional examples, including showing how to handle the event that results from changing the priority, can be found in: Prioritized Task Scheduling API > Examples.

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

| Specification |
| --- |
| Prioritized Task Scheduling # dom-taskcontroller-setpriority |

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

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


Using the CSS Typed Object Model - Web APIs

Using the CSS Typed Object Model
================================

The **CSS Typed Object Model API** exposes CSS values as typed JavaScript objects to allow their performant manipulation.

Converting CSS Object Model value strings into meaningfully-typed JavaScript representations and back (via `HTMLElement.style`) can incur a significant performance overhead.

The CSS Typed OM makes CSS manipulation more logical and performant by providing object features (rather than CSSOM string manipulation), providing access to types, methods, and an object model for CSS values.

This article provides an introduction to all of its main features.

computedStyleMap()
------------------

With the CSS Typed OM API, we can access all the CSS properties and values — including custom properties — that are impacting an element. Let's see how this works by creating our first example, which explores `computedStyleMap()`.

### Getting all the properties and values

#### HTML

We start with some HTML: a paragraph with a link, as well as a definition list to which we will add all the CSS Property / Value pairs.

```html
<p>
  <a href="https://example.com">Link</a>
</p>
<dl id="regurgitation"></dl>
```

#### JavaScript

We add JavaScript to grab our unstyled link and return back a definition list of all the default CSS property values impacting the link using `computedStyleMap()`.

```js
// Get the element
const myElement = document.querySelector("a");

// Get the <dl> we'll be populating
const stylesList = document.querySelector("#regurgitation");

// Retrieve all computed styles with computedStyleMap()
const defaultComputedStyles = myElement.computedStyleMap();

// Iterate through the map of all the properties and values, adding a <dt> and <dd> for each
for (const [prop, val] of defaultComputedStyles) {
  // properties
  const cssProperty = document.createElement("dt");
  cssProperty.appendChild(document.createTextNode(prop));
  stylesList.appendChild(cssProperty);

  // values
  const cssValue = document.createElement("dd");
  cssValue.appendChild(document.createTextNode(val));
  stylesList.appendChild(cssValue);
}
```

The `computedStyleMap()` method returns a `StylePropertyMapReadOnly` object containing the `size` property, which indicates how many properties are in the map. We iterate through the style map, creating a `<dt>` and `<dd>` for each property and value respectively.

#### Result

In browsers that support `computedStyleMap()`, you'll see a list of all the CSS properties and values. In other browsers, you'll just see a link.

Did you realize how many default CSS properties a link had? Update the JavaScript on line 2 to select the `<p>` rather than the `<a>`. You'll notice a difference in the `margin-top` and `margin-bottom` default computed values.

### .get() method / custom properties

Let's update our example to only retrieve a few properties and values. Let's start by adding some CSS to our example, including a custom property and an inheritable property:

```css
p {
  font-weight: bold;
}

a {
  --color: red;
  color: var(--color);
}
```

Instead of getting *all* the properties, we create an array of properties of interest and use the `StylePropertyMapReadOnly.get()` method to get each of their values:
```

<p>
  <a href="https://example.com">Link</a>
</p>
<dl id="regurgitation"></dl>
```

```js
// Get the element
const myElement = document.querySelector("a");

// Get the <dl> we'll be populating
const stylesList = document.querySelector("#regurgitation");

// Retrieve all computed styles with computedStyleMap()
const allComputedStyles = myElement.computedStyleMap();

// Array of properties we're interested in
const ofInterest = ["font-weight", "border-left-color", "color", "--color"];

// iterate through our properties of interest
for (const value of ofInterest) {
  // Properties
  const cssProperty = document.createElement("dt");
  cssProperty.appendChild(document.createTextNode(value));
  stylesList.appendChild(cssProperty);

  // Values
  const cssValue = document.createElement("dd");
  cssValue.appendChild(document.createTextNode(allComputedStyles.get(value)));
  stylesList.appendChild(cssValue);
}
```

We included `border-left-color` to demonstrate that, had we included all the properties, every value that defaults to `currentcolor` (including `caret-color`, `outline-color`, `text-decoration-color`, `column-rule-color`, etc.) would return `rgb(255 0 0)`. The link has inherited `font-weight: bold;` from the paragraph's styles, listing it as `font-weight: 700`. Custom properties, like our `--color: red`, are properties. As such, they are accessible via `get()`.

You'll note that custom properties retain the value as written in the stylesheet, whereas computed styles will be listed as the computed value — `color` was listed as an `rgb()` value and the `font-weight` returned was `700` even though we use a `named color` and the `bold` keyword.

### CSSUnitValue and CSSKeywordValue

The power of the CSS Typed OM is that values are separate from units; parsing and concatenating string values may become be a thing of the past. Every CSS property in a style map has a value. If the value is a keyword, the object returned is a `CSSKeywordValue`. If the value is numeric, a `CSSUnitValue` is returned.

`CSSKeywordValue` is a class that defines keywords like `inherit`, `initial`, `unset`, and other strings you don't quote, such as `auto` and `grid`. This subclass gives you a `value` property via `cssKeywordValue.value`.

`CSSUnitValue` is returned if the value is a unit type. It is a class that defines numbers with units of measurement like `20px`, `40%`, `200ms`, or `7`. It is returned with two properties: a `value` and a `unit`. With this type we can access the numeric value — `cssUnitValue.value` — and its unit — `cssUnitValue.unit`.

Let's write a plain paragraph, apply no styles, and inspect a few of its CSS properties by returning a table with the unit and value:

```html
<p>
   This is a paragraph with some content. Open up this example in Codepen or
   JSFiddle, and change some features. Try adding some CSS, such as a width
   for this paragraph, or adding a CSS property to the ofInterest array.
</p>
<table id="regurgitation">
  <thead>
    <tr>
      <th>Property</th>
      <th>Value</th>
      <th>Unit</th>
    </tr>
</table>
```

For each property of interest, we list the name of the property, use `.get(propertyName).value` to return the value, and, if the object returned by the `get()` is a `CSSUnitValue`, list the unit type we retrieve with `.get(propertyName).unit`.

```js
// Get the element we're inspecting
const myElement = document.querySelector("p");

// Get the table we'll be populating
const stylesTable = document.querySelector("#regurgitation");

// Retrieve all computed styles with computedStyleMap()
const allComputedStyles = myElement.computedStyleMap();

// Array of properties we're interested in
const ofInterest = [
  "padding-top",
  "margin-bottom",
  "font-size",
  "font-stretch",
  "animation-duration",
  "animation-iteration-count",
  "width",
  "height",
];

// Iterate through our properties of interest
for (const value of ofInterest) {
  // Create a row
  const row = document.createElement("tr");

  // Add the name of the property
  const cssProperty = document.createElement("td");
  cssProperty.appendChild(document.createTextNode(value));
  row.appendChild(cssProperty);

  // Add the unitless value
  const cssValue = document.createElement("td");

  // Shrink long floats to 1 decimal point
  let propVal = allComputedStyles.get(value).value;
  propVal = propVal % 1 ? propVal.toFixed(1) : propVal;
  cssValue.appendChild(document.createTextNode(propVal));
  row.appendChild(cssValue);

  // Add the type of unit
  const cssUnit = document.createElement("td");
  cssUnit.appendChild(
    document.createTextNode(allComputedStyles.get(value).unit),
  );
  row.appendChild(cssUnit);

  // Add the row to the table
  stylesTable.appendChild(row);
}
```

For those of you using a non-supporting browser, the above output should look something like this:

| Property | Value | Unit |
| --- | --- | --- |
| `padding-top` | 0 | `px` |
| `margin-bottom` | 16 | `px` |
| `font-size` | 16 | `px` |
| `font-stretch` | 100 | `%` |
| `animation-duration` | 0 | `px` |
| `animation-iteration-count` | 1 | *number* |
| `width` | auto | *undefined* |
| `height` | auto | *undefined* |

You'll note the `<length>` unit returned is `px`, the `<percentage>` unit returned is `percent`, the `<time>` unit is `s` for 'seconds', and the unitless `<number>` unit is `number`.

We didn't declare a `width` or a `height` for the paragraph, both of which default to `auto` and therefore return a `CSSKeywordValue` instead of a `CSSUnitValue`. `CSSKeywordValue`s do not have a unit property, so in these cases our `get().unit` returns `undefined`.

Had the `width` or `height` been defined in a `<length>` or `<percent>`, the `CSSUnitValue` unit would have been `px` or `percent` respectively.

There are other types available:

* An `<image>` will return a `CSSImageValue`.
* A `<color>` would return a `CSSStyleValue`.
* A `transform` returns a `CSSTransformValue`.
* A custom property returns a `CSSUnparsedValue`.

You can use a `CSSUnitValue` or `CSSKeywordValue` to create other objects.

CSSStyleValue
-------------

The `CSSStyleValue` interface of the CSS Typed Object Model API is the base class of all CSS values accessible through the Typed OM API, including `CSSImageValue`, `CSSKeywordValue`, `CSSNumericValue`, `CSSPositionValue`, `CSSTransformValue`, and `CSSUnparsedValue`.

It has two methods:

* `CSSStyleValue.parse()`
* `CSSStyleValue.parseAll()`

As noted above, `StylePropertyMapReadOnly.get('--customProperty')` returns a `CSSUnparsedValue`. We can parse `CSSUnparsedValue` object instances with the inherited `CSSStyleValue.parse()` and `CSSStyleValue.parseAll()` methods.

Let's examine a CSS example with several custom properties, transforms, `calc()`s, and other features. We'll take a look at what their types are by employing short JavaScript snippets outputting to `console.log()`:

```css
:root {
  --mainColor: hsl(198 43% 42%);
  --black: hsl(0 0% 16%);
  --white: hsl(0 0% 97%);
  --unit: 1.2rem;
}

button {
  --mainColor: hsl(198 100% 66%);
  display: inline-block;
  padding: var(--unit) calc(var(--unit) * 2);
  width: calc(30% + 20px);
  background: no-repeat 5% center url(magicwand.png) var(--mainColor);
  border: 4px solid var(--mainColor);
  border-radius: 2px;
  font-size: calc(var(--unit) * 2);
  color: var(--white);
  cursor: pointer;
  transform: scale(0.95);
}
```

Let's add the class to a button (a button which does nothing).

```html
<button>Styled Button</button>
```

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

// Retrieve all computed styles with computedStyleMap()
const allComputedStyles = button.computedStyleMap();

// CSSMathSum Example
let btnWidth = allComputedStyles.get("width");

console.log(btnWidth); // CSSMathSum
console.log(btnWidth.values); // CSSNumericArray {0: CSSUnitValue, 1: CSSUnitValue, length: 2}
console.log(btnWidth.operator); // 'sum'

// CSSTransformValue
let transform = allComputedStyles.get("transform");

console.log(transform); // CSSTransformValue {0: CSSScale, 1: CSSTranslate, length: 2, is2D: true}
console.log(transform.length); // 1
console.log(transform[0]); // CSSScale {x: CSSUnitValue, y: CSSUnitValue, z: CSSUnitValue, is2D: true}
console.log(transform[0].x); // CSSUnitValue {value: 0.95, unit: "number"}
console.log(transform[0].y); // CSSUnitValue {value: 0.95, unit: "number"}
console.log(transform[0].z); // CSSUnitValue {value: 1, unit: "number"}
console.log(transform.is2D); // true

// CSSImageValue
let bgImage = allComputedStyles.get("background-image");

console.log(bgImage); // CSSImageValue
console.log(bgImage.toString()); // url("magicwand.png")

// CSSUnparsedValue
let unit = allComputedStyles.get("--unit");

console.log(unit);

let parsedUnit = CSSNumericValue.parse(unit);
console.log(parsedUnit);
console.log(parsedUnit.unit);
console.log(parsedUnit.value);
```

We grab our `StylePropertyMapReadOnly` with the following JavaScript:

```js
const allComputedStyles = document.querySelector("button").computedStyleMap();
```

The following examples reference `allComputedStyles`:

### CSSUnparsedValue

The `CSSUnparsedValue` represents custom properties:

```js
// CSSUnparsedValue
const unit = allComputedStyles.get("--unit");

console.log(unit); // CSSUnparsedValue {0: " 1.2rem", length: 1}
console.log(unit[0]); // " 1.2rem"
```

When we invoke `get()`, a custom property of type `CSSUnparsedValue` is returned. Note the space before the `1.2rem`. To get a unit and value, we need a `CSSUnitValue`, which we can retrieve using the `CSSStyleValue.parse()` method on the `CSSUnparsedValue`.

```js
const parsedUnit = CSSNumericValue.parse(unit);
console.log(parsedUnit); // CSSUnitValue {value: 1.2, unit: "rem"}
console.log(parsedUnit.unit); // "rem"
console.log(parsedUnit.value); // 1.2
```

### CSSMathSum

Although the `<button>` element is an inline element by default, we've added `display: inline-block;` to enable sizing. In our CSS we have `width: calc(30% + 20px);`, which is a `calc()` function to define the width.

When we `get()` the `width`, we get a `CSSMathSum` returned. `CSSMathSum.values` is a `CSSNumericArray` with 2 `CSSUnitValues`.

The value of `CSSMathValue.operator` is `sum`:

```js
const btnWidth = allComputedStyles.get("width");

console.log(btnWidth); // CSSMathSum
console.log(btnWidth.values); // CSSNumericArray {0: CSSUnitValue, 1: CSSUnitValue, length: 2}
console.log(btnWidth.operator); // 'sum'
```

### CSSTransformValue with CSSScale

The `display: inline-block;` also enables transforming. In our CSS we have `transform: scale(0.95);`, which is a `transform` function.

```js
const transform = allComputedStyles.get("transform");

console.log(transform); // CSSTransformValue {0: CSSScale, 1: CSSTranslate, length: 2, is2D: true}
console.log(transform.length); // 1
console.log(transform[0]); // CSSScale {x: CSSUnitValue, y: CSSUnitValue, z: CSSUnitValue, is2D: true}
console.log(transform[0].x); // CSSUnitValue {value: 0.95, unit: "number"}
console.log(transform[0].y); // CSSUnitValue {value: 0.95, unit: "number"}
console.log(transform[0].z); // CSSUnitValue {value: 1, unit: "number"}
console.log(transform.is2D); // true
```

When we `get()` the `transform` property, we get a `CSSTransformValue`. We can query the length (or number) of transform functions with the `length` property.

Seen as we have a length of `1`, which represents a single transform function, we log the first object and get a `CSSScale` object. We get `CSSUnitValues` when we query the `x`, `y`, and `z` scaling. The readonly `CSSScale.is2D` property is `true` in this scenario.

Had we added `translate()`, `skew()`, and `rotate()` transform functions, the length would have been `4`, each with their own `x`, `y`, `z` values, and each with an `.is2D` property. For example, had we included `transform: translate3d(1px, 1px, 3px)`, the `.get('transform')` would have returned a `CSSTranslate` with `CSSUnitValues` for `x`, `y`, and `z`, and the readonly `.is2D` property would have been `false`.

### CSSImageValue

Our button has one background image: a magic wand.

```js
const bgImage = allComputedStyles.get("background-image");

console.log(bgImage); // CSSImageValue
console.log(bgImage.toString()); // url("magicwand.png")
```

When we `get()` the `'background-image'`, a `CSSImageValue` is returned. While we used the CSS `background` shorthand property, the inherited `Object.prototype.toString()` method, shows we returned only the image, `'url("magicwand.png")'`.

Notice that the value returned is the absolute path to the image — this is returned even if the original `url()` value was relative. Had the background image been a gradient or multiple background images, `.get('background-image')` would have returned a `CSSStyleValue`. The `CSSImageValue` is returned only if there is a single image, and only if that single image declaration is a URL.

### Summary

This should get you started with understanding the CSS Typed OM. Take a look at all the CSS Typed OM interfaces to learn more.

See also
--------

* Using the CSS Painting API


HTMLMapElement: name property - Web APIs

HTMLMapElement: name property
=============================

 The **`name`** property of the `HTMLMapElement` represents the unique name `<map>` element.
 Its value can be used with the `useMap` attribute of the `<img>` element to reference a `<map>` element.

If an `id` attribute is set on the `<map>` element, then this `name` property should be the same as this `id`.

Value
-----

A non-empty string without whitespaces.

Example
-------

```html
<map name="image-map">
  <area shape="circle" coords="15,15,5" />
</map>
```

```js
const mapElement = document.getElementsByName("image-map")[0];
console.log(mapElement.name); // output: "image-map"
```

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

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

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

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

See also
--------

* `HTMLImageElement.useMap` property
* `HTMLAreaElement` element


PresentationConnection: url property - Web APIs

PresentationConnection: url property
====================================

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

 The **`url`** readonly property of the
 `PresentationConnection` interface returns the URL used to create or
 reconnect to the presentation.

Value
-----

A string containing a URL.

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

| Specification |
| --- |
| Presentation API # dom-presentationconnection-url |

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

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


PresentationConnection: send() method - Web APIs

PresentationConnection: send() method
=====================================

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

 The **`send()`** method of the
 `PresentationConnection` interface tells a controlling browsing context to
 send binary or text data to a presenting browsing context.

Syntax
------

```js
send(data)
```

### Parameters

`data`

The data to send to the presentation context. It will be one of the following:

* `String`
* `Blob`
* `Array`

### Return value

None (`undefined`).

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

| Specification |
| --- |
| Presentation API # dom-presentationconnection-send |

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

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


PresentationConnection: close() method - Web APIs

PresentationConnection: close() method
======================================

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

When the `close()` method is called on a `PresentationConnection`, the user agent begins the process of closing the connection by sending an empty `closeMessage` with the `closeReason` set to `closed`.

Syntax
------

```js
close()
```

### Parameters

None.

### Return value

None (`undefined`).

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

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


PresentationConnection: terminate() method - Web APIs

PresentationConnection: terminate() method
==========================================

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

When the `terminate()` method is called on a `PresentationConnection`, the user agent begins the process of terminating the presentation. The exact process differs depending on whether `terminate()` is called in the controlling or the presenting context.

Syntax
------

```js
terminate()
```

### Parameters

None.

### Return value

None (`undefined`).

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

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


PresentationConnection: binaryType property - Web APIs

PresentationConnection: binaryType property
===========================================

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

When a `PresentationConnection` object is created, its `binaryType` IDL attribute *MUST* be set to the string `"arraybuffer"`. Upon getting, the attribute *MUST* return its most recent value (the value it was last set as). Upon setting, the user agent *MUST* set the IDL attribute to the new value.

**Note:** The `binaryType` attribute allows authors to control how binary data is exposed to scripts. By setting the attribute to `"blob"`, binary data is returned in `Blob` form; by setting it to `"arraybuffer"`, it is returned in `ArrayBuffer` form. The attribute defaults to `"arraybuffer"`. This attribute has no effect on data sent in a string form.

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

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


PresentationConnection: state property - Web APIs

PresentationConnection: state property
======================================

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

The **`state`** attribute reflects the presentation connection's current state. Depending on the current `PresentationConnectionState`, the `state` attribute can hold one of the following values.

* **`connecting`**: The user agent is attempting to establish a presentation connection with the destination browsing context. This is the initial state when a `PresentationConnection` object is created.
* **`connected`**: The presentation connection is established and communication is possible.
* **`closed`**: The presentation connection has been closed or could not be opened. The connection may be reopened by calling `reconnect()`. No communication is possible in this state.
* **`terminated`**: The receiving browsing context has terminated. Any presentation connection to that presentation has also terminated and cannot be reopened. No communication is possible.
Browser compatibility
---------------------

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


PresentationConnection: id property - Web APIs

PresentationConnection: id property
===================================

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

The **`id`** attribute specifies the presentation identifier of a presentation connection.

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

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


UIEvent: detail property - Web APIs

UIEvent: detail property
========================

The **`UIEvent.detail`** read-only property, when non-zero, provides the current (or next, depending on the event) click count.

For `click` or `dblclick` events, `UIEvent.detail` is the current click count.

For `mousedown` or `mouseup` events, `UIEvent.detail` is *1 plus* the current click count.

For all other `UIEvent` objects, `UIEvent.detail` is always zero.

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

| Specification |
| --- |
| UI Events # dom-uievent-detail |

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

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


UIEvent: UIEvent() constructor - Web APIs

UIEvent: UIEvent() constructor
==============================

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

**Note:** If you construct a synthetic event using this constructor, that event will not be *trusted*, for security reasons.
 Only browser-generated `UIEvent` objects are trusted and only trusted events trigger default actions.

Syntax
------

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

### Parameters

`type`

 A string with the name of the event.
 It is case-sensitive and browsers set it to `load`, `unload`, `abort`, `error`, or `select`.

`options` Optional

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

`detail` Optional

 A number that is an event-dependent value associated with the event.
 It defaults to `0` and `UIEvent.detail` lists the semantic for standard events.

`view` Optional

The `Window` associated with the event. Its default value is `null`.

`sourceCapabilities` Optional
Non-standard

 An `InputDeviceCapabilities` object which provides information
 about the physical device responsible for generating a touch event.

### Result value

A new `UIEvent` object.

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

| Specification |
| --- |
| UI Events # dom-uievent-uievent |

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

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

See also
--------

* `UIEvent`, the interface of the objects it constructs.


UIEvent: initUIEvent() method - Web APIs

UIEvent: initUIEvent() method
=============================

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

 The **`UIEvent.initUIEvent()`** method initializes a UI event
 once it's been created.

 Events initialized in this way must have been created with the `Document.createEvent()` method. This method must be called to set the event
 before it is dispatched, using `EventTarget.dispatchEvent()`. Once
 dispatched, it doesn't do anything anymore.

**Warning:** Do not use this method anymore as it is deprecated.

Instead use specific event constructors, like `UIEvent()`. The page on Creating and triggering events gives more information about the way to use these.

Syntax
------

```js
initUIEvent(type, canBubble, cancelable, view, detail)
```

### Parameters

`type`

A string defining the type of event.

`canBubble`

 A boolean value deciding whether the event should bubble up through the
 event chain or not. Once set, the read-only property `Event.bubbles`
 will give its value.

`cancelable`

 A boolean value defining whether the event can be canceled. Once set, the
 read-only property `Event.cancelable` will give its value.

`view`

Is the WindowProxy associated with the event.

`detail`

 An `unsigned long` specifying some detail information about the
 event, depending on the type of event. For mouse events, it indicates how many times
 the mouse has been clicked on a given screen location.

### Return value

None (`undefined`).

Examples
--------

```js
const e = document.createEvent("UIEvent");
// creates a click event that bubbles, can be cancelled,
// and with its view and detail property initialized to window and 1,
// respectively
e.initUIEvent("click", true, true, window, 1);
```

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

| Specification |
| --- |
| UI Events # dom-uievent-inituievent |

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

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

See also
--------

* `UIEvent`
* The constructor to use instead of this deprecated method:
 `UIEvent()`. More specific constructors can be used
 too.


UIEvent: sourceCapabilities property - Web APIs

UIEvent: sourceCapabilities property
====================================

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

 The **`sourceCapabilities`** read-only property of the `UIEvent` interface returns
 an instance of the `InputDeviceCapabilities` interface which provides
 information about the physical device responsible for generating a touch event. If no
 input device was responsible for the event, it returns `null`.

 When a single user interaction with an input device generates a series of different
 input events, the `sourceCapabilities` property for all of them will point to
 the same instance of `InputDeviceCapabilities`. For example, when a user
 lifts their finger off of a touchscreen, several UIEvents may be generated including
 `touchend`, `mousedown`, `click`, and
 `focus`. All of these events must have the same
 `sourceCapabilities` representing the touchscreen.

 A device is considered "responsible" for an event only when that interaction is part of
 the abstraction provided by the web platform. For example, many user agents allow a
 window to be resized with a mouse or a keyboard, but this detail is not exposed to the
 web platform in any way, and so the sourceCapabilities of a resize event will typically
 be null.

Value
-----

An instance of `InputDeviceCapabilities`.

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

| Specification |
| --- |
| Input Device Capabilities # dom-uievent-sourcecapabilities |

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

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


UIEvent: which property - Web APIs

UIEvent: which property
=======================

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

The **`UIEvent.which`** read-only property of the `UIEvent` interface returns a number that indicates which button was pressed on the mouse, or the numeric `keyCode` or the character code (`charCode`) of the key pressed on the keyboard.

Value
-----

### Value for KeyboardEvent
Non-standard

 For `KeyboardEvent`, `event.which` contains the numeric code for a particular key pressed, depending on whether an alphanumeric or non-alphanumeric key was pressed.
 Please see deprecated `KeyboardEvent.charCode` and `KeyboardEvent.keyCode` for more details.

**Note:** Consider `KeyboardEvent.key` or `KeyboardEvent.code` for new code.

### Value for MouseEvent
Non-standard

For `MouseEvent`, `event.which` is a number representing a given button:

* `0`: No button
* `1`: Left button
* `2`: Middle button (if present)
* `3`: Right button

 For a mouse configured for left-handed use, the button actions are reversed.
 In this case, the values are read from right to left.

**Note:** Consider `MouseEvent.button` for new code.

Examples
--------

```html
<html lang="en">
  <head>
    <title>charCode/keyCode/which example</title>

    <script>
 function showKeyPress(evt) {
 alert(
 `onkeypress handler:\n` +
 `keyCode property: ${evt.keyCode}\n` +
 `which property: ${evt.which}\n` +
 `charCode property: ${evt.charCode}\n` +
 `Character Key Pressed: ${String.fromCharCode(evt.charCode)}\n`,
 );
 }

 function keyDown(evt) {
 alert(
 `onkeydown handler:\n` +
 `keyCode property: ${evt.keyCode}\n` +
 `which property: ${evt.which}\n`,
 );
 }
 </script>
  </head>

  <body onkeypress="showKeyPress(event);" onkeydown="keyDown(event);">
    <p>Please press any key.</p>
  </body>
</html>
```

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

| Specification |
| --- |
| UI Events # dom-uievent-which |

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

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

See also
--------

* `KeyboardEvent`
* `MouseEvent`


UIEvent: view property - Web APIs

UIEvent: view property
======================

 The **`UIEvent.view`** read-only property returns the
 WindowProxy object from which the event was generated. In browsers, this
 is the `Window` object the event happened in.

Value
-----

A reference to an `AbstractView` object.

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

| Specification |
| --- |
| UI Events # dom-uievent-view |

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

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


IDBVersionChangeEvent: oldVersion property - Web APIs

IDBVersionChangeEvent: oldVersion property
==========================================

 The **`oldVersion`** read-only property of the
 `IDBVersionChangeEvent` interface returns the old version number of the
 database.

When the opened database doesn't exist yet, the value of `oldVersion` is 0.

**Note:** This feature is available in Web Workers

Value
-----

A number containing a 64-bit integer.

Examples
--------

```js
const dbName = "sampleDB";
const dbVersion = 2;
const request = indexedDB.open(dbName, dbVersion);

request.onupgradeneeded = (e) => {
  const db = request.result;
  if (e.oldVersion < 1) {
    db.createObjectStore("store1");
  }

  if (e.oldVersion < 2) {
    db.deleteObjectStore("store1");
    db.createObjectStore("store2");
  }

  // etc. for version < 3, 4…
};
```

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

| Specification |
| --- |
| Indexed Database API 3.0 # dom-idbversionchangeevent-oldversion |

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

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

See also
--------

* Using IndexedDB
* Starting transactions: `IDBDatabase`
* Using transactions: `IDBTransaction`
* Setting a range of keys: `IDBKeyRange`
* Retrieving and making changes to your data: `IDBObjectStore`
* Using cursors: `IDBCursor`
* Reference example: To-do Notifications (View the example live).


IDBVersionChangeEvent: newVersion property - Web APIs

IDBVersionChangeEvent: newVersion property
==========================================

 The **`newVersion`** read-only property of the
 `IDBVersionChangeEvent` interface returns the new version number of the
 database.

**Note:** This feature is available in Web Workers

Value
-----

A number that is a 64-bit integer or null if the database is being deleted.

Examples
--------

 In the following code snippet, we make a request to open a database, and include
 handlers for the success and error cases. These events are fired via the custom
 `IDBVersionChangeEvent` interface. For a full working example, see our To-do Notifications app (view example live).

```js
const note = document.querySelector("ul");

// Let us open version 4 of our database
const DBOpenRequest = window.indexedDB.open("toDoList", 4);

// these two event handlers act on the database being opened
DBOpenRequest.onerror = (event) => {
  note.innerHTML += "<li>Error loading database.</li>";
};

DBOpenRequest.onsuccess = (event) => {
  note.innerHTML += "<li>Database initialized.</li>";

  // store the result of opening the database in the db variable.
  // This is used a lot later on, for opening transactions and suchlike.
  const db = DBOpenRequest.result;
};
```

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

| Specification |
| --- |
| Indexed Database API 3.0 # dom-idbversionchangeevent-newversion |

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

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

See also
--------

* Using IndexedDB
* Starting transactions: `IDBDatabase`
* Using transactions: `IDBTransaction`
* Setting a range of keys: `IDBKeyRange`
* Retrieving and making changes to your data: `IDBObjectStore`
* Using cursors: `IDBCursor`
* Reference example: To-do Notifications (View the example live).


IDBVersionChangeEvent: IDBVersionChangeEvent() constructor - Web APIs

IDBVersionChangeEvent: IDBVersionChangeEvent() constructor
==========================================================

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

 The **`IDBVersionChangeEvent()`** constructor
 creates a new `IDBVersionChangeEvent` object, which is used to represent
 when a version of the database has changed, as a result of the
 `onupgradeneeded` event handler.

Syntax
------

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

### Parameters

`type`

 A string with the name of the event.
 It is case-sensitive and browsers set it to `versionchange`, `success`, or `blocked`.

`options` Optional

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

`oldVersion` Optional

A number representing the previous version of the database. It defaults to `0`.

`newVersion` Optional

 An unsigned long representing the new version of the database,
 or `null` if the database is being deleted. It defaults is `null`.

### Return value

A new `IDBVersionChangeEvent` object.

Examples
--------

For a full working example, see our To-do Notifications app (view example live).

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

| Specification |
| --- |
| Indexed Database API 3.0 # dom-idbversionchangeevent-idbversionchangeevent |

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

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


WindowControlsOverlayGeometryChangeEvent: WindowControlsOverlayGeometryChangeEvent() constructor - Web APIs

WindowControlsOverlayGeometryChangeEvent: WindowControlsOverlayGeometryChangeEvent() constructor
================================================================================================

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

The **`WindowControlsOverlayGeometryChangeEvent()`** constructor returns a new `WindowControlsOverlayGeometryChangeEvent` object, representing the current geometry of a desktop Progressive Web App's title bar area.

Syntax
------

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

### Parameters

*The `WindowControlsOverlayGeometryChangeEvent()` constructor also inherits arguments from
`Event()`.*

`type`

A string indicating the event type. It is case-sensitive and browsers set it to `geometrychange`.

`options`

An object with the following properties:

`visible` Optional

A boolean flag that's true when the `titlebarAreaRect` object's values are not 0. Its default value is `false`.

`titlebarAreaRect`

A `DOMRect` representing the position and size of the title bar area.

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

| Specification |
| --- |
| Window Controls Overlay # windowcontrolsoverlay-interface |

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

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

See also
--------

* The `WindowControlsOverlayGeometryChangeEvent` interface it belongs to.


WindowControlsOverlayGeometryChangeEvent: visible property - Web APIs

WindowControlsOverlayGeometryChangeEvent: visible property
==========================================================

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

The **`visible`** read-only property of the `WindowControlsOverlayGeometryChangeEvent` interface is a boolean flag that indicates whether the window controls overlay is visible or not in a desktop-installed Progressive Web App.

If the user opts-out of the Window Controls Overlay feature, the default title bar appears and the window controls buttons do not appear as an overlay, in which case the `visible` flag is false.

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

| Specification |
| --- |
| Window Controls Overlay # windowcontrolsoverlay-interface |

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

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


WindowControlsOverlayGeometryChangeEvent: titlebarAreaRect property - Web APIs

WindowControlsOverlayGeometryChangeEvent: titlebarAreaRect property
===================================================================

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

The **`titlebarAreaRect`** read-only property of the `WindowControlsOverlayGeometryChangeEvent` interface is a `DOMRect` representing the position and size of the area occupied by the title bar in a desktop-installed Progressive Web App.

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

| Specification |
| --- |
| Window Controls Overlay # windowcontrolsoverlay-interface |

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

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