JavaScript Promise Reference
This page is a reference for JavaScript promises.
Use it to look up promise methods and common patterns.
Note
If you want to learn promises step by step, read JavaScript Promises.
The Promise Object
The Promise Object represents the completion or failure of an asynchronous operation.
A Promise can have 3 states:
| pending | initial state |
| rejected | operation failed |
| fulfilled | operation completed |
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 two functions to run when a promise is fulfilled |
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 sette |
| 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 .then() Method
The .then() method provides two functions to run when a promise is fulfilled.
Example
// Using then() to display a result
myPromise.then(
function(value) {myDisplayer(value)},
function(value) {myDisplayer(value)}
);
The .catch() Method
The .catch() method provides a function to run when a promise is rejected.
Example
// Using catch() to display a result
myPromise.catch(
function(value) {myDisplayer(value);}
);
The .finally() Method
The .finally() method provides a function to run when a promise is fulfilled or rejected.
Example
// Using finally() to display a result
myPromise.finally(
function(value) {myDisplayer(value)}
);
Promise.resolve()
The Promise.resolve() method returns a Promise object resolved with a value.
Example
let promise = Promise.resolve("Resolved OK");
promise
.then(function(value) {
myDisplayer(value);
})
.catch(function(value) {
myDisplayer(value);
});
Promise.reject()
The Promise.reject() method returns a Promise object rejected with a value.
Example
let promise = Promise.reject("Something went wrong");
promise
.then(function(value) {
myDisplayer(value);
})
.catch(function(value) {
myDisplayer(value);
});
Promise.all()
The Promise.all() method returns a single Promise from a list of promises,
when all promises fulfill (or rejects when one promise rejects).
Example
let p1 = Promise.resolve("A");
let p2 = Promise.resolve("B");
Promise.all([p1, p2])
.then(function(values) {
myDisplayer(values);
});
Promise.allSettled()
Promise.allSettled() returns an array of results for all promises.
Each result contains a status and a value or reason.
Examples
let p1 = Promise.resolve("A");
let p2 = Promise.reject("X");
Promise.allSettled([p1, p2])
.then(function(results) {
myDisplayer(JSON.stringify(results));
});
Try it Yourself »
// Create a Promise
const myPromise1 = new Promise((resolve, reject) => {
setTimeout(resolve, 200, "King");
});
// Create another Promise
const myPromise2 = new Promise((resolve, reject) => {
setTimeout(resolve, 100, "Queen");
});
// Settle All
Promise.all([myPromise1, myPromise2])
.then(function(values) {
myDisplayer(values);
});
Try it Yourself »
Note
Promise.allSettled() means "Just run all promises. I don't care about the 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.race()
Promise.race() settles when the first promise settles.
Example
let p1 = new Promise(function(resolve) {
setTimeout(function() { resolve("First"); }, 500);
});
let p2 = new Promise(function(resolve) {
setTimeout(function() { resolve("Second"); }, 1000);
});
Promise.race([p1, p2])
.then(function(value) {
myDisplayer(value);
});
Try it Yourself »
Promise.any()
Promise.any() resolves when the first promise is fulfilled.
It rejects only if all promises reject.
Example
let p1 = new Promise(function(resolve) {
setTimeout(function() { resolve("First"); }, 500);
});
let p2 = new Promise(function(resolve) {
setTimeout(function() { resolve("Second"); }, 1000);
});
Promise.race([p1, p2])
.then(function(value) {
myDisplayer(value);
});
Try it Yourself »
Promise.any() is useful when multiple sources can provide the same result.
JavaScript Promise.withResolvers()
Promise.withResolvers()
is a static method that simplifies the creation and management of Promises.
Promise.withResolvers() provides a more convenient way to access
the resolve and reject functions associated with a Promise outside of its executor function.
Instead of the traditional new Promise((resolve, reject) => { ... }) constructor pattern,
Promise.withResolvers() returns an object containing:
- promise: The newly created Promise instance
- resolve: A function to fulfill the promise with a value
- reject: A function to reject the promise with a reason (error)
Example
const {promise, resolve, reject} = Promise.withResolvers();
// You can now use 'resolve' and 'reject' anywhere in your code to control the state of the "promise".
// Simulate async work
setTimeout(() => {
const success = Math.random() > 0.5;
if (success) {
resolve("Operation successful!");
} else {
reject("Operation failed!");
}
}, 1000);
// Display result the promise finishes
promise
.then((value) => {
myDisplayer(value);
})
.catch((value) => {
myDisplayer(value);
});
Try it Yourself »
Example Explained
- After 1 second, the promise resolves or rejects
- The result is written into "demo"
The code to simulate async work can be simplified to:
// Simulate async work
setTimeout(() => {
Math.random() > 0.5
? resolve("Operation successful!")
: reject("Operation failed!");
}, 1000);
The then / catch code can be simplified to:
// Set text in then/catch, update DOM in finally
promise
.then((message) => text = message)
.catch((error) => text = error)
.finally(() => {myDisplayer(text)}
);
Try it Yourself »
Example Explained
- .then() or .catch() set the text variable
- .finally() always runs last, no matter success or failure
- The DOM is updated exactly once, cleanly and reliably
Using async/await is the cleanest:
// Use async/await to handle the promise
(async () => {
try {
text = await promise; // Wait for resolve
} catch (err) {
text = err; // Handle reject
}
// Update the UI after promise finishes
myDisplayer(text);
})();
Try it Yourself »
Example Explained
- async/await makes asynchronous code look synchronous
- The DOM is updated after the promise resolves or rejects
- The UI updates in one place (no duplicated innerHTML calls)
