JavaScript Promise race() Method

Beginner
6 min read
Updated: Nov 2026
3 examples
Static method

Definition

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);
CallWhat 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

ParameterDescription
iterableAn 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 ValueDescription
PromiseFulfills 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.

JavaScript
function request(ms) {
  return new Promise((resolve) => setTimeout(() => resolve('data ready'), ms));
}

function timeout(ms) {
  return new Promise((resolve, reject) => {
    setTimeout(() => reject(new Error('timed out')), ms);
  });
}

Promise.race([request(40), timeout(100)])
  .then((result) => console.log('fast request: ' + result))
  .catch((error) => console.log('fast request: ' + error.message));

Promise.race([request(160), timeout(100)])
  .then((result) => console.log('slow request: ' + result))
  .catch((error) => console.log('slow request: ' + error.message));
Try It Yourself

How It Works

  1. Two races, same deadline. Both requests get a 100 ms timer. One request needs 40 ms, the other needs 160 ms.
  2. The fast request wins. At 40 ms the data arrives first, so the first race fulfills and then prints data ready.
  3. The timer beats the slow request. At 100 ms the timeout rejects before the slow data arrives, so the second race rejects and catch prints timed out.

Example 2 — The First Promise to Settle Wins, Even a Failure

Three small races show the rules: a quick rejection wins, list order breaks ties, and plain values count as ready.

JavaScript
const slow = new Promise((resolve) => setTimeout(() => resolve('slow'), 60));
const quickFail = new Promise((resolve, reject) => {
  setTimeout(() => reject(new Error('quick fail')), 30);
});

Promise.race([slow, quickFail])
  .then((v) => console.log('winner: ' + v))
  .catch((e) => console.log('a rejection won: ' + e.message));

Promise.race([Promise.resolve('first in list'), Promise.resolve('second in list')])
  .then((v) => console.log('both ready, list order decides: ' + v));

Promise.race([42, slow]).then((v) => console.log('plain value wins: ' + v));
Try It Yourself

How It Works

  1. 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.
  2. 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.
  3. 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));
Try It Yourself

How It Works

  1. Race data against a marker. The marker promise fulfills with 'slow' after 50 ms. Whichever is ready first decides whether a spinner is needed.
  2. A fast load skips the spinner. The 20 ms profile wins, so first is the user object and only the greeting prints.
  3. 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.

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.

Baseline Every modern browser
Google Chrome All modern versions
Full support
Mozilla Firefox All modern versions
Full support
Apple Safari All modern versions
Full support
Microsoft Edge All modern versions
Full support
Node.js All current releases
Supported
Deno All releases
Supported
Internet Explorer No 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.

Next: Promise.reject()

Create a promise that is already rejected, for errors you know about up front.

reject() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

11 people found this page helpful