# AbortController
Baseline Widely available
This feature is well established and works across many devices and browser
versions. It’s been available across browsers since March 2019.
* Learn more
* See full compatibility
* Report feedback
**Note:** This feature is available in Web Workers.
The `AbortController` interface represents a controller object that allows you
to abort one or more Web requests as and when desired.
You can create a new `AbortController` object using the `AbortController()`
constructor. Communicating with an asynchronous operation is done using an
`AbortSignal` object.
## Constructor
`AbortController()`
Creates a new `AbortController` object instance.
## Instance properties
`AbortController.signal` Read only
Returns an `AbortSignal` object instance, which can be used to communicate
with, or to abort, an asynchronous operation.
## Instance methods
`AbortController.abort()`
Aborts an asynchronous operation before it has completed. This is able to
abort fetch requests, consumption of any response bodies, and streams.
## Examples
**Note:** There are additional examples in the `AbortSignal` reference.
In the following snippet, we aim to download a video using the Fetch API.
We first create a controller using the `AbortController()` constructor, then
grab a reference to its associated `AbortSignal` object using the
`AbortController.signal` property.
When the fetch request is initiated, we pass in the `AbortSignal` as an option
inside the request's options object (the `{signal}` below). This associates
the signal and controller with the fetch request and allows us to abort it by
calling `AbortController.abort()`, as seen below in the second event listener.
When `abort()` is called, the `fetch()` promise rejects with a `DOMException`
named `AbortError`.
let controller;
const url = "video.mp4";
const downloadBtn = document.querySelector(".download");
const abortBtn = document.querySelector(".abort");
downloadBtn.addEventListener("click", fetchVideo);
abortBtn.addEventListener("click", () => {
if (controller) {
controller.abort();
console.log("Download aborted");
}
});
async function fetchVideo() {
controller = new AbortController();
const signal = controller.signal;
try {
const response = await fetch(url, { signal });
console.log("Download complete", response);
// process response further
} catch (err) {
console.error(`Download error: ${err.message}`);
}
}
If the request is aborted after the `fetch()` call has been fulfilled but
before the response body has been read, then attempting to read the response
body will reject with an `AbortError` exception.
async function get() {
const controller = new AbortController();
const request = new Request("https://example.org/get", {
signal: controller.signal,
});
const response = await fetch(request);
controller.abort();
// The next line will throw `AbortError`
const text = await response.text();
console.log(text);
}
You can find a full working example on GitHub; you can also see it running
live.
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`AbortController` | 66 | 16 | 57 | 53 | 12.111.1–12.1Even though `window.AbortController` is defined, it doesn't really abort `fetch` requests. See bug 174980. | 66 | 57 | 47 | 12.211.3–12.2Even though `window.AbortController` is defined, it doesn't really abort `fetch` requests. See bug 174980. | 9.0 | 66
`AbortController` | 66 | 16 | 57 | 53 | 12.111.1–12.1Even though `window.AbortController` is defined, it doesn't really abort `fetch` requests. See bug 174980. | 66 | 57 | 47 | 12.211.3–12.2Even though `window.AbortController` is defined, it doesn't really abort `fetch` requests. See bug 174980. | 9.0 | 66
`abort` | 66 | 16 | 57 | 53 | 12.111.1–12.1Even though `window.AbortController` is defined, it doesn't really abort `fetch` requests. See bug 174980. | 66 | 57 | 47 | 12.211.3–12.2Even though `window.AbortController` is defined, it doesn't really abort `fetch` requests. See bug 174980. | 9.0 | 66
`signal` | 66 | 16 | 57 | 53 | 12.111.1–12.1Even though `window.AbortController` is defined, it doesn't really abort `fetch` requests. See bug 174980. | 66 | 57 | 47 | 12.211.3–12.2Even though `window.AbortController` is defined, it doesn't really abort `fetch` requests. See bug 174980. | 9.0 | 66
## See also
* Fetch API
* Abortable Fetch by Jake Archibald
# AbortController: abort() method
Baseline Widely available
This feature is well established and works across many devices and browser
versions. It’s been available across browsers since March 2019.
* Learn more
* See full compatibility
* Report feedback
**Note:** This feature is available in Web Workers.
The `abort()` method of the `AbortController` interface aborts an asynchronous
operation before it has completed. This is able to abort fetch requests, the
consumption of any response bodies, or streams.
## Syntax
abort()
abort(reason)
### Parameters
`reason` Optional
The reason why the operation was aborted, which can be any JavaScript value.
If not specified, the reason is set to "AbortError" `DOMException`.
### Return value
None (`undefined`).
## Examples
In the following snippet, we aim to download a video using the Fetch API.
We first create a controller using the `AbortController()` constructor, then
grab a reference to its associated `AbortSignal` object using the
`AbortController.signal` property.
When the fetch request is initiated, we pass in the `AbortSignal` as an option
inside the request's options object (the `{signal}` below). This associates
the signal and controller with the fetch request and allows us to abort it by
calling `AbortController.abort()`, as seen below in the second event listener.
const controller = new AbortController();
const signal = controller.signal;
const url = "video.mp4";
const downloadBtn = document.querySelector(".download");
const abortBtn = document.querySelector(".abort");
downloadBtn.addEventListener("click", fetchVideo);
abortBtn.addEventListener("click", () => {
controller.abort();
console.log("Download aborted");
});
function fetchVideo() {
fetch(url, { signal })
.then((response) => {
console.log("Download complete", response);
})
.catch((err) => {
console.error(`Download error: ${err.message}`);
});
}
**Note:** When `abort()` is called, the `fetch()` promise rejects with an
`Error` of type `DOMException`, with name `AbortError`.
You can find a full working example on GitHub; you can also see it running
live.
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`abort` | 66 | 16 | 57 | 53 | 12.111.1–12.1Even though `window.AbortController` is defined, it doesn't really abort `fetch` requests. See bug 174980. | 66 | 57 | 47 | 12.211.3–12.2Even though `window.AbortController` is defined, it doesn't really abort `fetch` requests. See bug 174980. | 9.0 | 66
`reason_parameter` | 98 | 98 | 97 | 84 | 15.4 | 98 | 97 | 68 | 15.4 | 18.0 | 98
## See also
* Fetch API
# AbortController: AbortController() constructor
Baseline Widely available
This feature is well established and works across many devices and browser
versions. It’s been available across browsers since March 2019.
* Learn more
* See full compatibility
* Report feedback
**Note:** This feature is available in Web Workers.
The `AbortController()` constructor creates a new `AbortController` object
instance.
## Syntax
new AbortController()
### Parameters
None.
## Examples
In the following snippet, we aim to download a video using the Fetch API.
We first create a controller using the `AbortController()` constructor, then
grab a reference to its associated `AbortSignal` object using the
`AbortController.signal` property.
When the fetch request is initiated, we pass in the `AbortSignal` as an option
inside the request's options object (the `{ signal }` below). This associates
the signal and controller with the fetch request and allows us to abort it by
calling `AbortController.abort()`, as seen below in the second event listener.
const controller = new AbortController();
const signal = controller.signal;
const url = "video.mp4";
const downloadBtn = document.querySelector(".download");
const abortBtn = document.querySelector(".abort");
downloadBtn.addEventListener("click", fetchVideo);
abortBtn.addEventListener("click", () => {
controller.abort();
console.log("Download aborted");
});
function fetchVideo() {
fetch(url, { signal })
.then((response) => {
console.log("Download complete", response);
})
.catch((err) => {
console.error(`Download error: ${err.message}`);
});
}
**Note:** When `abort()` is called, the `fetch()` promise rejects with an
`AbortError`.
You can find a full working example on GitHub; you can also see it running
live.
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`AbortController` | 66 | 16 | 57 | 53 | 12.111.1–12.1Even though `window.AbortController` is defined, it doesn't really abort `fetch` requests. See bug 174980. | 66 | 57 | 47 | 12.211.3–12.2Even though `window.AbortController` is defined, it doesn't really abort `fetch` requests. See bug 174980. | 9.0 | 66
## See also
* Fetch API
# AbortController: signal property
Baseline Widely available
This feature is well established and works across many devices and browser
versions. It’s been available across browsers since March 2019.
* Learn more
* See full compatibility
* Report feedback
**Note:** This feature is available in Web Workers.
The `signal` read-only property of the `AbortController` interface returns an
`AbortSignal` object instance, which can be used to communicate with/abort an
asynchronous operation as desired.
## Value
An `AbortSignal` object instance.
## Examples
In the following snippet, we aim to download a video using the Fetch API.
We first create a controller using the `AbortController()` constructor, then
grab a reference to its associated `AbortSignal` object using the
`AbortController.signal` property.
When the fetch request is initiated, we pass in the `AbortSignal` as an option
inside the request's options object (the `{signal}` below). This associates
the signal and controller with the fetch request and allows us to abort it by
calling `AbortController.abort()`, as seen below in the second event listener.
const controller = new AbortController();
const signal = controller.signal;
const url = "video.mp4";
const downloadBtn = document.querySelector(".download");
const abortBtn = document.querySelector(".abort");
downloadBtn.addEventListener("click", fetchVideo);
abortBtn.addEventListener("click", () => {
controller.abort();
console.log("Download aborted");
});
function fetchVideo() {
fetch(url, { signal })
.then((response) => {
console.log("Download complete", response);
})
.catch((err) => {
console.error(`Download error: ${err.message}`);
});
}
**Note:** When `abort()` is called, the `fetch()` promise rejects with an
`AbortError`.
You can find a full working example on GitHub; you can also see it running
live.
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`signal` | 66 | 16 | 57 | 53 | 12.111.1–12.1Even though `window.AbortController` is defined, it doesn't really abort `fetch` requests. See bug 174980. | 66 | 57 | 47 | 12.211.3–12.2Even though `window.AbortController` is defined, it doesn't really abort `fetch` requests. See bug 174980. | 9.0 | 66
## See also
* Fetch API
# AbortSignal
Baseline Widely available *
This feature is well established and works across many devices and browser
versions. It’s been available across browsers since April 2018.
* Some parts of this feature may have varying levels of support.
* Learn more
* See full compatibility
* Report feedback
**Note:** This feature is available in Web Workers.
The `AbortSignal` interface represents a signal object that allows you to
communicate with an asynchronous operation (such as a fetch request) and abort
it if required via an `AbortController` object.
EventTarget AbortSignal
## Instance properties
_Also inherits properties from its parent interface,`EventTarget`._
`AbortSignal.aborted` Read only
A Boolean that indicates whether the request(s) the signal is communicating
with is/are aborted (`true`) or not (`false`).
`AbortSignal.reason` Read only
A JavaScript value providing the abort reason, once the signal has aborted.
## Static methods
_Also inherits methods from its parent interface,`EventTarget`._
`AbortSignal.abort()`
Returns an `AbortSignal` instance that is already set as aborted.
`AbortSignal.any()`
Returns an `AbortSignal` that aborts when any of the given abort signals
abort.
`AbortSignal.timeout()`
Returns an `AbortSignal` instance that will automatically abort after a
specified time.
## Instance methods
_Also inherits methods from its parent interface,`EventTarget`._
`AbortSignal.throwIfAborted()`
Throws the signal's abort `reason` if the signal has been aborted; otherwise
it does nothing.
## Events
_Also inherits events from its parent interface,`EventTarget`._
Listen to this event using `addEventListener()` or by assigning an event
listener to the `oneventname` property of this interface.
`abort`
Invoked when the asynchronous operations the signal is communicating with
is/are aborted. Also available via the `onabort` property.
## Examples
### Aborting a fetch operation using an explicit signal
The following snippet shows how we might use a signal to abort downloading a
video using the Fetch API.
We first create an abort controller using the `AbortController()` constructor,
then grab a reference to its associated `AbortSignal` object using the
`AbortController.signal` property.
When the fetch request is initiated, we pass in the `AbortSignal` as an option
inside the request's options object (the `{signal}` below). This associates
the signal and controller with the fetch request, and allows us to abort it by
calling `AbortController.abort()`. Below you can see that the fetch operation
is aborted in the second event listener, which triggered when the abort button
(`abortBtn`) is clicked.
When `abort()` is called, the `fetch()` promise rejects with a `DOMException`
named `AbortError`.
let controller;
const url = "video.mp4";
const downloadBtn = document.querySelector(".download");
const abortBtn = document.querySelector(".abort");
downloadBtn.addEventListener("click", fetchVideo);
abortBtn.addEventListener("click", () => {
if (controller) {
controller.abort();
console.log("Download aborted");
}
});
async function fetchVideo() {
controller = new AbortController();
const signal = controller.signal;
try {
const response = await fetch(url, { signal });
console.log("Download complete", response);
// process response further
} catch (err) {
console.error(`Download error: ${err.message}`);
}
}
If the request is aborted after the `fetch()` call has been fulfilled but
before the response body has been read, then attempting to read the response
body will reject with an `AbortError` exception.
async function get() {
const controller = new AbortController();
const request = new Request("https://example.org/get", {
signal: controller.signal,
});
const response = await fetch(request);
controller.abort();
// The next line will throw `AbortError`
const text = await response.text();
console.log(text);
}
You can find a full working example on GitHub; you can also see it running
live.
### Aborting a fetch operation with a timeout
If you need to abort the operation on timeout then you can use the static
`AbortSignal.timeout()` method. This returns an `AbortSignal` that will
automatically timeout after a certain number of milliseconds.
The code snippet below shows how you would either succeed in downloading a
file, or handle a timeout error after 5 seconds. Note that when there is a
timeout the `fetch()` promise rejects with a `TimeoutError` `DOMException`.
This allows code to differentiate between timeouts (for which user
notification is probably required), and user aborts.
const url = "video.mp4";
try {
const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
const result = await res.blob();
// …
} catch (err) {
if (err.name === "TimeoutError") {
console.error("Timeout: It took more than 5 seconds to get the result!");
} else if (err.name === "AbortError") {
console.error(
"Fetch aborted by user action (browser stop button, closing tab, etc.",
);
} else {
// A network error, or some other problem.
console.error(`Error: type: ${err.name}, message: ${err.message}`);
}
}
### Aborting a fetch with timeout or explicit abort
If you want to abort from multiple signals, you can use `AbortSignal.any()` to
combine them into a single signal. The following example shows this using
`fetch`:
try {
const controller = new AbortController();
const timeoutSignal = AbortSignal.timeout(5000);
const res = await fetch(url, {
// This will abort the fetch when either signal is aborted
signal: AbortSignal.any([controller.signal, timeoutSignal]),
});
const body = await res.json();
} catch (e) {
if (e.name === "AbortError") {
// Notify the user of abort.
} else if (e.name === "TimeoutError") {
// Notify the user of timeout
} else {
// A network error, or some other problem.
console.log(`Type: ${e.name}, Message: ${e.message}`);
}
}
**Note:** Unlike when using `AbortSignal.timeout()`, there is no way to tell
whether the final abort was caused by a timeout.
### Implementing an abortable API
An API that needs to support aborting can accept an `AbortSignal` object, and
use its state to trigger abort signal handling when needed.
A `Promise`-based API should respond to the abort signal by rejecting any
unsettled promise with the `AbortSignal` abort `reason`. For example, consider
the following `myCoolPromiseAPI`, which takes a signal and returns a promise.
The promise is rejected immediately if the signal is already aborted, or if
the abort event is detected. Otherwise it completes normally and then resolves
the promise.
function myCoolPromiseAPI(/* …, */ { signal }) {
return new Promise((resolve, reject) => {
// If the signal is already aborted, immediately throw in order to reject the promise.
if (signal.aborted) {
reject(signal.reason);
return;
}
// Perform the main purpose of the API
// Call resolve(result) when done.
// Watch for 'abort' signals
signal.addEventListener("abort", () => {
// Stop the main operation
// Reject the promise with the abort reason.
reject(signal.reason);
});
});
}
The API might then be used as shown. Note that `AbortController.abort()` is
called to abort the operation.
const controller = new AbortController();
const signal = controller.signal;
startSpinner();
myCoolPromiseAPI({ /* …, */ signal })
.then((result) => {})
.catch((err) => {
if (err.name === "AbortError") return;
showUserErrorMessage();
})
.then(() => stopSpinner());
controller.abort();
APIs that do not return promises might react in a similar manner. In some
cases it may make sense to absorb the signal.
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`AbortSignal` | 66 | 16 | 57 | 53 | 11.1 | 66 | 57 | 47 | 11.3 | 9.0 | 66
`abort_event` | 66 | 16 | 57 | 53 | 11.1 | 66 | 57 | 47 | 11.3 | 9.0 | 66
`abort_static` | 93 | 93 | 88 | 79 | 15 | 93 | 88 | 66 | 15 | 17.0 | 93
`aborted` | 66 | 16 | 57 | 53 | 11.1 | 66 | 57 | 47 | 11.3 | 9.0 | 66
`any_static` | 116 | 116 | 124 | 102 | 17.4 | 116 | 124 | 78 | 17.4 | 24.0 | 116
`reason` | 98 | 98 | 97 | 84 | 15.4 | 98 | 97 | 68 | 15.4 | 18.0 | 98
`throwIfAborted` | 100 | 100 | 97 | 86 | 15.4 | 100 | 97 | 69 | 15.4 | 19.0 | 100
`timeout_static` | 124103–124Always aborts with an `AbortError` on timeout, not a `TimeoutError`. | 124103–124Always aborts with an `AbortError` on timeout, not a `TimeoutError`. | 100 | 11089–110Always aborts with an `AbortError` on timeout, not a `TimeoutError`. | 16 | 124103–124Always aborts with an `AbortError` on timeout, not a `TimeoutError`. | 100 | 8271–82Always aborts with an `AbortError` on timeout, not a `TimeoutError`. | 16 | 27.020.0–27.0Always aborts with an `AbortError` on timeout, not a `TimeoutError`. | 124103–124Always aborts with an `AbortError` on timeout, not a `TimeoutError`.
## See also
* Fetch API
* Abortable Fetch by Jake Archibald
# AbortSignal: abort event
Baseline Widely available
This feature is well established and works across many devices and browser
versions. It’s been available across browsers since April 2018.
* Learn more
* See full compatibility
* Report feedback
**Note:** This feature is available in Web Workers.
The `abort` event of the `AbortSignal` is fired when the associated request is
aborted, i.e., using `AbortController.abort()`.
## Syntax
Use the event name in methods like `addEventListener()`, or set an event
handler property.
addEventListener("abort", (event) => { })
onabort = (event) => { }
## Event type
A generic `Event` with no added properties.
## Examples
In the following snippets, we create a new `AbortController` object, and get
its `AbortSignal` (available using the `signal` property). Later on we check
whether or not the signal has been aborted using an event handler property,
You can detect the `abort` event using an `addEventListener` method:
const controller = new AbortController();
const signal = controller.signal;
signal.addEventListener("abort", () => {
console.log("Request aborted");
});
Or use the `onabort` event handler property:
const controller = new AbortController();
const signal = controller.signal;
signal.onabort = () => {
console.log("Request aborted");
};
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`abort_event` | 66 | 16 | 57 | 53 | 11.1 | 66 | 57 | 47 | 11.3 | 9.0 | 66
# AbortSignal: abort() static method
Baseline Widely available
This feature is well established and works across many devices and browser
versions. It’s been available across browsers since September 2021.
* Learn more
* See full compatibility
* Report feedback
**Note:** This feature is available in Web Workers.
The `AbortSignal.abort()` static method returns an `AbortSignal` that is
already set as aborted (and which does not trigger an `abort` event).
This is shorthand for the following code:
const controller = new AbortController();
controller.abort();
return controller.signal;
This could, for example, be passed to a fetch method in order to run its abort
logic (i.e., it may be that code is organized such that the abort logic should
be run even if the intended fetch operation has not been started).
**Note:** The method is similar in purpose to `Promise.reject`.
## Syntax
AbortSignal.abort()
AbortSignal.abort(reason)
### Parameters
`reason`
The reason why the operation was aborted, which can be any JavaScript value.
If not specified, the reason is set to "AbortError" `DOMException`.
### Return value
An `AbortSignal` instance with the `AbortSignal.aborted` property set to
`true`, and `AbortSignal.reason` set to the specified or default reason value.
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`abort_static` | 93 | 93 | 88 | 79 | 15 | 93 | 88 | 66 | 15 | 17.0 | 93
`reason_parameter` | 98 | 98 | 97 | 84 | 15.4 | 98 | 97 | 68 | 15.4 | 18.0 | 98
# AbortSignal: aborted property
Baseline Widely available
This feature is well established and works across many devices and browser
versions. It’s been available across browsers since April 2018.
* Learn more
* See full compatibility
* Report feedback
**Note:** This feature is available in Web Workers.
The `aborted` read-only property returns a value that indicates whether the
asynchronous operations the signal is communicating with are aborted (`true`)
or not (`false`).
## Value
`true` (aborted) or `false`
## Examples
In the following snippet, we create a new `AbortController` object, and get
its `AbortSignal` (available using the `signal` property). Later on, using the
`aborted` property, we check whether or not the signal has been aborted, and
send an appropriate log to the console.
const controller = new AbortController();
const signal = controller.signal;
// …
if (signal.aborted) {
console.log("Request has been aborted");
} else {
console.log("Request not aborted");
}
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`aborted` | 66 | 16 | 57 | 53 | 11.1 | 66 | 57 | 47 | 11.3 | 9.0 | 66
## See also
* Fetch API
# AbortSignal: any() static method
Baseline 2024
Newly available
Since March 2024, 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
**Note:** This feature is available in Web Workers.
The `AbortSignal.any()` static method takes an iterable of abort signals and
returns an `AbortSignal`. The returned abort signal is aborted when any of the
input iterable abort signals are aborted. The abort reason will be set to the
reason of the first signal that is aborted. If any of the given abort signals
are already aborted then so will be the returned `AbortSignal`.
## Syntax
AbortSignal.any(iterable)
### Parameters
`iterable`
An iterable (such as an `Array`) of abort signals.
### Return value
A `AbortSignal` that is:
* **Already aborted** , if any of the abort signals given is already aborted. The returned `AbortSignal`'s reason will be already set to the `reason` of the first abort signal that was already aborted.
* **Asynchronously aborted** , when any abort signal in `iterable` aborts. The `reason` will be set to the reason of the first abort signal that is aborted.
## Examples
### Using `AbortSignal.any()`
This example demonstrates combining both a signal from an `AbortController`,
and a timeout signal from `AbortSignal.timeout`.
const cancelDownloadButton = document.getElementById("cancelDownloadButton");
const userCancelController = new AbortController();
cancelDownloadButton.addEventListener("click", () => {
userCancelController.abort();
});
// Timeout after 5 minutes
const timeoutSignal = AbortSignal.timeout(1_000 * 60 * 5);
// This signal will abort when either the user clicks the cancel button or 5 minutes is up
// whichever is sooner
const combinedSignal = AbortSignal.any([
userCancelController.signal,
timeoutSignal,
]);
try {
const res = await fetch(someUrlToDownload, {
// Stop the fetch when any of the signals aborts
signal: combinedSignal,
});
const body = await res.blob();
// Do something with downloaded content:
// …
} catch (e) {
if (e.name === "AbortError") {
// Cancelled by the user
} else if (e.name === "TimeoutError") {
// Show user that download timed out
} else {
// Other error, e.g. network error
}
}
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`any_static` | 116 | 116 | 124 | 102 | 17.4 | 116 | 124 | 78 | 17.4 | 24.0 | 116
# AbortSignal: reason property
Baseline Widely available
This feature is well established and works across many devices and browser
versions. It’s been available across browsers since March 2022.
* Learn more
* See full compatibility
* Report feedback
**Note:** This feature is available in Web Workers.
The `reason` read-only property returns a JavaScript value that indicates the
abort reason.
The property is `undefined` when the signal has not been aborted. It can be
set to a specific value when the signal is aborted, using
`AbortController.abort()` or `AbortSignal.abort()`. If not explicitly set in
those methods, it defaults to "AbortError" `DOMException`.
## Value
A JavaScript value that indicates the abort reason, or `undefined`, if not
aborted.
## Examples
In the following snippet, we create a new `AbortController` object, and get
its `AbortSignal` (available using the `signal` property). Later on, using the
`aborted` property, we check whether or not the signal has been aborted, and
log the abort status and reason to the console.
const controller = new AbortController();
const signal = controller.signal;
// …
if (signal.aborted) {
if (signal.reason) {
console.log(`Request aborted with reason: ${signal.reason}`);
} else {
console.log("Request aborted but no reason was given.");
}
} else {
console.log("Request not aborted");
}
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`reason` | 98 | 98 | 97 | 84 | 15.4 | 98 | 97 | 68 | 15.4 | 18.0 | 98
## See also
* Fetch API
# AbortSignal: throwIfAborted() method
Baseline Widely available
This feature is well established and works across many devices and browser
versions. It’s been available across browsers since April 2022.
* Learn more
* See full compatibility
* Report feedback
**Note:** This feature is available in Web Workers.
The `throwIfAborted()` method throws the signal's abort `reason` if the signal
has been aborted; otherwise it does nothing.
An API that needs to support aborting can accept an `AbortSignal` object and
use `throwIfAborted()` to test and throw when the `abort` event is signalled.
This method can also be used to abort operations at particular points in code,
rather than passing to functions that take a signal.
## Syntax
throwIfAborted()
### Parameters
None.
### Return value
None (`undefined`).
## Examples
The examples below come from the specification.
### Aborting a polling operation
This example demonstrates how you can use `throwIfAborted()` to abort a
polling operation.
Consider an asynchronous `waitForCondition()` function that is called with
another asynchronous function `func`, a target value `targetValue`, and an
`AbortSignal`. The method compares the result of `func` with `targetValue` in
a loop, returning when they match.
async function waitForCondition(func, targetValue, { signal } = {}) {
while (true) {
signal?.throwIfAborted();
const result = await func();
if (result === targetValue) {
return;
}
}
}
On each iteration of the loop, we use `throwIfAborted()` to throw the signal's
`reason` if the operation has been aborted (and otherwise do nothing). If the
signal is aborted, this will cause the `waitForCondition()` promise to be
rejected.
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`throwIfAborted` | 100 | 100 | 97 | 86 | 15.4 | 100 | 97 | 69 | 15.4 | 19.0 | 100
## See also
* Fetch API
# AbortSignal: timeout() static method
Baseline 2024
Newly available
Since April 2024, 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
**Note:** This feature is available in Web Workers.
The `AbortSignal.timeout()` static method returns an `AbortSignal` that will
automatically abort after a specified time.
The signal aborts with a `TimeoutError` `DOMException` on timeout.
The timeout is based on active rather than elapsed time, and will effectively
be paused if the code is running in a suspended worker, or while the document
is in a back-forward cache ("bfcache").
To combine multiple signals, you can use `AbortSignal.any()`, for example, to
directly abort a download using either a timeout signal or by calling
`AbortController.abort()`.
## Syntax
AbortSignal.timeout(time)
### Parameters
`time`
The "active" time in milliseconds before the returned `AbortSignal` will
abort. The value must be within range of 0 and `Number.MAX_SAFE_INTEGER`.
### Return value
An `AbortSignal`.
The signal will abort with its `AbortSignal.reason` property set to a
`TimeoutError` `DOMException` on timeout, or an `AbortError` `DOMException` if
the operation was user-triggered.
## Examples
Below is an example showing a fetch operation that will timeout if
unsuccessful after 5 seconds. Note that this may also fail if the method is
not supported, if a browser "stop" button is pressed, or for another reason.
const url = "https://path_to_large_file.mp4";
try {
const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
const result = await res.blob();
// …
} catch (err) {
if (err.name === "TimeoutError") {
// This exception is from the abort signal
console.error("Timeout: It took more than 5 seconds to get the result!");
} else if (err.name === "AbortError") {
// This exception is from the fetch itself
console.error(
"Fetch aborted by user action (browser stop button, closing tab, etc.",
);
} else if (err.name === "TypeError") {
console.error("AbortSignal.timeout() method is not supported");
} else {
// A network error, or some other problem.
console.error(`Error: type: ${err.name}, message: ${err.message}`);
}
}
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`timeout_static` | 124103–124Always aborts with an `AbortError` on timeout, not a `TimeoutError`. | 124103–124Always aborts with an `AbortError` on timeout, not a `TimeoutError`. | 100 | 11089–110Always aborts with an `AbortError` on timeout, not a `TimeoutError`. | 16 | 124103–124Always aborts with an `AbortError` on timeout, not a `TimeoutError`. | 100 | 8271–82Always aborts with an `AbortError` on timeout, not a `TimeoutError`. | 16 | 27.020.0–27.0Always aborts with an `AbortError` on timeout, not a `TimeoutError`. | 124103–124Always aborts with an `AbortError` on timeout, not a `TimeoutError`.
# AbsoluteOrientationSensor
Limited availability
This feature is not Baseline because it does not work in some of the most
widely-used browsers.
* Learn more
* See full compatibility
* Report feedback
**Secure context:** This feature is available only in secure contexts (HTTPS),
in some or all supporting browsers.
The `AbsoluteOrientationSensor` interface of the Sensor APIs describes the
device's physical orientation in relation to the Earth's reference coordinate
system.
To use this sensor, the user must grant permission to the `'accelerometer'`,
`'gyroscope'`, and `'magnetometer'` device sensors through the Permissions
API.
This feature may be blocked by a Permissions Policy set on your server.
EventTarget Sensor OrientationSensor AbsoluteOrientationSensor
## Constructor
`AbsoluteOrientationSensor()`
Creates a new `AbsoluteOrientationSensor` object.
## Instance properties
_No specific properties; inherits properties from its
ancestors`OrientationSensor` and `Sensor`._
## Instance methods
_No specific methods; inherits methods from its ancestors`OrientationSensor`
and `Sensor`._
## Events
_No specific events; inherits methods from its ancestor,`Sensor`._
## Examples
### Basic Example
The following example, which is loosely based on Intel's Orientation Phone
demo, instantiates an `AbsoluteOrientationSensor` with a frequency of 60 times
a second. On each reading it uses `OrientationSensor.quaternion` to rotate a
visual model of a phone.
const options = { frequency: 60, referenceFrame: "device" };
const sensor = new AbsoluteOrientationSensor(options);
sensor.addEventListener("reading", () => {
// model is a Three.js object instantiated elsewhere.
model.quaternion.fromArray(sensor.quaternion).inverse();
});
sensor.addEventListener("error", (event) => {
if (event.error.name === "NotReadableError") {
console.log("Sensor is not available.");
}
});
sensor.start();
### Permissions Example
Using orientation sensors requires requesting permissions for multiple device
sensors. Because the `Permissions` interface uses promises, a good way to
request permissions is to use `Promise.all`.
const sensor = new AbsoluteOrientationSensor();
Promise.all([
navigator.permissions.query({ name: "accelerometer" }),
navigator.permissions.query({ name: "magnetometer" }),
navigator.permissions.query({ name: "gyroscope" }),
]).then((results) => {
if (results.every((result) => result.state === "granted")) {
sensor.start();
// …
} else {
console.log("No permissions to use AbsoluteOrientationSensor.");
}
});
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`AbsoluteOrientationSensor` | 67 | 79 | No | 54 | No | 67 | No | 48 | No | 9.0 | 67
`AbsoluteOrientationSensor` | 67 | 79 | No | 54 | No | 67 | No | 48 | No | 9.0 | 67
# AbsoluteOrientationSensor: AbsoluteOrientationSensor() constructor
Limited availability
This feature is not Baseline because it does not work in some of the most
widely-used browsers.
* Learn more
* See full compatibility
* Report feedback
**Secure context:** This feature is available only in secure contexts (HTTPS),
in some or all supporting browsers.
The `AbsoluteOrientationSensor()` constructor creates a new
`AbsoluteOrientationSensor` object which describes the device's physical
orientation in relation to the Earth's reference coordinate system.
## Syntax
new AbsoluteOrientationSensor()
new AbsoluteOrientationSensor(options)
### Parameters
`options` Optional
Options are as follows:
`frequency` Optional
The desired number of times per second a sample should be taken, meaning the
number of times per second that the `reading` event will be called. A whole
number or decimal may be used, the latter for frequencies less than a second.
The actual reading frequency depends on the device hardware and consequently
may be less than requested.
`referenceFrame` Optional
Either `'device'` or `'screen'`. The default is `'device'`.
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`AbsoluteOrientationSensor` | 67 | 79 | No | 54 | No | 67 | No | 48 | No | 9.0 | 67
## See also
* `reading` event
# AbstractRange
Baseline Widely available
This feature is well established and works across many devices and browser
versions. It’s been available across browsers since April 2021.
* Learn more
* See full compatibility
* Report feedback
The `AbstractRange` abstract interface is the base class upon which all DOM
range types are defined. A **range** is an object that indicates the start and
end points of a section of content within the document.
**Note:** As an abstract interface, you will not directly instantiate an
object of type `AbstractRange`. Instead, you will use the `Range` or
`StaticRange` interfaces. To understand the difference between those two
interfaces, and how to choose which is appropriate for your needs, consult
each interface's documentation.
## Instance properties
`collapsed` Read only
A Boolean value which is `true` if the range is _collapsed_. A collapsed range
is a range whose start position and end position are the same, resulting in a
zero-character-long range.
`endContainer` Read only
The `Node` object in which the end of the range, as specified by the
`endOffset` property, is located.
`endOffset` Read only
An integer value indicating the offset, in characters, from the beginning of
the node's contents to the last character of the range represented by the
range object. This value must be less than the length of the `endContainer`
node.
`startContainer` Read only
The DOM `Node` in which the beginning of the range, as specified by the
`startOffset` property, is located.
`startOffset` Read only
An integer value indicating the offset, in characters, from the beginning of
the node's contents to the first character of the contents referred to by the
range object. This value must be less than the length of the node indicated in
`startContainer`.
## Instance methods
_The`AbstractRange` interface doesn't provide any methods._
## Usage notes
### Range types
All ranges of content within a `document` are described using instances of
interfaces based on `AbstractRange`. There are two such interfaces:
`Range`
The `Range` interface has been around for a long time and has only recently
been redefined to be based upon `AbstractRange` as the need arose to define
other forms of range data. `Range` provides methods that allow you to alter
the range's endpoints, as well as methods to compare ranges, detect
intersections between ranges, and so forth.
`StaticRange`
A `StaticRange` is a basic range which cannot be changed once it's been
created. Specifically, as the node tree mutates and changes, the range does
not. This is useful when you need to specify a range that will only be used
once, since it avoids the performance and resource impact of the more complex
`Range` interface.
### Contents of elements
When trying to access the contents of an element, keep in mind that the
element itself is a node, but so is any text inside it. In order to set a
range endpoint within the text of an element, be sure to find the text node
inside the element:
const startElem = document.querySelector("p");
const endElem = startElem.querySelector("span");
const range = document.createRange();
range.setStart(startElem, 0);
range.setEnd(endElem, endElem.childNodes[0].length / 2);
const contents = range.cloneContents();
document.body.appendChild(contents);
This example creates a new range, `range`, and sets its starting point to the
third child node of the first element. The end point is set to be the middle
of the first child of the span, and then the range is used to copy the
contents of the range.
### Ranges and the hierarchy of the DOM
In order to define a range of characters within a document in a way that is
able to span across zero or more node boundaries, and which is as resilient as
possible to changes to the DOM, you can't specify the offset to the first and
last characters in the HTML. There are a few good reasons for that.
First, after your page is loaded, the browser isn't thinking in terms of HTML.
Once it's been loaded, the page is a tree of DOM `Node` objects, so you need
to specify the beginning and ending locations of a range in terms of nodes and
positions within nodes.
Second, in order to support the mutability of the DOM tree as much as
possible, you need a way to represent positions relative to nodes in the tree,
rather than global positions within the entire document. By defining points
within the document as offsets within a given node, those positions remain
consistent with the content even as nodes are added to, removed from, or moved
around within the DOM tree—within reason. There are fairly obvious limitations
(such as if a node is moved to be after the endpoint of a range, or if the
content of a node is heavily altered), but it's far better than nothing.
Third, using node-relative positions to define the start and end positions
will generally be easier to make perform well. Rather than having to negotiate
the DOM figuring out what your global offset refers to, the user agent
(browser) can instead go directly to the node indicated by the starting
position and start from there, working its way forward until it reaches the
given offset into the ending node.
To illustrate this, consider the HTML below:
The Ultimate Website
Section 1: An interesting thing…
A very interesting thing happened on the way to the forum…
After loading the HTML and constructing the DOM representation of the
document, the resulting DOM tree looks like this:
In this diagram, the nodes representing HTML elements are shown in green. Each
row beneath them shows the next layer of depth into the DOM tree. Blue nodes
are text nodes, containing the text that gets shown onscreen. Each element's
contents are linked below it in the tree, potentially spawning a series of
branches below as elements include other elements and text nodes.
If you want to create a range that incorporates the contents of the `
`
element whose contents are `"A very interesting thing happened on the
way to the forum…"`, you can do so like this:
const pRange = document.createRange();
pRange.selectNodeContents(document.querySelector("#entry1 p"));
Since we wish to select the entire contents of the `
` element, including
its descendants, this works perfectly.
If we wish to instead copy the text "An interesting thing…" from the
``'s heading (an h2 element) through the end of the letters "ve" in
the `` within the paragraph below it, the following code would work:
const range = document.createRange();
const startNode = document.querySelector("section h2").childNodes[0];
range.setStart(startNode, 11);
const endNode = document.querySelector("#entry1 p em").childNodes[0];
range.setEnd(endNode, 2);
const fragment = range.cloneContents();
Here an interesting problem arises—we are capturing content from multiple
nodes located at different levels of the DOM hierarchy, and then only part of
one of them. What should the result look like?
As it turns out, the DOM specification fortunately addresses this exact issue.
For example, in this case, we're calling `cloneContents()` on the range to
create a new `DocumentFragment` object providing a DOM subtree which
replicates the contents of the specified range. To do this, `cloneContents()`
constructs all the nodes needed to preserve the structure of the indicated
range, but no more than necessary.
In this example, the start of the specified range is found within the text
node below the section's heading, which means that the new `DocumentFragment`
will need to contain an h2 and, below it, a text node.
The range's end is located below the `
` element, so that will be needed
within the new fragment. So will the text node containing the word "A", since
that's included in the range. Finally, an `` and a text node below it will
be added below the `
` as well.
The contents of the text nodes are then determined by the offsets into those
text nodes given when calling `setStart()` and `setEnd()`. Given the offset of
11 into the heading's text, that node will contain "An interesting thing…".
Similarly, the last text node will contain "ve", given the request for the
first two characters of the ending node.
The resulting document fragment looks like this:
Notice especially that the contents of this fragment are all _below_ the
shared common parent of the topmost nodes within it. The parent `` is
not needed to replicate the cloned content, so it isn't included.
## Example
Consider this simple HTML fragment of HTML.
This is a paragraph.
Imagine using a `Range` to extract the word "paragraph" from this. The code to
do that looks like the following:
const paraNode = document.querySelector("p");
const paraTextNode = paraNode.childNodes[1];
const range = document.createRange();
range.setStart(paraTextNode, 6);
range.setEnd(paraTextNode, paraTextNode.length - 1);
const fragment = range.cloneContents();
document.body.appendChild(fragment);
First we get references to the paragraph node itself as well as to the
_second_ child node within the paragraph. The first child is the ``
element. The second child is the text node " is a paragraph.".
With the text node reference in hand, we create a new `Range` object by
calling `createRange()` on the `Document` itself. We set the starting position
of the range to the sixth character of the text node's string, and the end
position to the length of the text node's string minus one. This sets the
range to encompass the word "paragraph".
We then finish up by calling `cloneContents()` on the `Range` to create a new
`DocumentFragment` object which contains the portion of the document
encompassed by the range. After that, we use `appendChild()` to add that
fragment at the end of the document's body, as obtained from `document.body`.
The result looks like this:
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`AbstractRange` | 90 | 9018–79 | 69 | 76 | 14.1 | 90 | 79 | 64 | 14.5 | 15.0 | 90
`collapsed` | 90 | 9018–79 | 69 | 76 | 14.1 | 90 | 79 | 64 | 14.5 | 15.0 | 90
`endContainer` | 90 | 9018–79 | 69 | 76 | 14.1 | 90 | 79 | 64 | 14.5 | 15.0 | 90
`endOffset` | 90 | 9018–79 | 69 | 76 | 14.1 | 90 | 79 | 64 | 14.5 | 15.0 | 90
`startContainer` | 90 | 9018–79 | 69 | 76 | 14.1 | 90 | 79 | 64 | 14.5 | 15.0 | 90
`startOffset` | 90 | 9018–79 | 69 | 76 | 14.1 | 90 | 79 | 64 | 14.5 | 15.0 | 90
# AbstractRange: collapsed property
Baseline Widely available
This feature is well established and works across many devices and browser
versions. It’s been available across browsers since April 2021.
* Learn more
* See full compatibility
* Report feedback
The read-only `collapsed` property of the `AbstractRange` interface returns
`true` if the range's start position and end position are the same.
## Value
A boolean value which is `true` if the range is _collapsed_. A collapsed range
is one in which the start and end positions are the same, resulting in a zero-
character-long range.
## Example
let isCollapsed = range.collapsed;
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`collapsed` | 90 | 9018–79 | 69 | 76 | 14.1 | 90 | 79 | 64 | 14.5 | 15.0 | 90
# AbstractRange: endContainer property
Baseline Widely available
This feature is well established and works across many devices and browser
versions. It’s been available across browsers since April 2021.
* Learn more
* See full compatibility
* Report feedback
The read-only `endContainer` property of the `AbstractRange` interface returns
the `Node` in which the end of the range is located.
## Value
The `Node` which contains the last character of the range.
## Example
let endNode = range.endContainer;
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`endContainer` | 90 | 9018–79 | 69 | 76 | 14.1 | 90 | 79 | 64 | 14.5 | 15.0 | 90
# AbstractRange: endOffset property
Baseline Widely available
This feature is well established and works across many devices and browser
versions. It’s been available across browsers since April 2021.
* Learn more
* See full compatibility
* Report feedback
The `endOffset` property of the `AbstractRange` interface returns the offset
into the end node of the range's end position.
## Value
An integer value indicating the number of characters into the `Node` indicated
by `endContainer` at which the final character of the range is located.
## Example
let endOffset = range.endOffset;
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`endOffset` | 90 | 9018–79 | 69 | 76 | 14.1 | 90 | 79 | 64 | 14.5 | 15.0 | 90
# AbstractRange: startContainer property
Baseline Widely available
This feature is well established and works across many devices and browser
versions. It’s been available across browsers since April 2021.
* Learn more
* See full compatibility
* Report feedback
The read-only `startContainer` property of the `AbstractRange` interface
returns the start `Node` for the range.
## Value
The `Node` inside which the start position of the range is found.
## Example
let startNode = range.startContainer;
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`startContainer` | 90 | 9018–79 | 69 | 76 | 14.1 | 90 | 79 | 64 | 14.5 | 15.0 | 90
# AbstractRange: startOffset property
Baseline Widely available
This feature is well established and works across many devices and browser
versions. It’s been available across browsers since April 2021.
* Learn more
* See full compatibility
* Report feedback
The read-only `startOffset` property of the `AbstractRange` interface returns
the offset into the start node of the range's start position.
## Value
An integer value indicating the number of characters into the `Node` indicated
by `startContainer` at which the first character of the range is located.
## Example
let startOffset = range.startOffset;
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`startOffset` | 90 | 9018–79 | 69 | 76 | 14.1 | 90 | 79 | 64 | 14.5 | 15.0 | 90
# Accelerometer
Limited availability
This feature is not Baseline because it does not work in some of the most
widely-used browsers.
* Learn more
* See full compatibility
* Report feedback
**Secure context:** This feature is available only in secure contexts (HTTPS),
in some or all supporting browsers.
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in
production.
The `Accelerometer` interface of the Sensor APIs provides on each reading the
acceleration applied to the device along all three axes.
To use this sensor, the user must grant permission to the `'accelerometer'`,
device sensor through the Permissions API.
This feature may be blocked by a Permissions Policy set on your server.
EventTarget Sensor Accelerometer
## Constructor
`Accelerometer()` Experimental
Creates a new `Accelerometer` object.
## Instance properties
_In addition to the properties listed below,`Accelerometer` inherits
properties from its parent interfaces, `Sensor` and `EventTarget`._
`Accelerometer.x` Read only Experimental
Returns a double containing the acceleration of the device along the device's
x axis.
`Accelerometer.y` Read only Experimental
Returns a double containing the acceleration of the device along the device's
y axis.
`Accelerometer.z` Read only Experimental
Returns a double containing the acceleration of the device along the device's
z axis.
## Instance methods
_`Accelerometer` doesn't have own methods. However, it inherits methods from
its parent interfaces, `Sensor` and `EventTarget`._
## Events
_`Accelerometer` doesn't have own events. However, it inherits events from its
parent interface, `Sensor`._
## Example
Acceleration is typically read in the `reading` event callback. In the example
below this occurs sixty times a second.
const acl = new Accelerometer({ frequency: 60 });
acl.addEventListener("reading", () => {
console.log(`Acceleration along the X-axis ${acl.x}`);
console.log(`Acceleration along the Y-axis ${acl.y}`);
console.log(`Acceleration along the Z-axis ${acl.z}`);
});
acl.start();
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`Accelerometer` | 67 | 79 | No | 54 | No | 67 | No | 48 | No | 9.0 | 67
`Accelerometer` | 67 | 79 | No | 54 | No | 67 | No | 48 | No | 9.0 | 67
`x` | 67 | 79 | No | 54 | No | 67 | No | 48 | No | 9.0 | 67
`y` | 67 | 79 | No | 54 | No | 67 | No | 48 | No | 9.0 | 67
`z` | 67 | 79 | No | 54 | No | 67 | No | 48 | No | 9.0 | 67
# Accelerometer: Accelerometer() constructor
Limited availability
This feature is not Baseline because it does not work in some of the most
widely-used browsers.
* Learn more
* See full compatibility
* Report feedback
**Secure context:** This feature is available only in secure contexts (HTTPS),
in some or all supporting browsers.
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in
production.
The `Accelerometer()` constructor creates a new `Accelerometer` object which
returns the acceleration of the device along all three axes at the time it is
read.
## Syntax
new Accelerometer()
new Accelerometer(options)
### Parameters
`options` Optional
Options are as follows:
`frequency` Optional
The desired number of times per second a sample should be taken, meaning the
number of times per second the `reading` event will be called. A whole number
or decimal may be used, the latter for frequencies less than a second. The
actual reading frequency depends on the device hardware and consequently may
be less than requested.
`referenceFrame` Optional
Either `'device'` or `'screen'`. The default is `'device'`.
### Exceptions
`SecurityError` `DOMException`
Use of this feature was blocked by a Permissions Policy.
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`Accelerometer` | 67 | 79 | No | 54 | No | 67 | No | 48 | No | 9.0 | 67
## See also
* `reading` event
# Accelerometer: x property
Limited availability
This feature is not Baseline because it does not work in some of the most
widely-used browsers.
* Learn more
* See full compatibility
* Report feedback
**Secure context:** This feature is available only in secure contexts (HTTPS),
in some or all supporting browsers.
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in
production.
The `x` read-only property of the `Accelerometer` interface returns a number
specifying the acceleration of the device along its x-axis.
## Value
A `Number`.
## Examples
Acceleration is typically read in the `reading` event callback. In the example
below this occurs sixty times a second.
const accelerometer = new Accelerometer({ frequency: 60 });
accelerometer.addEventListener("reading", (e) => {
console.log(`Acceleration along the X-axis ${accelerometer.x}`);
console.log(`Acceleration along the Y-axis ${accelerometer.y}`);
console.log(`Acceleration along the Z-axis ${accelerometer.z}`);
});
accelerometer.start();
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`x` | 67 | 79 | No | 54 | No | 67 | No | 48 | No | 9.0 | 67
# Accelerometer: y property
Limited availability
This feature is not Baseline because it does not work in some of the most
widely-used browsers.
* Learn more
* See full compatibility
* Report feedback
**Secure context:** This feature is available only in secure contexts (HTTPS),
in some or all supporting browsers.
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in
production.
The `y` read-only property of the `Accelerometer` interface returns a number
specifying the acceleration of the device along its y-axis.
## Value
A `Number`.
## Examples
Acceleration is typically read in the `reading` event callback. In the example
below this occurs sixty times a second.
const accelerometer = new Accelerometer({ frequency: 60 });
accelerometer.addEventListener("reading", (e) => {
console.log(`Acceleration along the X-axis ${accelerometer.x}`);
console.log(`Acceleration along the Y-axis ${accelerometer.y}`);
console.log(`Acceleration along the Z-axis ${accelerometer.z}`);
});
accelerometer.start();
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`y` | 67 | 79 | No | 54 | No | 67 | No | 48 | No | 9.0 | 67
# Accelerometer: z property
Limited availability
This feature is not Baseline because it does not work in some of the most
widely-used browsers.
* Learn more
* See full compatibility
* Report feedback
**Secure context:** This feature is available only in secure contexts (HTTPS),
in some or all supporting browsers.
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in
production.
The `z` read-only property of the `Accelerometer` interface returns a number
specifying the acceleration of the device along its z-axis.
## Value
A `Number`.
## Examples
Acceleration is typically read in the `reading` event callback. In the example
below this occurs sixty times a second.
const accelerometer = new Accelerometer({ frequency: 60 });
accelerometer.addEventListener("reading", (e) => {
console.log(`Acceleration along the X-axis ${accelerometer.x}`);
console.log(`Acceleration along the Y-axis ${accelerometer.y}`);
console.log(`Acceleration along the Z-axis ${accelerometer.z}`);
});
accelerometer.start();
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`z` | 67 | 79 | No | 54 | No | 67 | No | 48 | No | 9.0 | 67
# AesCbcParams
The `AesCbcParams` dictionary of the Web Crypto API represents the object that
should be passed as the `algorithm` parameter into `SubtleCrypto.encrypt()`,
`SubtleCrypto.decrypt()`, `SubtleCrypto.wrapKey()`, or
`SubtleCrypto.unwrapKey()`, when using the AES-CBC algorithm.
## Instance properties
`name`
A string. This should be set to `AES-CBC`.
`iv`
An `ArrayBuffer`, a `TypedArray`, or a `DataView`. The initialization vector.
Must be 16 bytes, unpredictable, and preferably cryptographically random.
However, it need not be secret (for example, it may be transmitted unencrypted
along with the ciphertext).
## Examples
See the examples for `SubtleCrypto.encrypt()` and `SubtleCrypto.decrypt()`.
## Specifications
## Browser compatibility
## See also
* CBC mode is defined in section 6.2 of the NIST SP800-38A standard.
* `SubtleCrypto.encrypt()`.
* `SubtleCrypto.decrypt()`.
* `SubtleCrypto.wrapKey()`.
* `SubtleCrypto.unwrapKey()`.
# AesCtrParams
The `AesCtrParams` dictionary of the Web Crypto API represents the object that
should be passed as the `algorithm` parameter into `SubtleCrypto.encrypt()`,
`SubtleCrypto.decrypt()`, `SubtleCrypto.wrapKey()`, or
`SubtleCrypto.unwrapKey()`, when using the AES-CTR algorithm.
AES is a block cipher, meaning that it splits the message into blocks and
encrypts it a block at a time. In CTR mode, every time a block of the message
is encrypted, an extra block of data is mixed in. This extra block is called
the "counter block".
A given counter block value must never be used more than once with the same
key:
* Given a message _n_ blocks long, a different counter block must be used for every block.
* If the same key is used to encrypt more than one message, a different counter block must be used for all blocks across all messages.
Typically this is achieved by splitting the initial counter block value into
two concatenated parts:
* A nonce (that is, a number that may only be used once). The nonce part of the block stays the same for every block in the message. Each time a new message is to be encrypted, a new nonce is chosen. Nonces don't have to be secret, but they must not be reused with the same key.
* A counter. This part of the block gets incremented each time a block is encrypted.
Essentially: the nonce should ensure that counter blocks are not reused from
one message to the next, while the counter should ensure that counter blocks
are not reused within a single message.
**Note:** See Appendix B of the NIST SP800-38A standard for more information.
## Instance properties
`name`
A string. This should be set to `AES-CTR`.
`counter`
An `ArrayBuffer`, a `TypedArray`, or a `DataView` — the initial value of the
counter block. This must be 16 bytes long (the AES block size). The rightmost
`length` bits of this block are used for the counter, and the rest is used for
the nonce. For example, if `length` is set to 64, then the first half of
`counter` is the nonce and the second half is used for the counter.
`length`
A `Number` — the number of bits in the counter block that are used for the
actual counter. The counter must be big enough that it doesn't wrap: if the
message is `n` blocks and the counter is `m` bits long, then the following
must be true: `n <= 2^m`. The NIST SP800-38A standard, which defines CTR,
suggests that the counter should occupy half of the counter block (see
Appendix B.2), so for AES it would be 64.
## Examples
See the examples for `SubtleCrypto.encrypt()` and `SubtleCrypto.decrypt()`.
## Specifications
## Browser compatibility
## See also
* CTR mode is defined in section 6.5 of the NIST SP800-38A standard.
* `SubtleCrypto.encrypt()`.
* `SubtleCrypto.decrypt()`.
* `SubtleCrypto.wrapKey()`.
* `SubtleCrypto.unwrapKey()`.
# AesGcmParams
The `AesGcmParams` dictionary of the Web Crypto API represents the object that
should be passed as the `algorithm` parameter into `SubtleCrypto.encrypt()`,
`SubtleCrypto.decrypt()`, `SubtleCrypto.wrapKey()`, or
`SubtleCrypto.unwrapKey()`, when using the AES-GCM algorithm.
For details of how to supply appropriate values for this parameter, see the
specification for AES-GCM: NIST SP800-38D, in particular section 5.2.1.1 on
Input Data.
## Instance properties
`name`
A string. This should be set to `AES-GCM`.
`iv`
An `ArrayBuffer`, a `TypedArray`, or a `DataView` with the initialization
vector. This must be unique for every encryption operation carried out with a
given key. Put another way: never reuse an IV with the same key. The AES-GCM
specification recommends that the IV should be 96 bits long, and typically
contains bits from a random number generator. Section 8.2 of the specification
outlines methods for constructing IVs. Note that the IV does not have to be
secret, just unique: so it is OK, for example, to transmit it in the clear
alongside the encrypted message.
`additionalData` Optional
An `ArrayBuffer`, a `TypedArray`, or a `DataView`. This contains additional
data that will not be encrypted but will be authenticated along with the
encrypted data. If `additionalData` is given here then the same data must be
given in the corresponding call to `decrypt()`: if the data given to the
`decrypt()` call does not match the original data, the decryption will throw
an exception. This gives you a way to authenticate associated data without
having to encrypt it.
The bit length of `additionalData` must be smaller than `2^64 - 1`.
The `additionalData` property is optional and may be omitted without
compromising the security of the encryption operation.
`tagLength` Optional
A `Number`. This determines the size in bits of the authentication tag
generated in the encryption operation and used for authentication in the
corresponding decryption.
The Web Crypto API specification requires this to have one of the following
values: 32, 64, 96, 104, 112, 120, or 128. On the other hand, the AES-GCM
specification recommends that it should be 96, 104, 112, 120, or 128, although
32 or 64 bits may be acceptable in some applications. For additional guidance,
see Appendix C of the NIST Publication on "Recommendation for Block Cipher
Modes of Operation".
`tagLength` is optional and defaults to 128 if it is not specified.
## Examples
See the examples for `SubtleCrypto.encrypt()` and `SubtleCrypto.decrypt()`.
## Specifications
## Browser compatibility
## See also
* `SubtleCrypto.encrypt()`.
* `SubtleCrypto.decrypt()`.
* `SubtleCrypto.wrapKey()`.
* `SubtleCrypto.unwrapKey()`.
# AesKeyGenParams
The `AesKeyGenParams` dictionary of the Web Crypto API represents the object
that should be passed as the `algorithm` parameter into
`SubtleCrypto.generateKey()`, when generating an AES key: that is, when the
algorithm is identified as any of AES-CBC, AES-CTR, AES-GCM, or AES-KW.
## Instance properties
`name`
A string. This should be set to `AES-CBC`, `AES-CTR`, `AES-GCM`, or `AES-KW`,
depending on the algorithm you want to use.
`length`
A `Number` — the length in bits of the key to generate. This must be one of:
128, 192, or 256.
## Examples
See the examples for `SubtleCrypto.generateKey()`.
## Specifications
## Browser compatibility
## See also
* `SubtleCrypto.generateKey()`.
# AmbientLightSensor
Limited availability
This feature is not Baseline because it does not work in some of the most
widely-used browsers.
* Learn more
* See full compatibility
* Report feedback
**Secure context:** This feature is available only in secure contexts (HTTPS),
in some or all supporting browsers.
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in
production.
The `AmbientLightSensor` interface of the Sensor APIs returns the current
light level or illuminance of the ambient light around the hosting device.
To use this sensor, the user must grant permission to the `'ambient-light-
sensor'` device sensor through the Permissions API.
This feature may be blocked by a Permissions Policy set on your server.
EventTarget Sensor AmbientLightSensor
## Constructor
`AmbientLightSensor()` Experimental
Creates a new `AmbientLightSensor` object.
## Instance properties
`AmbientLightSensor.illuminance` Read only Experimental
Returns the current light level in lux of the ambient light level around the
hosting device.
## Instance methods
_`AmbientLightSensor` doesn't have own methods. However, it inherits methods
from its parent interfaces, `Sensor` and `EventTarget`._
## Events
_`AmbientLightSensor` doesn't have own events. However, it inherits events
from its parent interface, `Sensor`._
## Example
if ("AmbientLightSensor" in window) {
const sensor = new AmbientLightSensor();
sensor.addEventListener("reading", (event) => {
console.log("Current light level:", sensor.illuminance);
});
sensor.addEventListener("error", (event) => {
console.log(event.error.name, event.error.message);
});
sensor.start();
}
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`AmbientLightSensor` | 6756 | 7979 | No | 5443 | No | 6756 | No | No | No | No | No
`AmbientLightSensor` | 6756 | 7979 | No | 5443 | No | 6756 | No | No | No | No | No
`illuminance` | 67In Chrome 79, this method stopped returning floats and returned integers to avoid fingerprinting.56In Chrome 79, this method stopped returning floats and returned integers to avoid fingerprinting. | 79In Edge 79, this method stopped returning floats and returned integers to avoid fingerprinting.79In Edge 79, this method stopped returning floats and returned integers to avoid fingerprinting. | No | 54In Opera 66, this method stopped returning floats and returned integers to avoid fingerprinting.43In Opera 66, this method stopped returning floats and returned integers to avoid fingerprinting. | No | 67In Chrome Android 79, this method stopped returning floats and returned integers to avoid fingerprinting.56In Chrome Android 79, this method stopped returning floats and returned integers to avoid fingerprinting. | No | No | No | No | No
# AmbientLightSensor: AmbientLightSensor() constructor
Limited availability
This feature is not Baseline because it does not work in some of the most
widely-used browsers.
* Learn more
* See full compatibility
* Report feedback
**Secure context:** This feature is available only in secure contexts (HTTPS),
in some or all supporting browsers.
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in
production.
The `AmbientLightSensor()` constructor creates a new `AmbientLightSensor`
object, which returns the current light level or illuminance of the ambient
light around the hosting device.
## Syntax
new AmbientLightSensor()
new AmbientLightSensor(options)
### Parameters
`options` Optional
Currently only one option is supported:
`frequency` Optional
The desired number of times per second a sample should be taken, meaning the
number of times per second that `reading` event will be called. A whole number
or decimal may be used, the latter for frequencies less than a second. The
actual reading frequency depends on the device hardware and consequently may
be less than requested.
### Exceptions
`SecurityError` `DOMException`
Use of this feature was blocked by a Permissions Policy.
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`AmbientLightSensor` | 6756 | 7979 | No | 5443 | No | 6756 | No | No | No | No | No
## See also
* `reading` event
# AmbientLightSensor: illuminance property
Limited availability
This feature is not Baseline because it does not work in some of the most
widely-used browsers.
* Learn more
* See full compatibility
* Report feedback
**Secure context:** This feature is available only in secure contexts (HTTPS),
in some or all supporting browsers.
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in
production.
The `illuminance` read-only property of the `AmbientLightSensor` interface
returns the current light level in lux of the ambient light level around the
hosting device.
## Value
A `Number` indicating the current light level in lux.
## Examples
if ("AmbientLightSensor" in window) {
const sensor = new AmbientLightSensor();
sensor.addEventListener("reading", (event) => {
console.log("Current light level:", sensor.illuminance);
});
sensor.addEventListener("error", (event) => {
console.log(event.error.name, event.error.message);
});
sensor.start();
}
## Specifications
## Browser compatibility
| Desktop | Mobile
---|---|---
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android
`illuminance` | 67In Chrome 79, this method stopped returning floats and returned integers to avoid fingerprinting.56In Chrome 79, this method stopped returning floats and returned integers to avoid fingerprinting. | 79In Edge 79, this method stopped returning floats and returned integers to avoid fingerprinting.79In Edge 79, this method stopped returning floats and returned integers to avoid fingerprinting. | No | 54In Opera 66, this method stopped returning floats and returned integers to avoid fingerprinting.43In Opera 66, this method stopped returning floats and returned integers to avoid fingerprinting. | No | 67In Chrome Android 79, this method stopped returning floats and returned integers to avoid fingerprinting.56In Chrome Android 79, this method stopped returning floats and returned integers to avoid fingerprinting. | No | No | No | No | No
# AnalyserNode
Baseline Widely available
This feature is well established and works across many devices and browser
versions. It’s been available across browsers since July 2015.
* Learn more
* See full compatibility
* Report feedback
The `AnalyserNode` interface represents a node able to provide real-time
frequency and time-domain analysis information. It is an `AudioNode` that
passes the audio stream unchanged from the input to the output, but allows you
to take the generated data, process it, and create audio visualizations.
An `AnalyserNode` has exactly one input and one output. The node works even if
the output is not connected.
EventTarget AudioNode AnalyserNode
Number of inputs | `1`
---|---
Number of outputs | `1` (but may be left unconnected)
Channel count mode | `"max"`
Channel count | `2`
Channel interpretation | `"speakers"`
## Constructor
`AnalyserNode()`
Creates a new instance of an `AnalyserNode` object.
## Instance properties
_Inherits properties from its parent,`AudioNode`_.
`AnalyserNode.fftSize`
An unsigned long value representing the size of the FFT (Fast Fourier
Transform) to be used to determine the frequency domain.
`AnalyserNode.frequencyBinCount` Read only
An unsigned long value half that of the FFT size. This generally equates to
the number of data values you will have to play with for the visualization.
`AnalyserNode.minDecibels`
A double value representing the minimum power value in the scaling range for
the FFT analysis data, for conversion to unsigned byte values — basically,
this specifies the minimum value for the range of results when using
`getByteFrequencyData()`.
`AnalyserNode.maxDecibels`
A double value representing the maximum power value in the scaling range for
the FFT analysis data, for conversion to unsigned byte values — basically,
this specifies the maximum value for the range of results when using
`getByteFrequencyData()`.
`AnalyserNode.smoothingTimeConstant`
A double value representing the averaging constant with the last analysis
frame — basically, it makes the transition between values over time smoother.
## Instance methods
_Inherits methods from its parent,`AudioNode`_.
`AnalyserNode.getFloatFrequencyData()`
Copies the current frequency data into a `Float32Array` array passed into it.
`AnalyserNode.getByteFrequencyData()`
Copies the current frequency data into a `Uint8Array` (unsigned byte array)
passed into it.
`AnalyserNode.getFloatTimeDomainData()`
Copies the current waveform, or time-domain, data into a `Float32Array` array
passed into it.
`AnalyserNode.getByteTimeDomainData()`
Copies the current waveform, or time-domain, data into a `Uint8Array`
(unsigned byte array) passed into it.
## Examples
**Note:** See the guide Visualizations with Web Audio API for more information
on creating audio visualizations.
### Basic usage
The following example shows basic usage of an `AudioContext` to create an
`AnalyserNode`, then `requestAnimationFrame` and `
The JavaScript implementation of `makeDocument()` follows:
function makeDocument() {
let frame = document.getElementById("theFrame");
let doc = document.implementation.createHTMLDocument("New Document");
let p = doc.createElement("p");
p.textContent = "This is a new paragraph.";
try {
doc.body.appendChild(p);
} catch (e) {
console.log(e);
}
// Copy the new HTML document into the frame
let destDocument = frame.contentDocument;
let srcNode = doc.documentElement;
let newNode = destDocument.importNode(srcNode, true);
destDocument.replaceChild(newNode, destDocument.documentElement);
}
The code handles creating the new HTML document and inserting some content
into it. `createHTMLDocument()` constructs a new HTML document whose `