JavaScript Promise Object Reference

The JavaScript Promise object represents the eventual completion or failure of an asynchronous operation.

This page documents the Promise constructor, instance methods, and static methods.

Share

Promise Overview

Promise States

A Promise is always in one of three states.

Promise Object Methods

Revised December 2025

Instance Methods

Static Methods

The Promise Constructor

The Promise() constructor creates a new Promise object.

Syntax

new Promise(executor)

Parameters

Return Value

A new Promise object.

Example

const promise = new Promise(function(resolve, reject) {

  const success = true;

  if (success) {

    resolve("Done");

  } else {

    reject("Failed");

  }

});

promise

.then(function(value) {

  myDisplayer(value);

})

.catch(function(error) {

  myDisplayer(error);

});

Promise Instance Methods

Promise then()

The then() method registers functions to handle a Promise result.

The method is called immediately and returns a new Promise.

The registered handler runs asynchronously after the original Promise settles.

Syntax

promise.then(onFulfilled) promise.then(onFulfilled, onRejected)

Parameters

Return Value

A new Promise.

Example

const promise1 = Promise.resolve("Hello");

const promise2 = promise1.then(function(value) {

  return value + " World";

});

promise2.then(function(value) {

  myDisplayer(value);

});

Promise catch()

The catch() method registers a function to handle a rejected Promise.

It returns a new Promise.

Syntax

promise.catch(onRejected)

Parameters

Return Value

A new Promise.

Example

const promise = Promise.reject("Something went wrong");

promise.catch(function(error) {

  myDisplayer(error);

});

Promise finally()

The finally() method registers a function that runs when a Promise settles.

The handler runs whether the Promise is fulfilled or rejected.

It receives no arguments.

Syntax

promise.finally(onFinally)

Parameters

Return Value

A new Promise.

Example

Promise.resolve("Done")

.then(function(value) {

  myDisplayer(value);

})

.finally(function() {

  console.log("Promise settled");

});

Promise Static Methods

Promise.resolve()

The Promise.resolve() method returns a Promise resolved with a value.

Syntax

Promise.resolve(value)

Return Value

A Promise resolved with the specified value.

Example

const promise = Promise.resolve("Resolved OK");

promise.then(function(value) {

  myDisplayer(value);

});

Promise.reject()

The Promise.reject() method returns a Promise rejected with a reason.

Syntax

Promise.reject(reason)

Return Value

A rejected Promise.

Example

const promise = Promise.reject("Something went wrong");

promise.catch(function(error) {

  myDisplayer(error);

});

Promise.all()

The Promise.all() method waits for all input Promises to fulfill.

It rejects when one of the input Promises rejects.

Syntax

Promise.all(iterable)

Return Value

A Promise fulfilled with an array of values when all input Promises fulfill.

Example

const p1 = Promise.resolve("A");

const p2 = Promise.resolve("B");

Promise.all([p1, p2])

.then(function(values) {

  myDisplayer(values);

});

Promise.allSettled()

The Promise.allSettled() method waits for all input Promises to settle.

It returns information about both fulfilled and rejected Promises.

Syntax

Promise.allSettled(iterable)

Return Value

A Promise fulfilled with an array of result objects.

Each result has a status property and either a value or a reason property.

Example

const p1 = Promise.resolve("A");

const p2 = Promise.reject("X");

Promise.allSettled([p1, p2])

.then(function(results) {

  myDisplayer(JSON.stringify(results));

});

Browser Support

Promise.allSettled() is an ES2020 feature.

ES2020 is fully supported in all modern browsers since September 2020:

Promise.any()

The Promise.any() method fulfills when the first input Promise fulfills.

Rejected Promises are ignored unless every input Promise rejects.

Syntax

Promise.any(iterable)

Return Value

A Promise fulfilled with the value of the first fulfilled input Promise.

If every input Promise rejects, the returned Promise rejects with an AggregateError.

Example

const p1 = Promise.reject("Failed");

const p2 = new Promise(function(resolve) {

  setTimeout(function() {

    resolve("First success");

  }, 500);

});

const p3 = new Promise(function(resolve) {

  setTimeout(function() {

    resolve("Second success");

  }, 1000);

});

Promise.any([p1, p2, p3])

.then(function(value) {

  myDisplayer(value);

});

Promise.any() is useful when several sources can provide the same result.

Promise.race()

The Promise.race() method settles when the first input Promise settles.

The first Promise may fulfill or reject.

Syntax

Promise.race(iterable)

Return Value

A Promise settled with the value or reason of the first settled input Promise.

Example

const p1 = new Promise(function(resolve) {

  setTimeout(function() {

    resolve("First");

  }, 500);

});

const p2 = new Promise(function(resolve) {

  setTimeout(function() {

    resolve("Second");

  }, 1000);

});

Promise.race([p1, p2])

.then(function(value) {

  myDisplayer(value);

});

Promise.withResolvers()

The Promise.withResolvers() method creates a Promise and returns its resolving functions.

Syntax

Promise.withResolvers()

Return Value

An object with three properties:

Example

const {promise, resolve, reject} = Promise.withResolvers();

setTimeout(function() {

  resolve("Operation completed");

}, 1000);

promise

.then(function(value) {

  myDisplayer(value);

})

.catch(function(error) {

  myDisplayer(error);

});

Promise Method Comparison