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.
To learn Promises step by step, read JavaScript Promises.
Promise Overview
| Type | Members |
|---|---|
| Constructor | new Promise() |
| Instance methods |
then(),
catch(),
finally()
|
| Static methods |
Promise.resolve(),
Promise.reject(),
Promise.all(),
Promise.allSettled(),
Promise.any(),
Promise.race(),
Promise.withResolvers()
|
Promise States
A Promise is always in one of three states.
| State | Description |
|---|---|
| Pending | The operation has not completed. |
| Fulfilled | The operation completed successfully. |
| Rejected | The operation failed. |
A Promise is settled when it is fulfilled or rejected.
A Promise can settle only once.
Promise Object Methods
Revised December 2025
Instance Methods
| Method | Description |
|---|---|
| .catch(onRejected) | Provides a function to run when a promise is rejected |
| .finally(onFinally) | Provides a function to run when a promise is fulfilled or rejected |
| .then(onFulfilled, onRejected) | Provides one callback function for fulfilled and one for rejected |
Static Methods
| Method | Description |
|---|---|
| Promise.all() | Returns a single Promise from a list of promises When all promises fulfill |
| Promise.allSettled() | Returns a single Promise from a list of promises When all promises settle |
| Promise.any() | Returns a single Promise from a list of promises When any promise fulfills |
| Promise.race() | Returns a single Promise from a list of promises When the faster promise settles |
| Promise.reject() | Returns a Promise rejected with a given value |
| Promise.resolve() | Returns a Promise resolved with a given value |
| Promise.then() | Provides two callbacks: One funtion to run when a promise is fulfilled. One funtion to run when a promise is rejected. |
| Promise.try() | Executes a function and wraps its result in a promise. |
| Promise.withResolvers() | Returns an object containing a new Promise object and two functions to resolve or reject it. |
The Promise Constructor
The Promise() constructor creates a new Promise object.
Syntax
new Promise(executor)
Parameters
| Parameter | Description |
|---|---|
executor |
A function that receives two functions: resolve and reject. |
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
| Method | Description |
|---|---|
then() |
Registers fulfillment and rejection handlers. |
catch() |
Registers a rejection handler. |
finally() |
Registers a handler that runs when the Promise settles. |
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
| Parameter | Description |
|---|---|
onFulfilled |
Optional. A function called with the fulfillment value. |
onRejected |
Optional. A function called with the rejection reason. |
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);
});
promise1 and promise2 are different Promise objects.
Promise catch()
The catch() method registers a function to handle a rejected Promise.
It returns a new Promise.
Syntax
promise.catch(onRejected)
Parameters
| Parameter | Description |
|---|---|
onRejected |
A function called with the rejection reason. |
Return Value
A new Promise.
Example
const promise = Promise.reject("Something went wrong");
promise.catch(function(error) {
myDisplayer(error);
});
catch(onRejected) works like then(undefined, onRejected).
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
| Parameter | Description |
|---|---|
onFinally |
A function called when the Promise settles. |
Return Value
A new Promise.
Example
Promise.resolve("Done")
.then(function(value) {
myDisplayer(value);
})
.finally(function() {
console.log("Promise settled");
});
Promise Static Methods
| Method | Settles When |
|---|---|
Promise.resolve() |
Creates or returns a Promise resolved with a value. |
Promise.reject() |
Creates a Promise rejected with a reason. |
Promise.all() |
All input Promises fulfill, or one rejects. |
Promise.allSettled() |
All input Promises settle. |
Promise.any() |
One input Promise fulfills, or all reject. |
Promise.race() |
The first input Promise settles. |
Promise.withResolvers() |
Creates a Promise with exposed resolve and reject functions. |
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:
| Chrome 85 |
Edge 85 |
Firefox 79 |
Safari 14 |
Opera 71 |
| Aug 2020 | Aug 2020 | Mar 2020 | Sep 2020 | Sep 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:
| Property | Description |
|---|---|
promise |
The newly created Promise. |
resolve |
A function that fulfills the Promise. |
reject |
A function that rejects the Promise. |
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
| Method | Returns | Handles |
|---|---|---|
then() |
A new Promise | Fulfillment or rejection |
catch() |
A new Promise | Rejection |
finally() |
A new Promise | Settlement |
Promise.resolve() |
A resolved Promise | One value |
Promise.reject() |
A rejected Promise | One reason |
Promise.all() |
A Promise | All fulfilled values |
Promise.allSettled() |
A Promise | All settled results |
Promise.any() |
A Promise | First fulfillment |
Promise.race() |
A Promise | First settlement |
Promise.withResolvers() |
An object | External resolving functions |
