AbortController
Lets you cancel an asynchronous operation, e.g. a fetch() request, and detach many event handlers at once with a single abort() call.
- Returns
- A new
AbortControllerobject with asignalproperty.
Example
#const controller = new AbortController()
const { signal } = controller
signal.addEventListener('abort', () => console.log('Aborted:', signal.reason.name))
const request = fetch('data:application/json,{"courses":12}', { signal })
controller.abort()
try {
await request
} catch (error) {
console.log('fetch rejected:', error.name)
}
console.log(signal.aborted)The abort event fires right away, during controller.abort(). The request’s promise is rejected with an AbortError, caught by the catch block.
Definition and usage
#AbortController consists of two parts: a controller with an abort() method, and a signal (controller.signal) that you pass to an operation, e.g. fetch(url, { signal }). Calling abort() tells every operation using that signal to stop. An aborted fetch() request rejects its promise with an error named AbortError.
The signal has an aborted property (whether it was aborted), a reason (the reason for aborting: by default the AbortError error, but you can pass your own to abort()), and fires an abort event. The signal.throwIfAborted() method throws the abort reason if the signal is already aborted, which is handy in longer functions. A single controller only works once: an aborted signal stays aborted forever, so create a new controller for the next operation.
You can pass the same signal to addEventListener() too, through the signal option. After abort(), all such handlers get detached, without having to keep track of every function individually. Static methods also produce ready-made signals: AbortSignal.timeout(ms) aborts an operation after a given time (with a TimeoutError), and the newer AbortSignal.any([...]) combines several signals into one.
Syntax
#const controller = new AbortController()
controller.signal
controller.abort()
controller.abort(reason)
signal.aborted
signal.reason
signal.throwIfAborted()
AbortSignal.timeout(ms)Parameters
#reason
optional, any value
The reason for aborting, passed toabort(). It ends up insignal.reasonand in the error rejecting the promise. By default it’s aDOMExceptionerror namedAbortError.
More examples
#let controller
async function search(query) {
controller?.abort()
controller = new AbortController()
try {
const response = await fetch(`data:application/json,{"query":"${query}"}`, {
signal: controller.signal
})
const data = await response.json()
console.log('Results for:', data.query)
} catch (error) {
if (error.name !== 'AbortError') throw error
console.log('Cancelled:', query)
}
}
search('ja')
search('jav')
search('java')Every new search aborts the previous request, so you only get a result for the last piece of text. This is how a search box that searches as you type works.
const button = document.querySelector('#start')
const controller = new AbortController()
const { signal } = controller
button.addEventListener('click', () => console.log('Quiz started'), { signal })
button.addEventListener('click', () => console.log('Timer turned on'), { signal })
document.addEventListener('keydown', () => console.log('Key pressed'), { signal })
button.click()
controller.abort()
button.click()
console.log('Handlers detached:', signal.aborted)After controller.abort(), the second click prints nothing. All three handlers were detached with a single call.
function wait(ms, signal) {
return new Promise((resolve, reject) => {
const timer = setTimeout(resolve, ms)
signal.addEventListener(
'abort',
() => {
clearTimeout(timer)
reject(signal.reason)
},
{ once: true }
)
})
}
const controller = new AbortController()
setTimeout(() => controller.abort(new Error('Response time limit exceeded')), 200)
try {
await wait(1000, controller.signal)
console.log('Response on time')
} catch (error) {
console.log(error.message)
}The wait() function listens for the abort event on the signal and rejects the promise with the reason passed to abort(). You can add cancellation to your own asynchronous operations the same way.
Browser support
#Widely available · since 2019
Works in all modern browsers, phones included. You can use it without worry.
- Chrome
- Edge
- Firefox
- Safari
Good practices
#- Create a new
AbortControllerfor each new operation. An aborted signal stays aborted forever and would immediately abort every following request too. - In a
catchblock, tell an abort apart from a real error witherror.name === "AbortError". A cancellation by the user usually doesn’t need an error message. - For a simple timeout,
fetch(url, { signal: AbortSignal.timeout(5000) })is enough, with no need to create a controller.
Related entries
#- fetch()Sends an HTTP request and returns a promise with the server’s response (a Response object).
- EventTarget.removeEventListener()Detaches an event handler function added earlier with addEventListener(). Requires the same function and the same event type.
- EventTarget.addEventListener()Registers a function that’s called every time a given event occurs on an element, for example a click.
- PromiseAn object representing the result of an operation that will be available in the future: a value on success or an error.
- try...catchCatches errors thrown in the try block and handles them in catch. The optional finally always runs.
- async functionDeclares an asynchronous function that always returns a promise and can use the await keyword inside it.
Spotted a mistake or missing an example? Write to us.