How to Use Promise.race in JavaScript: Syntax and Examples

Promise.race takes an array of promises and returns a new promise that settles as soon as the first promise in the array settles (either resolves or rejects). It is useful when you want to react to the fastest promise outcome among many.

Syntax

The Promise.race method accepts an iterable (usually an array) of promises and returns a new promise. This new promise settles as soon as the first promise in the iterable settles, with the same value or reason.

• Promise.race(iterable): Starts a race among promises.
• iterable: An array or any iterable of promises.
• The returned promise resolves or rejects with the first settled promise's result.

javascript

Promise.race([promise1, promise2, promise3])
  .then(value => {
    // runs when the first promise resolves
  })
  .catch(error => {
    // runs when the first promise rejects
  });

Example

This example shows three promises with different delays. Promise.race returns the result of the fastest promise, which resolves first.

javascript

const promise1 = new Promise(resolve => setTimeout(() => resolve('First'), 300));
const promise2 = new Promise(resolve => setTimeout(() => resolve('Second'), 200));
const promise3 = new Promise(resolve => setTimeout(() => resolve('Third'), 400));

Promise.race([promise1, promise2, promise3])
  .then(result => console.log(result))
  .catch(error => console.error(error));

Output

Second

Common Pitfalls

One common mistake is expecting Promise.race to wait for all promises to finish. It only cares about the first settled promise and ignores the rest. Also, if the first promise rejects, the race promise rejects immediately, which might be unexpected.

Another pitfall is passing non-promise values; they are treated as resolved promises immediately.

javascript

const p1 = new Promise((_, reject) => setTimeout(() => reject('Error!'), 100));
const p2 = new Promise(resolve => setTimeout(() => resolve('Success'), 200));

// This will reject first because p1 rejects first
Promise.race([p1, p2])
  .then(console.log)
  .catch(console.error);

// Correct handling: be ready for rejection
Promise.race([p1, p2])
  .then(result => console.log('Result:', result))
  .catch(error => console.log('Caught:', error));

Output

Caught: Error!

Quick Reference

Feature	Description
Input	An iterable (usually array) of promises or values
Output	A promise that settles as soon as the first input settles
Resolves	With the value of the first resolved promise
Rejects	With the reason of the first rejected promise
Use case	Get the fastest result among multiple async tasks

Key Takeaways

Promise.race returns a promise that settles as soon as the first input promise settles.

It resolves or rejects with the first settled promise's value or reason.

It does not wait for all promises to finish, only the fastest matters.

Be prepared to handle both resolve and reject outcomes from the race.

Non-promise values in the iterable are treated as immediately resolved promises.