Request: text() method - Web APIs

Request: text() method
======================

 The **`text()`** method of the `Request` interface
 reads the request body and returns it as a promise that resolves with a `String`.
 The response is *always* decoded using UTF-8.

Syntax
------

```js
text()
```

### Parameters

None.

### Return value

A Promise that resolves with a `String`.

Examples
--------

```js
const text = "Hello world";

const request = new Request("/myEndpoint", {
  method: "POST",
  body: text,
});

request.text().then((text) => {
  // do something with the text sent in the request
});
```

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

| Specification |
| --- |
| Fetch Standard # ref-for-dom-body-text① |

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

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

See also
--------

* `Response.text()`


Request: referrer property - Web APIs

Request: referrer property
==========================

 The **`referrer`** read-only property of the
 `Request` interface is set by the user agent to be the referrer of the
 Request. (e.g., `client`, `no-referrer`, or a URL.)

**Note:** If `referrer`'s value is `no-referrer`,
 it returns an empty string.

Value
-----

A string representing the request's referrer.

Examples
--------

 In the following snippet, we create a new request using the
 `Request()` constructor (for an image file in the same directory as
 the script), then save the request referrer in a variable:

```js
const myRequest = new Request("flowers.jpg");
const myReferrer = myRequest.referrer; // returns "about:client" by default
```

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

| Specification |
| --- |
| Fetch Standard # ref-for-dom-request-referrer① |

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

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

See also
--------

* ServiceWorker API
* HTTP access control (CORS)
* HTTP


Request: clone() method - Web APIs

Request: clone() method
=======================

The **`clone()`** method of the `Request` interface creates a copy of the current `Request` object.

 Like the underlying `ReadableStream.tee` api,
 the `body` of a cloned `Response`
 will signal backpressure at the rate of the *faster* consumer of the two bodies,
 and unread data is enqueued internally on the slower consumed `body`
 without any limit or backpressure.
 Beware when you construct a `Request` from a stream and then `clone` it.

`clone()` throws a `TypeError` if the request body has already been used. In fact, the main reason `clone()` exists is to allow multiple uses of body objects (when they are one-use only.)

If you intend to modify the request, you may prefer the `Request` constructor.

Syntax
------

```js
clone()
```

### Parameters

None.

### Return value

A `Request` object, which is an exact copy of the `Request` that `clone()` was called on.

Examples
--------

In the following snippet, we create a new request using the `Request()` constructor (for an image file in the same directory as the script), then clone the request.

```js
const myRequest = new Request("flowers.jpg");
const newRequest = myRequest.clone(); // a copy of the request is now stored in newRequest
```

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

| Specification |
| --- |
| Fetch Standard # ref-for-dom-request-clone① |

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

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

See also
--------

* ServiceWorker API
* HTTP access control (CORS)
* HTTP


Request: json() method - Web APIs

Request: json() method
======================

 The **`json()`** method of the `Request` interface
 reads the request body and returns it as a promise that resolves with the result of parsing the body text as `JSON`.

Note that despite the method being named `json()`, the result is not JSON but is instead the result of taking JSON as input and parsing it to produce a JavaScript object.

Syntax
------

```js
json()
```

### Parameters

None.

### Return value

 A `Promise` that resolves to a JavaScript object. This object could be
 anything that can be represented by JSON — an object, an array, a string, a number…

Examples
--------

```js
const obj = { hello: "world" };

const request = new Request("/myEndpoint", {
  method: "POST",
  body: JSON.stringify(obj),
});

request.json().then((data) => {
  // do something with the data sent in the request
});
```

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

| Specification |
| --- |
| Fetch Standard # ref-for-dom-body-json① |

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

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

See also
--------

* `Response.json()`


Request: referrerPolicy property - Web APIs

Request: referrerPolicy property
================================

 The **`referrerPolicy`** read-only property of the
 `Request` interface returns the referrer policy, which governs what
 referrer information, sent in the `Referer` header, should be included
 with the request.

Value
-----

 A string representing the request's `referrerPolicy`. For
 more information and possible values, see the `Referrer-Policy` HTTP
 header page.

Examples
--------

 In the following snippet, we create a new request using the
 `Request()` constructor (for an image file in the same directory as
 the script), then save the request referrer policy in a variable:

```js
const myRequest = new Request("flowers.jpg");
const myReferrer = myRequest.referrerPolicy; // returns "" by default
```

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

| Specification |
| --- |
| Fetch Standard # ref-for-dom-request-referrerpolicy② |

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

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

See also
--------

* ServiceWorker API
* HTTP access control (CORS)
* HTTP


Request: formData() method - Web APIs

Request: formData() method
==========================

 The **`formData()`** method of the `Request` interface
 reads the request body and returns it as a promise that resolves with a `FormData` object.

Syntax
------

```js
formData()
```

### Parameters

None.

### Return value

A `Promise` that resolves with a `FormData` object.

Examples
--------

```js
const formData = new FormData();
const fileField = document.querySelector('input[type="file"]');

formData.append("username", "abc123");
formData.append("avatar", fileField.files[0]);

const request = new Request("/myEndpoint", {
  method: "POST",
  body: formData,
});

request.formData().then((data) => {
  // do something with the formdata sent in the request
});
```

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

| Specification |
| --- |
| Fetch Standard # ref-for-dom-body-formdata① |

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

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

See also
--------

* `Response.formData()`


Request: body property - Web APIs

Request: body property
======================

 The read-only **`body`** property of the `Request`
 interface contains a `ReadableStream` with the body contents
 that have been added to the request. Note that a request using the
 `GET` or `HEAD` method cannot have a body
 and `null` is returned in these cases.

Value
-----

A `ReadableStream` or `null`.

Examples
--------

```js
const request = new Request("/myEndpoint", {
  method: "POST",
  body: "Hello world",
});

request.body; // ReadableStream
```

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

| Specification |
| --- |
| Fetch Standard # ref-for-dom-body-body① |

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

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

See also
--------

* `Request.bodyUsed`


Request: bodyUsed property - Web APIs

Request: bodyUsed property
==========================

 The read-only **`bodyUsed`** property of the
 `Request` interface is a boolean value that indicates
 whether the request body has been read yet.

Value
-----

A boolean value.

Examples
--------

```js
const request = new Request("/myEndpoint", {
  method: "POST",
  body: "Hello world",
});

request.bodyUsed; // false

request.text().then((bodyAsText) => {
  console.log(request.bodyUsed); // true
});
```

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

| Specification |
| --- |
| Fetch Standard # ref-for-dom-body-bodyused① |

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

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

See also
--------

* `Request.body`


Request: method property - Web APIs

Request: method property
========================

 The **`method`** read-only property of the
 `Request` interface contains the request's method (`GET`,
 `POST`, etc.)

Value
-----

A `String` indicating the method of the request.

Examples
--------

 In the following snippet, we create a new request using the
 `Request()` constructor (for an image file in the same directory as
 the script), then save the method of the request in a variable:

```js
const myRequest = new Request("flowers.jpg");
const myMethod = myRequest.method; // GET
```

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

| Specification |
| --- |
| Fetch Standard # ref-for-dom-request-method② |

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

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

See also
--------

* ServiceWorker API
* HTTP access control (CORS)
* HTTP


Request: cache property - Web APIs

Request: cache property
=======================

The **`cache`** read-only property of the `Request` interface contains the cache mode of the request. It controls how the request will interact with the browser's HTTP cache.

Value
-----

A `RequestCache` value. The available values are:

* `default` — The browser looks for a matching request in its HTTP cache.
    + If there is a match and it is fresh, it will be returned from the cache.
    + If there is a match but it is stale, the browser will make a conditional request to the remote server. If the server indicates that the resource has not changed, it will be returned from the cache. Otherwise the resource will be downloaded from the server and the cache will be updated.
    + If there is no match, the browser will make a normal request, and will update the cache with the downloaded resource.
* `no-store` — The browser fetches the resource from the remote server without first looking in the cache, *and will not* update the cache with the downloaded resource.
* `reload` — The browser fetches the resource from the remote server without first looking in the cache, *but then will* update the cache with the downloaded resource.
* `no-cache` — The browser looks for a matching request in its HTTP cache.
    + If there is a match, *fresh or stale,* the browser will make a conditional request to the remote server. If the server indicates that the resource has not changed, it will be returned from the cache. Otherwise the resource will be downloaded from the server and the cache will be updated.
    + If there is no match, the browser will make a normal request, and will update the cache with the downloaded resource.
* `force-cache` — The browser looks for a matching request in its HTTP cache.
    + If there is a match, *fresh or stale*, it will be returned from the cache.
    + If there is no match, the browser will make a normal request, and will update the cache with the downloaded resource.
* `only-if-cached` — The browser looks for a matching request in its HTTP cache.
    + If there is a match, *fresh or stale*, it will be returned from the cache.
    + If there is no match, the browser will respond with a 504 Gateway timeout status.The `"only-if-cached"` mode can only be used if the request's `mode` is `"same-origin"`. Cached redirects will be followed if the request's `redirect` property is `"follow"` and the redirects do not violate the `"same-origin"` mode.
Examples
--------

```js
// Download a resource with cache busting, to bypass the cache
// completely.
fetch("some.json", { cache: "no-store" }).then((response) => {
  /\* consume the response \*/
});

// Download a resource with cache busting, but update the HTTP
// cache with the downloaded resource.
fetch("some.json", { cache: "reload" }).then((response) => {
  /\* consume the response \*/
});

// Download a resource with cache busting when dealing with a
// properly configured server that will send the correct ETag
// and Date headers and properly handle If-Modified-Since and
// If-None-Match request headers, therefore we can rely on the
// validation to guarantee a fresh response.
fetch("some.json", { cache: "no-cache" }).then((response) => {
  /\* consume the response \*/
});

// Download a resource with economics in mind! Prefer a cached
// albeit stale response to conserve as much bandwidth as possible.
fetch("some.json", { cache: "force-cache" }).then((response) => {
  /\* consume the response \*/
});

// Naive stale-while-revalidate client-level implementation.
// Prefer a cached albeit stale response; but update if it's too old.
// AbortController and signal to allow better memory cleaning.
// In reality; this would be a function that takes a path and a
// reference to the controller since it would need to change the value
let controller = new AbortController();
fetch("some.json", {
  cache: "only-if-cached",
  mode: "same-origin",
  signal: controller.signal,
})
  .catch((e) =>
    e instanceof TypeError && e.message === "Failed to fetch"
      ? { status: 504 } // Workaround for chrome; which fails with a TypeError
      : Promise.reject(e),
  )
  .then((res) => {
    if (res.status === 504) {
      controller.abort();
      controller = new AbortController();
      return fetch("some.json", {
        cache: "force-cache",
        mode: "same-origin",
        signal: controller.signal,
      });
    }
    const date = res.headers.get("date"),
      dt = date ? new Date(date).getTime() : 0;
    if (dt < Date.now() - 86\_400\_000) {
      // if older than 24 hours
      controller.abort();
      controller = new AbortController();
      return fetch("some.json", {
        cache: "reload",
        mode: "same-origin",
        signal: controller.signal,
      });
    }

    // Other possible conditions
    if (dt < Date.now() - 300\_000)
      // If it's older than 5 minutes
      fetch("some.json", { cache: "no-cache", mode: "same-origin" }); // no cancellation or return value.
    return res;
  })
  .then((response) => {
    /\* consume the (possibly stale) response \*/
  })
  .catch((error) => {
    /\* Can be an AbortError/DOMException or a TypeError \*/
  });
```

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

| Specification |
| --- |
| Fetch Standard # ref-for-dom-request-cache② |

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

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

See also
--------

* ServiceWorker API
* HTTP access control (CORS)
* HTTP


Request: credentials property - Web APIs

Request: credentials property
=============================

The **`credentials`** read-only property of the `Request` interface indicates whether the user agent should send or receive cookies from the other domain in the case of cross-origin requests.

Value
-----

A `RequestCredentials` dictionary value indicating whether the user agent should send or receive cookies from the other domain in the case of cross-origin requests. Possible values are:

`omit`

Never send or receive cookies.

`same-origin`

Send user credentials (cookies, basic http auth, etc..) if the URL is on the same origin as the calling script. **This is the default value.**

`include`

Always send user credentials (cookies, basic http auth, etc..), even for cross-origin calls.

This is similar to XHR's `withCredentials` flag, but with three available values instead of two.

Examples
--------

In the following snippet, we create a new request using the `Request()` constructor (for an image file in the same directory as the script), then save the request credentials in a variable:

```js
const myRequest = new Request("flowers.jpg");
const myCred = myRequest.credentials; // returns "same-origin" by default
```

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

| Specification |
| --- |
| Fetch Standard # ref-for-dom-request-credentials② |

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

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

See also
--------

* ServiceWorker API
* HTTP access control (CORS)
* HTTP


Request: Request() constructor - Web APIs

Request: Request() constructor
==============================

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

Syntax
------

```js
new Request(input)
new Request(input, options)
```

### Parameters

`input`

Defines the resource that you wish to fetch. This can either be:

* A string containing the URL of the resource you want to fetch. The URL may be relative to the base URL, which is the document's `baseURI` in a window context, or `WorkerGlobalScope.location` in a worker context.
* A `Request` object, effectively creating a copy. Note the following
 behavioral updates to retain security while making the constructor less likely to
 throw exceptions:
    + If this object exists on another origin to the constructor call, the
     `Request.referrer` is stripped out.
    + If this object has a `Request.mode` of `navigate`,
     the `mode` value is converted to `same-origin`.

`options` Optional

 An object containing any custom settings that you want to apply to the
 request. The possible options are:

`method`

 The request method, e.g., `GET`,
 `POST`. The default is `GET`.

`headers`

 Any headers you want to add to your request, contained
 within a `Headers` object or an object literal with
 `String` values.

`body`

 Any body that you want to add to your request: this can be a
 `Blob`, an `ArrayBuffer`, a `TypedArray`, a `DataView`,
 a `FormData`, a `URLSearchParams`, a string, or a `ReadableStream` object.
 Note that a request using the `GET` or `HEAD` method cannot have a body.

`mode`

 The mode you want to use for the request, e.g.,
 `cors`, `no-cors`, `same-origin`, or
 `navigate`. The default is `cors`.

`credentials`

 The request credentials you want to use for the
 request: `omit`, `same-origin`, or `include`. The
 default is `same-origin`.

`cache`

The cache mode you want to use for the request.

`redirect`

 The redirect mode to use: `follow`,
 `error`, or `manual`. The default is `follow`.

`referrer`

 A string specifying
 `no-referrer`, `client`, or a URL. The default is
 `about:client`.

`referrerPolicy`

A string that changes how the referrer header is populated during certain actions (e.g., fetching subresources, prefetching, performing navigations).

`integrity`

 Contains the subresource integrity
 value of the request (e.g.,
 `sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=`).

`keepalive`

A boolean that indicates whether to make a persistent connection for multiple requests/responses.

`signal`

An AbortSignal object which can be used to communicate with/abort a request.

`priority`

Specifies the priority of the fetch request relative to other requests of the same type. Must be one of the following strings:

* `high`: A high priority fetch request relative to other requests of the same type.
* `low`: A low priority fetch request relative to other requests of the same type.
* `auto`: Automatically determine the priority of the fetch request relative to other requests of the same type (default).

If you construct a new `Request` from an existing `Request`, any options you set in an *options* argument for the new request replace any corresponding options set in the original `Request`. For example:

```js
const oldRequest = new Request(
  "https://github.com/mdn/content/issues/12959",
  { headers: { From: "webmaster@example.org" } },
);
oldRequest.headers.get("From"); // "webmaster@example.org"
const newRequest = new Request(oldRequest, {
  headers: { From: "developer@example.org" },
});
newRequest.headers.get("From"); // "developer@example.org"
```

Errors
------

| Type | Description |
| --- | --- |
| `TypeError` |
 Since Firefox 43,
 `Request()` will throw a TypeError if the URL has
 credentials, such as http://user:password@example.com.
  |

Examples
--------

 In our Fetch Request example (see Fetch Request live) we
 create a new `Request` object using the constructor, then fetch it using a
 `fetch()` call. Since we are fetching an image, we run
 `Response.blob` on the response to give it the proper MIME type so it will be
 handled properly, then create an Object URL of it and display it in an
 `<img>` element.

```js
const myImage = document.querySelector("img");

const myRequest = new Request("flowers.jpg");

fetch(myRequest)
  .then((response) => response.blob())
  .then((response) => {
    const objectURL = URL.createObjectURL(response);
    myImage.src = objectURL;
  });
```

 In our Fetch Request with init example (see Fetch Request init live) we do the same thing except that we pass in an *options* object when we
 invoke `fetch()`:

```js
const myImage = document.querySelector("img");

const myHeaders = new Headers();
myHeaders.append("Content-Type", "image/jpeg");

const myOptions = {
  method: "GET",
  headers: myHeaders,
  mode: "cors",
  cache: "default",
};

const myRequest = new Request("flowers.jpg", myOptions);

fetch(myRequest).then((response) => {
  // ...
});
```

 Note that you could also pass `myOptions` into the `fetch` call to get
 the same effect, e.g.:

```js
fetch(myRequest, myOptions).then((response) => {
  // ...
});
```

You can also use an object literal as `headers` in `myOptions`.

```js
const myOptions = {
  method: "GET",
  headers: {
    "Content-Type": "image/jpeg",
  },
  mode: "cors",
  cache: "default",
};

const myRequest = new Request("flowers.jpg", myOptions);
```

 You may also pass a `Request` object to the `Request()`
 constructor to create a copy of the Request (This is similar to calling the
 `clone()` method.)

```js
const copy = new Request(myRequest);
```

**Note:** This last usage is probably only useful in ServiceWorkers.

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

| Specification |
| --- |
| Fetch Standard # ref-for-dom-request① |

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

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

See also
--------

* ServiceWorker API
* HTTP access control (CORS)
* HTTP


MediaStreamEvent: stream property - Web APIs

MediaStreamEvent: stream 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.

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

 The read-only property **`MediaStreamEvent.stream`** returns
 the `MediaStream` associated with the event.

Syntax
------

```js
event.stream
```

Example
-------

```js
pc.onaddstream = (ev) => {
  alert(`A stream (id: '${ev.stream.id}') has been added to this connection.`);
};
```

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

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

See also
--------

* `addstream`, `removestream`
* `RTCPeerConnection`


MediaStreamEvent: MediaStreamEvent() constructor - Web APIs

MediaStreamEvent: MediaStreamEvent() constructor
================================================

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

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

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

Syntax
------

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

### Values

`type`

A string with the name of the event, like `addstream` or `removestream`.

`options`

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

`stream`

A `MediaStream` representing the stream being concerned by the event.

### Return value

A new `MediaStreamEvent` object.

Example
-------

```js
// s is a MediaStream
const event = new MediaStreamEvent("addstream", { stream: s });
```

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

*This feature is no more part of any specification.*

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

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

See also
--------

* WebRTC


SVGImageElement: y property - Web APIs

SVGImageElement: y property
===========================

 The **`y`** read-only property of the
 `SVGImageElement` interface returns an `SVGAnimatedLength`
 corresponding to the `y` attribute of the given `<image>`
 element.

Value
-----

An `SVGAnimatedLength`.

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

| Specification |
| --- |
| Scalable Vector Graphics (SVG) 2 # \_\_svg\_\_SVGImageElement\_\_y |

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

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


SVGImageElement: decoding property - Web APIs

SVGImageElement: decoding property
==================================

The **`decoding`** property of the `SVGImageElement` interface provides a hint to the browser as to whether it should perform image decoding synchronously or asynchronously.

Value
-----

A string representing the decoding hint. Possible values are:

`"sync"`

Decode the image synchronously for atomic presentation with other content.

`"async"`

Decode the image asynchronously and allow other content to be rendered before this completes.

`"auto"`

No preference for the decoding mode; the browser decides what is best for the user. This is the default value, but different browsers have different defaults:

* Chromium defaults to `"sync"`.
* Firefox defaults to `"async"`.
* Safari defaults to `"sync"` except in a small number of circumstances.

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

The `decoding` property provides a hint to the browser as to whether it should perform image decoding along with other tasks in a single step (`"sync"`), or allow other content to be rendered before this completes (`"async"`). In reality, the differences between the two values are often difficult to perceive and, where there are differences, there is often a better way.

For images that are inserted into the DOM inside the viewport, `"async"` can result in flashes of unstyled content, while `"sync"` can result in small amounts of jank. Using the `SVGImageElement.decode()` method is usually a better way to achieve atomic presentation without holding up other content.

For images inserted into the DOM outside of the viewport, modern browsers will usually decode them before they are scrolled into view and there will be no noticeable difference using either value.

Examples
--------

In the below example, you'll likely get an empty image shown on the page as the image is downloaded. Setting `decoding` won't prevent that.

```js
const SVG\_NS = "http://www.w3.org/2000/svg";
const svg = document.querySelector("svg");

const img = document.createElementNS(SVG\_NS, "image");
img.decoding = "sync";
img.setAttribute("href", "img/logo.svg");
svg.appendChild(img);
```

Inserting an image after download can make the `decoding` property more relevant:

```js
async function loadImage(url, elem) {
  return new Promise((resolve, reject) => {
    elem.onload = () => resolve(elem);
    elem.onerror = reject;
    elem.src = url;
  });
}

const SVG\_NS = "http://www.w3.org/2000/svg";
const svg = document.querySelector("svg");

const img = document.createElementNS(SVG\_NS, "image");
await loadImage("img/logo.svg", img);
// Using `sync` can ensure other content is only updated with the image
img.decoding = "sync";
svg.appendChild(img);
const text = document.createElementNS(SVG\_NS, "text");
text.textContent = "Image is fully loaded!";
svg.appendChild(text);
```

A better solution, however, is to use the `SVGImageElement.decode()` method to solve this problem. It provides a way to asynchronously decode an image, delaying inserting it into the DOM until it is fully downloaded and decoded, thereby avoiding the empty image problem mentioned above. This is particularly useful if you're dynamically swapping an existing image for a new one, and also prevents unrelated paints outside of this code from being held up while the image is decoding.

Using `img.decoding = "async"` may avoid holding up other content from displaying if the decoding time is long:

```js
const SVG\_NS = "http://www.w3.org/2000/svg";
const svg = document.querySelector("svg");

const img = document.createElementNS(SVG\_NS, "image");
img.decoding = "async";
img.setAttribute("href", "img/logo.svg");
svg.appendChild(img);
```

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

| Specification |
| --- |
| HTML Standard # dom-img-decoding |

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

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

See also
--------

* The `SVGImageElement.decode()` method
* The SVG `<image>` element `decoding` attribute.


SVGImageElement: width property - Web APIs

SVGImageElement: width property
===============================

 The **`width`** read-only property of the
 `SVGImageElement` interface returns an `SVGAnimatedLength`
 corresponding to the `width` attribute of the given `<image>`
 element.

Value
-----

An `SVGAnimatedLength`.

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

| Specification |
| --- |
| Scalable Vector Graphics (SVG) 2 # \_\_svg\_\_SVGImageElement\_\_width |

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

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


SVGImageElement: x property - Web APIs

SVGImageElement: x property
===========================

 The **`x`** read-only property of the
 `SVGImageElement` interface returns an `SVGAnimatedLength`
 corresponding to the `x` attribute of the given `<image>`
 element.

Value
-----

An `SVGAnimatedLength`.

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

| Specification |
| --- |
| Scalable Vector Graphics (SVG) 2 # \_\_svg\_\_SVGImageElement\_\_x |

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

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


SVGImageElement: height property - Web APIs

SVGImageElement: height property
================================

 The **`height`** read-only property of the
 `SVGImageElement` interface returns an `SVGAnimatedLength`
 corresponding to the `height` attribute of the given
 `<image>` element.

Value
-----

An `SVGAnimatedLength`.

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

| Specification |
| --- |
| Scalable Vector Graphics (SVG) 2 # \_\_svg\_\_SVGImageElement\_\_height |

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

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


SVGImageElement: decode() method - Web APIs

SVGImageElement: decode() method
================================

 The **`decode()`** method of the
 `SVGImageElement` interface initiates asynchronous decoding of an image,
 returning a `Promise` that resolves once the image is decoded and it is safe to append
 it to the DOM.

Syntax
------

```js
decode()
```

### Parameters

None.

### Return value

A `Promise` that fulfills with `undefined` once the image data is ready to be used, for example by appending it to the DOM, replacing an existing image, and so forth.

### Exceptions

None.

Examples
--------

In the below example, you'll likely get an empty image shown on the page as the image is downloaded:

```js
const SVG\_NS = "http://www.w3.org/2000/svg";
const svg = document.querySelector("svg");

const img = document.createElementNS(SVG\_NS, "image");
img.src = "img/logo.svg";
svg.appendChild(img);
```

Using `decode()` will delay inserting the image into the DOM until it is fully downloaded and decoded, thereby avoiding the empty image problem:

```js
const SVG\_NS = "http://www.w3.org/2000/svg";
const svg = document.querySelector("svg");

async function getImage() {
  const img = document.createElementNS(SVG\_NS, "image");
  img.src = "img/logo.svg";
  await img.decode();
  svg.appendChild(img);
  const text = document.createElementNS(SVG\_NS, "text");
  text.textContent = "Image is fully loaded!";
  svg.appendChild(text);
}
```

This is particularly useful if you're dynamically swapping an existing image for a new one, and also prevents unrelated paints outside of this code from being held up while the image is decoding.

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

| Specification |
| --- |
| HTML Standard # dom-img-decode-dev |

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

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

See also
--------

* `HTMLImageElement.decode()`: The same thing, but for HTML `<img>` elements
* What does the image decoding attribute actually do? on tunetheweb.com (2023)


SVGImageElement: preserveAspectRatio property - Web APIs

SVGImageElement: preserveAspectRatio property
=============================================

 The **`preserveAspectRatio`** read-only
 property of the `SVGImageElement` interface returns an
 `SVGAnimatedPreserveAspectRatio` corresponding to the
 `preserveAspectRatio` attribute of the given `<image>`
 element.

Value
-----

An `SVGAnimatedPreserveAspectRatio`.

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

| Specification |
| --- |
| Scalable Vector Graphics (SVG) 2 # PreserveAspectRatioAttribute |

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

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


LargestContentfulPaint: renderTime property - Web APIs

LargestContentfulPaint: renderTime property
===========================================

The **`renderTime`** read-only property of the `LargestContentfulPaint` interface represents the time that the element was rendered to the screen.

Value
-----

The `renderTime` property can have the following values:

* A `timestamp` representing the time in milliseconds that the element was rendered to the screen.
* `0` if the resource is a cross-origin request and no `Timing-Allow-Origin` HTTP response header is used.
Examples
--------

### Logging the renderTime of the largest contentful paint

This example uses a `PerformanceObserver` notifying of new `largest-contentful-paint` performance entries as they are recorded in the browser's performance timeline. The `buffered` option is used to access entries from before the observer creation.

```js
const observer = new PerformanceObserver((list) => {
  const entries = list.getEntries();
  const lastEntry = entries[entries.length - 1]; // Use the latest LCP candidate
  console.log(lastEntry.renderTime);
});
observer.observe({ type: "largest-contentful-paint", buffered: true });
```

### Cross-origin image render time

For security reasons, the value of the `renderTime` property is `0` if the resource is a cross-origin request. Instead the `loadTime` is exposed. To expose cross-origin render time information, the `Timing-Allow-Origin` HTTP response header needs to be set.

For example, to allow `https://developer.mozilla.org` to see `renderTime`, the cross-origin resource should send:

```http
Timing-Allow-Origin: https://developer.mozilla.org
```

Alternatively, you can use `startTime` which returns the value of the entry's `renderTime` if it is not `0`, and otherwise the value of this entry's `loadTime`. However, it is recommended to set the `Timing-Allow-Origin` header so that the metrics will be more accurate.

If you use `startTime`, you can flag any inaccuracies by checking if `renderTime` was used:

```js
const isAccurateLCP = entry.renderTime ? true : false;
```

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

| Specification |
| --- |
| Largest Contentful Paint # dom-largestcontentfulpaint-rendertime |

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

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


LargestContentfulPaint: size property - Web APIs

LargestContentfulPaint: size property
=====================================

The **`size`** read-only property of the `LargestContentfulPaint` interface returns the intrinsic size of the element that is the largest contentful paint.

The `size` of the element is the `width` times `height` of the `rectangle` that this element creates on the screen.

Value
-----

An integer representing the width times height of the element.

Examples
--------

### Logging the size of the largest contentful paint element

This example uses a `PerformanceObserver` notifying of new `largest-contentful-paint` performance entries as they are recorded in the browser's performance timeline. The `buffered` option is used to access entries from before the observer creation.

```js
const observer = new PerformanceObserver((list) => {
  const entries = list.getEntries();
  const lastEntry = entries[entries.length - 1]; // Use the latest LCP candidate
  console.log(lastEntry.size);
});
observer.observe({ type: "largest-contentful-paint", buffered: true });
```

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

| Specification |
| --- |
| Largest Contentful Paint # dom-largestcontentfulpaint-size |

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

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


LargestContentfulPaint: id property - Web APIs

LargestContentfulPaint: id property
===================================

The **`id`** read-only property of the `LargestContentfulPaint` interface returns the ID of the element that is the largest contentful paint.

Value
-----

A string containing the ID of the element, or the empty string if there is no such ID.

Examples
--------

### Logging the largest contentful paint element ID

This example uses a `PerformanceObserver` notifying of new `largest-contentful-paint` performance entries as they are recorded in the browser's performance timeline. The `buffered` option is used to access entries from before the observer creation.

```js
const observer = new PerformanceObserver((list) => {
  const entries = list.getEntries();
  const lastEntry = entries[entries.length - 1]; // Use the latest LCP candidate
  console.log(lastEntry.id);
});
observer.observe({ type: "largest-contentful-paint", buffered: true });
```

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

| Specification |
| --- |
| Largest Contentful Paint # dom-largestcontentfulpaint-id |

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

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


LargestContentfulPaint: loadTime property - Web APIs

LargestContentfulPaint: loadTime property
=========================================

The **`loadTime`** read-only property of the `LargestContentfulPaint` interface returns the time that the element was loaded.

Value
-----

A `timestamp` representing the time in milliseconds that the element was loaded.

Examples
--------

### Logging the loadTime of the largest contentful paint

This example uses a `PerformanceObserver` notifying of new `largest-contentful-paint` performance entries as they are recorded in the browser's performance timeline. The `buffered` option is used to access entries from before the observer creation.

```js
const observer = new PerformanceObserver((list) => {
  const entries = list.getEntries();
  const lastEntry = entries[entries.length - 1]; // Use the latest LCP candidate
  console.log(lastEntry.loadTime);
});
observer.observe({ type: "largest-contentful-paint", buffered: true });
```

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

| Specification |
| --- |
| Largest Contentful Paint # dom-largestcontentfulpaint-loadtime |

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

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


LargestContentfulPaint: toJSON() method - Web APIs

LargestContentfulPaint: toJSON() method
=======================================

The **`toJSON()`** method of the `LargestContentfulPaint` interface is a serializer; it returns a JSON representation of the `LargestContentfulPaint` object.

Syntax
------

```js
toJSON()
```

### Parameters

None.

### Return value

A `JSON` object that is the serialization of the `LargestContentfulPaint` object.

The JSON doesn't contain the `element` property because it is of type `Element`, which doesn't provide a `toJSON()` operation.

Examples
--------

### Using the toJSON method

In this example, calling `entry.toJSON()` returns a JSON representation of the `LargestContentfulPaint` object.

```js
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    console.log(entry.toJSON());
  });
});

observer.observe({ type: "largest-contentful-paint", buffered: true });
```

This would log a JSON object like so:

```json
{
  "name": "",
  "entryType": "largest-contentful-paint",
  "startTime": 468.2,
  "duration": 0,
  "size": 19824,
  "renderTime": 468.2,
  "loadTime": 0,
  "id": "",
  "url": ""
}
```

To get a JSON string, you can use `JSON.stringify(entry)` directly; it will call `toJSON()` automatically.

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

| Specification |
| --- |
| Largest Contentful Paint # dom-largestcontentfulpaint-tojson |

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

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

See also
--------

* `JSON`


LargestContentfulPaint: url property - Web APIs

LargestContentfulPaint: url property
====================================

The **`url`** read-only property of the `LargestContentfulPaint` interface returns the request URL of the element, if the element is an image.

Value
-----

A string containing a URL.

Examples
--------

### Logging the url of the largest contentful paint

This example uses a `PerformanceObserver` notifying of new `largest-contentful-paint` performance entries as they are recorded in the browser's performance timeline. The `buffered` option is used to access entries from before the observer creation.

```js
const observer = new PerformanceObserver((list) => {
  const entries = list.getEntries();
  const lastEntry = entries[entries.length - 1]; // Use the latest LCP candidate
  console.log(lastEntry.url);
});
observer.observe({ type: "largest-contentful-paint", buffered: true });
```

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

| Specification |
| --- |
| Largest Contentful Paint # dom-largestcontentfulpaint-url |

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

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


LargestContentfulPaint: element property - Web APIs

LargestContentfulPaint: element property
========================================

The **`element`** read-only property of the `LargestContentfulPaint` interface returns an object representing the `Element` that is the largest contentful paint.

Value
-----

An `Element`.

Examples
--------

### Logging the largest contentful paint element

This example uses a `PerformanceObserver` notifying of new `largest-contentful-paint` performance entries as they are recorded in the browser's performance timeline. The `buffered` option is used to access entries from before the observer creation.

```js
const observer = new PerformanceObserver((list) => {
  const entries = list.getEntries();
  const lastEntry = entries[entries.length - 1]; // Use the latest LCP candidate
  console.log(lastEntry.element);
});
observer.observe({ type: "largest-contentful-paint", buffered: true });
```

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

| Specification |
| --- |
| Largest Contentful Paint # dom-largestcontentfulpaint-element |

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

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


CSSImportRule: media property - Web APIs

CSSImportRule: media property
=============================

 The read-only **`media`** property of the
 `CSSImportRule` interface returns a `MediaList` object,
 containing the value of the `media` attribute of the associated stylesheet.

Value
-----

Returns a `MediaList` object.

The value of `media` can be set by passing a string containing the `media` attribute; for example `"print"`.

Examples
--------

### Getting the media property

 The following stylesheet includes a single `@import` rule. Therefore the
 first item in the list of CSS rules will be a `CSSImportRule`. The
 `media` property returns a `MediaList` object. This includes
 the `mediaText` property with a value of `screen`.

```css
@import url("style.css") screen;
```

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

### Setting the media property

To change the `media` attribute of the associated stylesheet, set the value of `media` to a string containing the new value.

```js
let myRules = document.styleSheets[0].cssRules;
myRules[0].media = "print";
```

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

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssimportrule-media |

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

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


CSSImportRule: supportsText property - Web APIs

CSSImportRule: supportsText property
====================================

The read-only **`supportsText`** property of the `CSSImportRule` interface returns the supports condition specified by the `@import` at-rule.

Value
-----

A string, or `null`.

Examples
--------

The document's single stylesheet contains three `@import` rules. The first declaration imports a stylesheet if `display: flex` is supported. The second declaration imports a stylesheet if the `:has` selector is supported. The third declaration imports a stylesheet without a supports condition.

The `supportsText` property returns the import conditions associated with the at-rule.

```css
@import url("style1.css") supports(display: flex);
@import url("style2.css") supports(selector(p:has(a)));
@import url("style3.css");
```

```js
const myRules = document.styleSheets[0].cssRules;
console.log(myRules[0].supportsText); // returns `"display: flex"`
console.log(myRules[1].supportsText); // returns `"selector(p:has(a))"`
console.log(myRules[2].supportsText); // returns `null`
```

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

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssimportrule-supportstext |

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

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

See also
--------

* Using feature queries
* `@import` and `@supports`


CSSImportRule: stylesheet property - Web APIs

CSSImportRule: stylesheet property
==================================

 The read-only **`styleSheet`** property of the
 `CSSImportRule` interface returns the CSS Stylesheet specified by the
 `@import` at-rule. This will be
 in the form of a `CSSStyleSheet` object.

 An `@import` at-rule always has
 an associated stylesheet.

Value
-----

A `CSSStyleSheet`.

Examples
--------

 The following stylesheet includes a single `@import` rule. Therefore the
 first item in the list of CSS rules will be a `CSSImportRule`. The
 `styleSheet` property returns the imported stylesheet.

```css
@import url("style.css") screen;
```

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

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

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssimportrule-stylesheet |

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

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


CSSImportRule: href property - Web APIs

CSSImportRule: href property
============================

 The read-only **`href`** property of the
 `CSSImportRule` interface returns the URL specified by the
 `@import` at-rule.

 The resolved URL will be the `href` attribute of the
 associated stylesheet.

Value
-----

A string.

Examples
--------

 The following stylesheet includes a single `@import` rule. Therefore the
 first item in the list of CSS rules will be a `CSSImportRule`. The
 `href` property returns the URL of the imported stylesheet.

```css
@import url("style.css") screen;
```

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

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

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssimportrule-href |

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

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


CSSImportRule: layerName property - Web APIs

CSSImportRule: layerName property
=================================

Baseline 2022
-------------

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

* Learn more
* See full compatibility
* Report feedback
The read-only **`layerName`** property of the `CSSImportRule` interface returns the name of the cascade layer created by the `@import` at-rule.

 If the created layer is anonymous, the string is empty (`""`), if no layer has been
 created, it is the `null` object.

Value
-----

A string, that can be empty, or the `null` object.

Examples
--------

The document's single stylesheet contains three `@import` rules. The first declaration imports a stylesheet into a named layer. The second declaration imports a stylesheet into an anonymous layer. The third declaration imports a stylesheet without a layer declaration.

 The `layerName` property returns the name of the layer associated with the imported
 stylesheet.

```css
@import url("style1.css") layer(layer-1);
@import url("style2.css") layer;
@import url("style3.css");
```

```js
const myRules = document.styleSheets[0].cssRules;
console.log(myRules[0].layerName); // returns `"layer-1"`
console.log(myRules[1].layerName); // returns `""` (an anonymous layer)
console.log(myRules[2].layerName); // returns `null`
```

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

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssimportrule-layername |

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

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

See also
--------

* Learning area : Cascade layers
* `@import` and `@layer`


USBDevice: deviceSubclass property - Web APIs

USBDevice: deviceSubclass property
==================================

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

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

* Learn more
* See full compatibility
* Report feedback
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`deviceSubclass`** read only property of the
 `USBDevice` interface one of three properties that identify USB devices for
 the purpose of loading a USB driver that will work with that device. The other two
 properties are USBDevice.deviceClass and USBDevice.deviceProtocol.

Value
-----

A number.

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-devicesubclass |

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

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


USBDevice: claimInterface() method - Web APIs

USBDevice: claimInterface() 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
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`claimInterface()`** method of the
 `USBDevice` interface returns a `promise` that resolves when
 the requested interface is claimed for exclusive access.

Syntax
------

```js
claimInterface(interfaceNumber)
```

### Parameters

`interfaceNumber`

 The index of one of the interfaces supported by the device. Interfaces are
 device specific.

### Return value

A `promise`.

Examples
--------

 The following example shows `claimInterface()` in the context of connecting
 to a USB device.

```js
async function connectDevice(usbDevice) {
  await usbDevice.open();
  if (usbDevice.configuration === null) await usbDevice.selectConfiguration(1);
  await usbDevice.claimInterface(0);
}
```

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-claiminterface② |

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

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


USBDevice: deviceProtocol property - Web APIs

USBDevice: deviceProtocol property
==================================

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

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

* Learn more
* See full compatibility
* Report feedback
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`deviceProtocol`** read only property of the
 `USBDevice` interface one of three properties that identify USB devices for
 the purpose of loading a USB driver that will work with that device. The other two
 properties are `USBDevice.deviceClass`
 and `USBDevice.deviceSubclass`.

Value
-----

A number.

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-deviceprotocol |

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

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


USBDevice: transferIn() method - Web APIs

USBDevice: transferIn() 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
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`transferIn()`** method of the `USBDevice`
 interface returns a `promise` that resolves with a
 `USBInTransferResult` when bulk or interrupt data is received from the USB
 device.

Syntax
------

```js
transferIn(endpointNumber, length)
```

### Parameters

`endpointNumber`

The number of a device-specific endpoint (buffer).

`length`

 The maximum number of bytes that will be read back from the device. The actual data
 is in the `USBInTransferResult` in the resolved Promise.

### Return value

A `promise` that resolves with a `USBInTransferResult`.

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-transferin① |

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

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


USBDevice: isochronousTransferIn() method - Web APIs

USBDevice: isochronousTransferIn() 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
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

The **`isochronousTransferIn()`** method of the `USBDevice` interface returns a `Promise` that resolves with a `USBIsochronousInTransferResult` when time sensitive information has been transmitted to (received by) the USB device.

Syntax
------

```js
isochronousTransferIn(endpointNumber, packetLengths)
```

### Parameters

`endpointNumber`

The number of a device-specific endpoint (buffer).

`packetLengths`

An array of lengths for the packets being received.

### Return value

A `Promise` that resolves with a `USBIsochronousInTransferResult`.

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-isochronoustransferin |

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

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


USBDevice: productName property - Web APIs

USBDevice: productName property
===============================

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

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

* Learn more
* See full compatibility
* Report feedback
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`productName`** read only property of the
 `USBDevice` interface the manufacturer-defined name that identifies a USB
 device.

Value
-----

The manufacturer-defined name that identifies a USB device.

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-productname |

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

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


USBDevice: usbVersionSubminor property - Web APIs

USBDevice: usbVersionSubminor property
======================================

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

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

* Learn more
* See full compatibility
* Report feedback
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`usbVersionSubminor`** read only property of the
 `USBDevice` interface is one of three properties that declare the USB
 protocol version supported by the device. The other two properties
 are USBDevice.usbVersionMajor and USBDevice.usbVersionMinor.

Value
-----

 The first of three properties that declare the USB protocol version supported by the
 device.

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-usbversionsubminor |

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

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


USBDevice: close() method - Web APIs

USBDevice: close() 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
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`close()`** method of the `USBDevice`
 interface returns a `promise` that resolves when all open interfaces are
 released and the device session has ended.

Syntax
------

```js
close()
```

### Parameters

None.

### Return value

A `promise`.

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-close |

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

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


USBDevice: configuration property - Web APIs

USBDevice: configuration property
=================================

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

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

* Learn more
* See full compatibility
* Report feedback
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`configuration`** read only property of the
 `USBDevice` interface returns a `USBConfiguration` object for
 the currently selected interface for a paired USB device.

Value
-----

A `USBConfiguration` object.

Examples
--------

 The following example uses this property to test for the existence of a
 USBConfiguration property to select a configuration before claiming an interface.

```js
async function connectDevice(usbDevice) {
  await usbDevice.open();
  if (usbDevice.configuration === null) await usbDevice.selectConfiguration(1);
  await usbDevice.claimInterface(0);
}
```

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-configuration① |

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

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


USBDevice: serialNumber property - Web APIs

USBDevice: serialNumber property
================================

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

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

* Learn more
* See full compatibility
* Report feedback
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`serialNumber`** read only property of the
 `USBDevice` interface is the manufacturer-defined serial number for the
 specific USB device.

Value
-----

The serial number for the specified USB device

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-serialnumber |

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

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


USBDevice: reset() method - Web APIs

USBDevice: reset() 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
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`reset()`** method of the `USBDevice`
 interface returns a `promise` that resolves when the device is reset and all
 app operations canceled and their promises rejected.

Syntax
------

```js
reset()
```

### Parameters

None.

### Return value

A `promise`.

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-reset |

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

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


USBDevice: forget() method - Web APIs

USBDevice: forget() 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
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

The **`forget()`** method of the `USBDevice` interface returns a `Promise` that resolves when all pending operations are aborted, all open interfaces are released, the device session has ended, and the permission is reset.

Syntax
------

```js
forget()
```

### Parameters

None.

### Return value

A `Promise` which resolves with `undefined` once the device access permission is revoked.

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

| Specification |
| --- |
| WebUSB API # dom-usbdevice-forget |

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

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


USBDevice: controlTransferIn() method - Web APIs

USBDevice: controlTransferIn() 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
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

The **`controlTransferIn()`** method of the `USBDevice` interface returns a `Promise` that resolves with a `USBInTransferResult` when a command or status request has been transmitted to (received by) the USB device.

Syntax
------

```js
controlTransferIn(setup, length)
```

### Parameters

`setup`

An object that sets options for. The available options are:

`requestType`

Must be one of three values specifying whether the transfer is `"standard"` (common to all USB devices) `"class"` (common to an industry-standard class of devices) or `"vendor"`.

`recipient`

Specifies the target of the transfer on the device, one of `"device"`, `"interface"`, `"endpoint"`, or `"other"`.

`request`

A vendor-specific command.

`value`

Vendor-specific request parameters.

`index`

The interface number of the recipient.

`length`

The maximum number of bytes to read from the device. The actual data is in the `USBInTransferResult` in the resolved Promise.

### Return value

`promise` that resolves with a `USBInTransferResult`.

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-controltransferin |

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

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


USBDevice: vendorId property - Web APIs

USBDevice: vendorId property
============================

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

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

* Learn more
* See full compatibility
* Report feedback
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`vendorId`** read only property of the
 `USBDevice` interface is the official usb.org-assigned vendor ID.

Value
-----

The official usb.org-assigned vendor ID.

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-vendorid |

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

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


USBDevice: deviceVersionSubminor property - Web APIs

USBDevice: deviceVersionSubminor property
=========================================

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

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

* Learn more
* See full compatibility
* Report feedback
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`deviceVersionSubminor`** read only property of the
 `USBDevice` interface the patch version number of the device in a semantic
 versioning scheme.

Value
-----

A number.

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-deviceversionsubminor |

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

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


USBDevice: isochronousTransferOut() method - Web APIs

USBDevice: isochronousTransferOut() 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
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`isochronousTransferOut()`** method of the
 `USBDevice` interface returns a `Promise` that resolves with a `USBIsochronousOutTransferResult` when time sensitive information has been transmitted from the USB device.

Syntax
------

```js
isochronousTransferOut(endpointNumber, data, packetLengths)
```

### Parameters

`endpointNumber`

The number of a device-specific endpoint (buffer).

`data`

A `TypedArray` containing the data to send to the device.

`packetLengths`

An array of lengths for the packets being transferred.

### Return value

A `Promise` that resolves with a `USBIsochronousOutTransferResult`.

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-isochronoustransferout |

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

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


USBDevice: open() method - Web APIs

USBDevice: open() 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
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`open()`** method of the `USBDevice`
 interface returns a `promise` that resolves when a device session has
 started.

Syntax
------

```js
open()
```

### Parameters

None.

### Return value

A `promise`.

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-open① |

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

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


USBDevice: releaseInterface() method - Web APIs

USBDevice: releaseInterface() 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
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`releaseInterface()`** method of the
 `USBDevice` interface returns a `promise` that resolves when a
 claimed interface is released from exclusive access.

Syntax
------

```js
releaseInterface(interfaceNumber)
```

### Parameters

`interfaceNumber`

The device-specific index of the currently-claimed interface.

### Return value

A `promise`.

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-releaseinterface① |

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

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


USBDevice: productId property - Web APIs

USBDevice: productId property
=============================

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

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

* Learn more
* See full compatibility
* Report feedback
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`productId`** read only property of the
 `USBDevice` interface the manufacturer-defined code that identifies a USB
 device.

Value
-----

The manufacturer-defined code that identifies a USB device.

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-productid |

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

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


USBDevice: deviceVersionMajor property - Web APIs

USBDevice: deviceVersionMajor property
======================================

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

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

* Learn more
* See full compatibility
* Report feedback
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`deviceVersionMajor`** read only property of the
 `USBDevice` interface he major version number of the device in a semantic
 versioning scheme.

Value
-----

A number.

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-deviceversionmajor |

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

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


USBDevice: transferOut() method - Web APIs

USBDevice: transferOut() 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
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`transferOut()`** method of the `USBDevice`
 interface returns a `promise` that resolves with a
 `USBOutTransferResult` when bulk or interrupt data is sent to the USB
 device.

Syntax
------

```js
transferOut(endpointNumber, data)
```

### Parameters

`endpointNumber`

The number of a device-specific endpoint (buffer).

`data`

A `TypedArray` containing the data to send to the device.

### Return value

A `promise` that resolves with a `USBOutTransferResult`.

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-transferout |

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

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


USBDevice: usbVersionMinor property - Web APIs

USBDevice: usbVersionMinor property
===================================

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

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

* Learn more
* See full compatibility
* Report feedback
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`usbVersionMinor`** read only property of the
 `USBDevice` interface is one of three properties that declare the USB
 protocol version supported by the device. The other two properties
 are USBDevice.usbVersionMajor and USBDevice.usbVersionSubminor.

Value
-----

 The second of three properties that declare the USB protocol version supported by the
 device.

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

| Specification |
| --- |
| WebUSB API # dom-usbdevice-usbversionminor |

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

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


USBDevice: manufacturerName property - Web APIs

USBDevice: manufacturerName property
====================================

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

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

* Learn more
* See full compatibility
* Report feedback
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`manufacturerName`** read only property of the
 `USBDevice` interface the of the organization that manufactured the USB
 device.

Value
-----

A string.

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-manufacturername |

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

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


USBDevice: configurations property - Web APIs

USBDevice: configurations property
==================================

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

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

* Learn more
* See full compatibility
* Report feedback
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`configurations`** read only property of the
 `USBDevice` interface an `array` of device-specific interfaces
 for controlling a paired USB device.

Value
-----

An `array` of `USBConfiguration` objects.

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-configurations① |

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

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


USBDevice: deviceClass property - Web APIs

USBDevice: deviceClass property
===============================

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

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

* Learn more
* See full compatibility
* Report feedback
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`deviceClass`** read only property of the
 `USBDevice` interface one of three properties that identify USB devices for
 the purpose of loading a USB driver that will work with that device. The other two
 properties are USBDevice.deviceSubclass and USBDevice.deviceprotocol.

Value
-----

A number.

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-deviceclass |

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

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


USBDevice: selectAlternateInterface() method - Web APIs

USBDevice: selectAlternateInterface() 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
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`selectAlternateInterface()`** method of the
 `USBDevice` interface returns a `promise` that resolves when
 the specified alternative endpoint is selected.

Syntax
------

```js
selectAlternateInterface(interfaceNumber, alternateSetting)
```

### Parameters

`interfaceNumber`

 The index of one of the interfaces supported by the device. Interfaces are
 device-specific.

`alternateSetting`

The configuration of the selected interface.

### Return value

A `promise`.

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-selectalternateinterface |

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

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


USBDevice: clearHalt() method - Web APIs

USBDevice: clearHalt() 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
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`clearHalt()`** method of the `USBDevice`
 interface returns a `promise` that resolves when a halt condition is
 cleared. A halt condition is when a data transfer to or from the device has a status
 of `'stall'`, which requires the web page (the *host* system, in USB
 terminology) to clear that condition. See the for details.

Syntax
------

```js
clearHalt(direction, endpointNumber)
```

### Parameters

`direction`

 Indicates whether the devices input or output should be cleared. Valid values
 are `'in'` or `'out'`.

`endpointNumber`

 Indicates the number of the endpoint to clear. The promise will reject if an invalid
 endpoint is supplied.

### Return value

A `promise`.

Examples
--------

 The following example shows how to test for and clear a `'stall'` condition
 in the result of a data transfer.

**Note:** What data can be passed to a USB device and how it is passed is particular and unique
 to each device.

```js
while (true) {
  let result = await data.transferIn(1, 6);

  if (result.data && result.data.byteLength === 6) {
    console.log(`Channel 1: ${result.data.getUint16(0)}`);
    console.log(`Channel 2: ${result.data.getUint16(2)}`);
    console.log(`Channel 5: ${result.data.getUint16(4)}`);
  }

  if (result.status === "stall") {
    console.warn("Endpoint stalled. Clearing.");
    await device.clearHalt("in", 1);
  }
}
```

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-clearhalt① |

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

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


USBDevice: controlTransferOut() method - Web APIs

USBDevice: controlTransferOut() 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
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

The **`controlTransferOut()`** method of the `USBDevice` interface returns a `Promise` that resolves with a `USBOutTransferResult` when a command or status operation has been transmitted from the USB device.

Syntax
------

```js
controlTransferOut(setup, data)
```

### Parameters

`setup`

An object that sets options for. The available options are:

`requestType`

Must be one of three values specifying whether the transfer is `"standard"` (common to all USB devices) `"class"` (common to an industry-standard class of devices) or `"vendor"`.

`recipient`

Specifies the target of the transfer on the device, one of `"device"`, `"interface"`, `"endpoint"`, or `"other"`.

`request`

A vendor-specific command.

`value`

Vendor-specific request parameters.

`index`

The interface number of the recipient.

`data`

 A `TypedArray` containing the data that will be transferred to the device.
 Not all commands require data; some commands can send data just through the value parameter.
 Check with your device to see what the specific request requires.

### Return value

A `promise` that resolves with a `USBOutTransferResult`.

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-controltransferout① |

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

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


USBDevice: opened property - Web APIs

USBDevice: opened property
==========================

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

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

* Learn more
* See full compatibility
* Report feedback
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`opened`** read only property of the
 `USBDevice` interface indicates whether a session has been started with a
 paired USB device. A device must be opened before it can be controlled by a web page.

Value
-----

A `boolean`.

Examples
--------

 This example is for a hypothetical USB device with a multi-colored LED. It shows how to
 test that a device is open before calling `USBDevice.controlTransferOut` to
 set a specified LED color.

**Note:** What data can be passed to a USB device and how it is passed is particular and unique
 to each device.

```js
async function setDeviceColor(usbDevice, r, g, b) {
  if (device.opened) {
    // This hypothetical USB device requires that the data passed to
    // it be in a Uint8Array.
    const payload = new Uint8Array([r, g, b]);

    await usbDevice.controlTransferOut(
      {
        requestType: "vendor",
        recipient: "device",
        request: 1,
        value: 0,
        index: 0,
      },
      payload,
    );
  }
}
```

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-opened |

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

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


USBDevice: deviceVersionMinor property - Web APIs

USBDevice: deviceVersionMinor property
======================================

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

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

* Learn more
* See full compatibility
* Report feedback
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`deviceVersionMinor`** read only property of the
 `USBDevice` interface the minor version number of the device in a semantic
 versioning scheme.

Value
-----

A number.

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-deviceversionminor |

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

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


USBDevice: selectConfiguration() method - Web APIs

USBDevice: selectConfiguration() 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
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`selectConfiguration()`** method of the
 `USBDevice` interface returns a `promise` that resolves when
 the specified configuration is selected.

Syntax
------

```js
selectConfiguration(configurationValue)
```

### Parameters

`configurationValue`

The number of a device-specific configuration.

### Return value

A `promise`.

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

| Specification |
| --- |
| WebUSB API # dom-usbdevice-selectconfiguration |

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

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


USBDevice: usbVersionMajor property - Web APIs

USBDevice: usbVersionMajor property
===================================

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

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

* Learn more
* See full compatibility
* Report feedback
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

 The **`usbVersionMajor`** read only property of the
 `USBDevice` interface is one of three properties that declare the USB
 protocol version supported by the device. The other two properties
 are USBDevice.usbVersionMinor and USBDevice.usbVersionSubminor.

Value
-----

 The last of three properties that declare the USB protocol version supported by the
 device.

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

| Specification |
| --- |
| WebUSB API # ref-for-dom-usbdevice-usbversionmajor |

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

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


Serial: requestPort() method - Web APIs

Serial: requestPort() method
============================

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

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

The **`Serial.requestPort()`** method of the `Serial` interface returns a `Promise` that resolves with an instance of `SerialPort` representing the device chosen by the user or rejects if no device was selected.

Syntax
------

```js
requestPort()
requestPort(options)
```

### Parameters

`options`

An object with the following properties:

`filters`

A list of objects containing vendor and product IDs used to search for attached devices. The USB Implementors Forum assigns IDs to specific companies. Each company assigns IDs to its products. Filters contain the following values:

`usbVendorId`

An unsigned short integer that identifies a USB device vendor.

`usbProductId`

An unsigned short integer that identifies a USB device.

### Return value

A `Promise` that resolves with an instance of `SerialPort`.

### Exceptions

`SecurityError` `DOMException`

The returned `Promise` rejects with this error if a Permissions Policy blocks the use of this feature or a user permission prompt was denied.

`NotFoundError` `DOMException`

The returned `Promise` rejects with this if the user does not select a port when prompted.

Security
--------

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

Examples
--------

The following example shows a filter being passed to `requestPort()` with a USB vendor ID in order to limit the set of devices shown to the user to only USB devices built by a particular manufacturer. If this filter was omitted the user would be able to select any available port.

```js
button.addEventListener("click", () => {
  const usbVendorId = 0xabcd;
  navigator.serial
    .requestPort({ filters: [{ usbVendorId }] })
    .then((port) => {
      // Connect to `port` or add it to the list of available ports.
    })
    .catch((e) => {
      // The user didn't select a port.
    });
});
```

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

| Specification |
| --- |
| Web Serial API # dom-serial-requestport |

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

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


Serial: getPorts() method - Web APIs

Serial: getPorts() method
=========================

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

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

The **`getPorts()`** method of the `Serial` interface returns a `Promise` that resolves with an array of `SerialPort` objects representing serial ports connected to the host which the origin has permission to access.

Syntax
------

```js
getPorts()
```

### Parameters

None.

### Return value

A `Promise` that resolves with an array of `SerialPort` objects.

### Exceptions

`SecurityError` `DOMException`

The returned `Promise` rejects with this error if a Permissions Policy blocks the use of this feature or a user permission prompt was denied.

Examples
--------

The following example uses `getPorts()` to initialize a list of available ports.

```js
navigator.serial.getPorts().then((ports) => {
  // Initialize the list of available ports with `ports` on page load.
});
```

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

| Specification |
| --- |
| Web Serial API # dom-serial-getports |

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

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


GPUError: message property - Web APIs

GPUError: message property
==========================

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

 The **`message`** read-only property of the
 `GPUError` interface provides a human-readable message that explains why the error occurred.

Value
-----

A string.

Examples
--------

For usage examples of error objects based on `GPUError`, see:

* `GPUDevice.popErrorScope`
* The `GPUDevice uncapturederror` event
* `GPUInternalError`, `GPUOutOfMemoryError`, and `GPUValidationError`
Specifications
--------------

| Specification |
| --- |
| WebGPU # dom-gpuerror-message |

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

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

See also
--------

* The WebGPU API
* WebGPU Error Handling best practices


OfflineAudioContext: resume() method - Web APIs

OfflineAudioContext: resume() method
====================================

 The **`resume()`** method of the
 `OfflineAudioContext` interface resumes the progression of time in an audio
 context that has been suspended. The promise resolves immediately because the
 `OfflineAudioContext` does not require the audio hardware.

Syntax
------

```js
resume()
```

### Parameters

None.

### Return value

A `Promise` resolving to `undefined`.

### Exceptions

The promise is rejected when an exception is encountered.

`InvalidStateError` `DOMException`

Returned if the context is not currently suspended or the rendering has not started.

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

| Specification |
| --- |
| Web Audio API # dom-offlineaudiocontext-resume |

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

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


OfflineAudioContext: length property - Web APIs

OfflineAudioContext: length property
====================================

 The **`length`** property of the
 `OfflineAudioContext` interface returns an integer representing the size of
 the buffer in sample-frames.

Value
-----

An integer representing the size of the buffer in sample-frames.

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

| Specification |
| --- |
| Web Audio API # dom-offlineaudiocontext-length |

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

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


OfflineAudioContext: suspend() method - Web APIs

OfflineAudioContext: suspend() method
=====================================

 The **`suspend()`** method of the `OfflineAudioContext` interface schedules a suspension of the time
 progression in the audio context at the specified time and returns a promise. This is
 generally useful at the time of manipulating the audio graph synchronously on
 OfflineAudioContext.

 Note that the maximum precision of suspension is the size of the render quantum and the
 specified suspension time will be rounded down to the nearest render quantum boundary.
 For this reason, it is not allowed to schedule multiple suspends at the same quantized
 frame. Also scheduling should be done while the context is not running to ensure the
 precise suspension.

Syntax
------

```js
suspend(suspendTime)
```

### Parameters

`suspendTime`

A floating-point number specifying the suspend time, in seconds.

### Return value

A `Promise` resolving to `undefined`.

### Exceptions

The promise is rejected when any exception is encountered.

`InvalidStateError` `DOMException`

Returned if the quantized frame number is one of the following:

* a negative number
* less than or equal to the current time
* greater than or equal to the total render duration
* scheduled by another suspend for the same time

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

| Specification |
| --- |
| Web Audio API # dom-offlineaudiocontext-suspend |

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

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


OfflineAudioContext: complete event - Web APIs

OfflineAudioContext: complete event
===================================

The `complete` event of the `OfflineAudioContext` interface is fired when the rendering of an offline audio context is complete.

This event is not cancelable and does not bubble.

Syntax
------

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

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

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

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

An `OfflineAudioCompletionEvent`. Inherits from `Event`.

Event

OfflineAudioCompletionEventEvent properties
----------------

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

`OfflineAudioCompletionEvent.renderedBuffer` Read only

An `AudioBuffer` containing the result of processing an `OfflineAudioContext`.

Examples
--------

When processing is complete, you might want to use the `complete` event handler to prompt the user that the audio can now be played, and enable the play button:

```js
const offlineAudioCtx = new OfflineAudioContext();

offlineAudioCtx.addEventListener("complete", () => {
  console.log("Offline audio processing now complete");
  showModalDialog("Song processed and ready to play");
  playBtn.disabled = false;
});
```

You can also set up the event handler using the `oncomplete` property:

```js
const offlineAudioCtx = new OfflineAudioContext();

offlineAudioCtx.oncomplete = () => {
  console.log("Offline audio processing now complete");
  showModalDialog("Song processed and ready to play");
  playBtn.disabled = false;
};
```

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

| Specification |
| --- |
| Web Audio API # OfflineAudioCompletionEvent |
| Web Audio API # dom-offlineaudiocontext-oncomplete |

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

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

See also
--------

* Web Audio API