The JavaScript Promise.race() method
The Promise.race() method returns a promise that settles as soon as the first of the given promises settles — adopting its value if it fulfilled or its error if it rejected. Its classic use is adding a timeout to an operation: race a task against a promise that rejects after N milliseconds.
Overview
Promise.race() takes several promises and settles the moment the first one settles — whichever finishes first wins, and the race takes on its outcome (fulfilled value or rejected error). The others keep running but their results are ignored.
Its signature use is implementing a timeout. You race your real operation against a "timer" promise that rejects after a set time: if the operation finishes first, you get its result; if the timer fires first, the race rejects with a timeout error. Promise.race([fetchData(), timeout(5000)]) is a clean way to bail out of a slow request — note that fetch() itself has no built-in timeout, so this pattern (or an AbortController) is how you add one.
Be aware it settles on the first to settle, including a rejection — so a fast failure wins the race. If you instead want the first to succeed (ignoring rejections until one fulfills), that's Promise.any(). And to wait for all of them, use Promise.all() or Promise.allSettled().
Syntax
const winner = await Promise.race([p1, p2]);
// add a timeout to an operation
const timeout = (ms) => new Promise((_, reject) =>
setTimeout(() => reject(new Error("timed out")), ms)
);
await Promise.race([doWork(), timeout(5000)]);Parameters
The Promise.race() method accepts the following parameters.
| Parameter | Description |
|---|---|
iterable |
An iterable of promises. The result settles with the first promise to settle (fulfill or reject). |
Example
<pre id="out" style="font:15px ui-monospace,monospace"></pre>
<script>
const after = (val, ms) => new Promise(r => setTimeout(() => r(val), ms));
Promise.race([after('slow', 800), after('fast', 300)]).then(winner => {
document.getElementById('out').textContent = 'winner: ' + winner; // fast
});
</script>Best practices
- Use
Promise.race()to add a timeout — race the task against a rejecting timer. - Remember a fast rejection wins; use
Promise.any()for the first to succeed. - The losing promises still run — race only ignores their results, it can't cancel them.
- For waiting on all, use all() or allSettled().
Frequently asked questions
What does Promise.race() do?
How do I add a timeout to a promise?
Promise.race([task(), timeout(5000)]).What is the difference between race() and any()?
race() settles on the first to settle (including a rejection); Promise.any() settles on the first to fulfill, ignoring rejections.Does Promise.race() cancel the other promises?
AbortController.