Promise.race(promises) returns a promise that copies the first promise to settle. If the first one fulfills, the race fulfills with its value; if the first one rejects, the race rejects with its reason. The other promises keep running, but their results are ignored. The classic use is a timeout: race your task against a timer.
Remember
Promise.race([a, b]) -> one promise
first to SETTLE wins (value or error)
others keep running, results ignored
already settled -> list order decides
[] -> stays pending forever
Syntax
Call it on Promise with an array (or any iterable) of promises.
JavaScript
Promise.race(iterable)
const first = await Promise.race(iterable);
Call
What it does
Promise.race([task, timeout(ms)])
Fail if the task takes longer than ms.
Promise.race([data, marker])
Find out which one is ready first.
A static method, part of JavaScript since ES2015.
Library declarations
JavaScript
Promise.race(iterable) // returns a Promise
// settles exactly like the first input promise that settles:
// fulfills with its value, or rejects with its reason
Parameters
Parameter
Description
iterable
An array (or other iterable) of promises. A plain value counts as already fulfilled, so it wins unless an earlier entry is already settled.
Return Value
Return Value
Description
Promise
Fulfills or rejects like the first input promise that settles. With an empty list it stays pending forever.
JavaScript Examples
Example 1 — Give a Request a Time Limit
A timeout() helper returns a promise that rejects after a delay. Racing it against a request gives the request a deadline.
both ready, list order decides: first in list
plain value wins: 42
a rejection won: quick fail
How It Works
Already settled entries win right away. The second and third races contain promises that are already fulfilled, so they settle in the first microtask round, before any timer.
Ties go to list order. When several entries are already settled, the earliest one in the list wins. The plain value 42 beats the pending slow promise.
A failure can win. In the first race quickFail settles at 30 ms, before slow, so the race rejects and catch runs.
Example 3 — Show a Spinner Only When Loading Is Slow
Race the data against a 50 ms marker. Fast loads show no spinner; slow loads show one and then still use the data.
JavaScript
function loadProfile(ms) {
return new Promise((resolve) => setTimeout(() => resolve({ name: 'Ada' }), ms));
}
async function showProfile(ms) {
const profile = loadProfile(ms);
const marker = new Promise((resolve) => setTimeout(() => resolve('slow'), 50));
const first = await Promise.race([profile, marker]);
if (first === 'slow') console.log(ms + ': still loading, show a spinner');
const user = await profile;
console.log(ms + ': hello ' + user.name);
}
showProfile(20).then(() => showProfile(120));
20: hello Ada
120: still loading, show a spinner
120: hello Ada
How It Works
Race data against a marker. The marker promise fulfills with 'slow' after 50 ms. Whichever is ready first decides whether a spinner is needed.
A fast load skips the spinner. The 20 ms profile wins, so first is the user object and only the greeting prints.
A slow load shows it, then waits. At 120 ms the marker wins first. The code shows the spinner, then awaits the same profile promise, which still delivers the user.
Compatibility
Browser & Runtime Support
Promise.race() is part of ES2015 (ES6), together with the Promise object itself.
✓ Baseline · ES2015
Promise.race()
Supported in every modern browser, plus Node.js, Deno, and Bun. Internet Explorer has no promises at all.
BaselineEvery modern browser
Google ChromeAll modern versions
Full support
Mozilla FirefoxAll modern versions
Full support
Apple SafariAll modern versions
Full support
Microsoft EdgeAll modern versions
Full support
Node.jsAll current releases
Supported
DenoAll releases
Supported
Internet ExplorerNo native support
Not supported
Promise.race()Excellent
Bottom line: Safe everywhere you can use promises. Remember that a race only stops waiting; to really stop a request, cancel it as well (for example with an AbortController).
Frequently Asked Questions
A promise that settles exactly like the first input promise that settles: it fulfills with that value or rejects with that reason.
Race it against a promise that rejects after a delay: Promise.race([task, timeout(5000)]). Whichever settles first decides the result.
No. The losing tasks keep running until they finish; only their results are ignored. Cancelling the work itself needs a separate tool such as AbortController.
The returned promise stays pending forever, so its then and catch callbacks never run.
Use race when the first outcome matters, such as a timeout. Use any when you want the first success and want to skip failures.