Promise.race()

Added in ves6 · Updated March 13, 2026 · Async APIs

promise async es6 javascript

Syntax

Promise.race(iterable)

Parameters

Parameter	Type	Description
`iterable`	`Iterable`	An iterable (such as an Array) containing promises or other values to race.

Return Value

A Promise that resolves or rejects as soon as one of the promises in the iterable resolves or rejects, adopting the outcome of the first settled promise.

Description

Promise.race() returns a promise that settles as soon as any one of the promises in the iterable settles. The winning promise determines the outcome—whether it resolves or rejects, the returned promise adopts the same state.

This method is useful for implementing timeouts. By racing a potentially long-running operation against a timeout promise, you can reject if the operation takes too long:

function fetchWithTimeout(url, timeoutMs) {
  return Promise.race([
    fetch(url),
    new Promise((_, reject) => 
      setTimeout(() => reject(new Error('Timeout')), timeoutMs)
    )
  ]);
}

If the iterable contains non-promise values, they are treated as immediately resolved promises.

Examples

Basic race between two promises

const fast = new Promise(resolve => setTimeout(() => resolve('fast'), 100));
const slow = new Promise(resolve => setTimeout(() => resolve('slow'), 500));

Promise.race([fast, slow])
  .then(console.log); // Output: 'fast' (resolves after 100ms)

Implementing a timeout

const fetchWithTimeout = (url, ms) => {
  const timeout = new Promise((_, reject) => 
    setTimeout(() => reject(new Error('Request timed out')), ms)
  );
  
  return Promise.race([fetch(url), timeout]);
};

fetchWithTimeout('https://api.example.com/data', 3000)
  .then(response => console.log(response))
  .catch(err => console.error(err));

Race with immediate values

Promise.race([Promise.resolve('instant'), new Promise(r => setTimeout(() => r('delayed'), 1000))])
  .then(console.log); // Output: 'instant'