JavaScript Promise withResolvers() Method

Beginner
6 min read
Updated: Nov 2026
3 examples
Static method

Definition

Promise.withResolvers() returns an object with three properties: promise, resolve, and reject. Calling resolve(value) or reject(reason) later, from outside any callback, settles that promise. It replaces the old trick of copying resolve and reject out of a new Promise(...) executor. A promise settles only once.

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

promise   → pending until you settle it
resolve(v) → fulfill promise with v
reject(e)  → reject promise with e
first call wins, later calls do nothing

Syntax

Call it with no arguments and pull out the parts you need with destructuring.

JavaScript
const { promise, resolve, reject } = Promise.withResolvers();
CallWhat it does
Promise.withResolvers()Returns { promise, resolve, reject }.
const { promise, resolve } = ...Take only what you need. Skip reject if the promise can never fail.
const deferred = Promise.withResolvers()Keep the whole object and use deferred.promise, deferred.resolve(), and deferred.reject().

Added in ES2024. Feature-detect with typeof Promise.withResolvers === "function".

Library declarations
JavaScript
Promise.withResolvers()   // returns { promise, resolve, reject }

// resolve(value) and reject(reason) settle it, once

Parameters

ParameterDescription
(none)This method takes no arguments.

Return Value

Return ValueDescription
ObjectAn object with promise (a new pending promise), resolve(value) (fulfills it), and reject(reason) (rejects it).

JavaScript Examples

Example 1 — Resolve a Promise Later

Create a promise, wait for it with then(), and settle it from a timer outside the promise.

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

promise.then((message) => {
  console.log('Got: ' + message);
});

console.log('Waiting for the timer...');
setTimeout(() => resolve('Hello from the timer'), 30);
Try It Yourself

How It Works

  1. Take the parts you need. Destructuring gives promise and resolve. This example never rejects, so it leaves reject behind.
  2. The promise is pending. The then() handler is added first, and Waiting for the timer... prints at once. Nothing has settled yet.
  3. Settle from anywhere. After 30 milliseconds the timer callback calls resolve(...), and the waiting handler prints the message.

Example 2 — Settle from Button Clicks

A confirm dialog: OK resolves the promise, Cancel rejects it. A tiny click list stands in for real buttons.

JavaScript
const clickHandlers = [];

function onClick(buttonName, handler) {
  clickHandlers.push({ buttonName, handler });
}

function click(buttonName) {
  clickHandlers
    .filter((entry) => entry.buttonName === buttonName)
    .forEach((entry) => entry.handler());
}

function askUser() {
  const { promise, resolve, reject } = Promise.withResolvers();
  onClick('ok', () => resolve('User said yes'));
  onClick('cancel', () => reject(new Error('User cancelled')));
  return promise;
}

const answer = askUser();
answer
  .then((message) => console.log(message))
  .catch((error) => console.log(error.message));

console.log('Dialog is open');
click('ok');
click('cancel');
console.log('Buttons were clicked');
Try It Yourself

How It Works

  1. Keep the controls inside. askUser() connects resolve to the OK button and reject to the Cancel button, then returns only the promise.
  2. Callers can wait, not settle. The code outside gets just promise. It can attach handlers, but only the buttons can decide the outcome.
  3. The first click wins. click('ok') fulfills the promise. The later click('cancel') calls reject too late, so User cancelled is never printed.

Example 3 — A Promise Settles Only Once

Call resolve twice and reject once. Three readers wait on one promise; one arrives after it settled.

JavaScript
const { promise: ready, resolve: markReady, reject: markFailed } = Promise.withResolvers();

ready.then((value) => console.log('A saw: ' + value));
ready.then((value) => console.log('B saw: ' + value));

markReady('first');
markReady('second');
markFailed(new Error('too late'));

console.log(typeof markReady);

ready.then((value) => console.log('C saw: ' + value));
Try It Yourself

How It Works

  1. Many readers, one result. Readers A and B were added before settlement. Both get the same value, in the order they were added.
  2. Only the first call counts. markReady('second') and markFailed(...) do nothing. The promise stays fulfilled with first and never rejects.
  3. Late readers still get it. Reader C is added after settlement and still prints first. typeof markReady is function, so the resolvers are ordinary functions.

Browser & Runtime Support

Promise.withResolvers() is part of ES2024.

✓ Newer · ES2024

Promise.withResolvers()

Chrome 119+, Edge 119+, Firefox 121+, Safari 17.4+, and Node.js 22+ (examples run on Node.js 24). Not in Internet Explorer.

Recent Recent browsers only
Google Chrome Chrome 119+
Supported
Mozilla Firefox Firefox 121+
Supported
Apple Safari Safari 17.4+
Supported
Microsoft Edge Edge 119+
Supported
Node.js Node.js 22+
Supported
Deno Recent versions
Supported
Internet Explorer No support
Not supported
Promise.withResolvers() Recent browsers

Bottom line: Feature-detect with typeof Promise.withResolvers === "function". Fallback: declare let resolve, reject, create the promise with new Promise((res, rej) => { resolve = res; reject = rej; }), and use them as before.

Frequently Asked Questions

A plain object with three properties: promise (a pending promise), resolve (fulfills it), and reject (rejects it). Use destructuring to take what you need.
With new Promise() the resolve and reject functions only exist inside the executor. To settle from elsewhere you had to copy them to outer variables. withResolvers() hands them over directly.
No. The first call to resolve or reject decides the result. Later calls are ignored without an error.
Yes. If you call reject and nobody has a catch() handler, it is an unhandled rejection, and Node.js 15 and newer stops the program.
It is ES2024: Chrome 119, Edge 119, Firefox 121, Safari 17.4, and Node.js 22 or newer. Older browsers can use the new Promise() capture trick.

Next: catch()

Handle a rejected promise with catch(), and keep the chain going after an error.

catch() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

11 people found this page helpful