JavaScript Promise

Beginner
9 min read
Updated: Nov 2026
3 examples
Asynchronous code

Definition and Usage

In JavaScript, a Promise is an object that stands for a value you do not have yet. Think of the buzzer a restaurant hands you: you cannot eat it, but it promises that your meal will be ready later, or that the kitchen will tell you something went wrong.

Some work takes time: downloading data with the Fetch API, reading a file, or waiting for a timer. JavaScript does not stop and wait for it. Instead, the slow function returns a promise right away, the rest of your code keeps running, and you tell the promise what to do when the result arrives with then() and catch().

Promises arrived in ES2015 and work in every modern browser and in Node.js. The async and await keywords are built on top of them. This page teaches the ideas; the Promise Methods index lists all 11 method guides.

A promise is a placeholder, not the value.

console.log(promise) shows the box, not what is inside. To get the value, use promise.then((value) => ...) or await promise.

JavaScript Syntax

One side creates the promise and settles it; the other side consumes it:

JavaScript
// Create: the executor runs immediately
const promise = new Promise((resolve, reject) => {
  // do some work, then call ONE of these:
  resolve('the result');            // success -> fulfilled
  // reject(new Error('it failed')); // failure -> rejected
});

// Consume: each handler runs later, when the promise settles
promise
  .then((value) => console.log(value))     // on success
  .catch((error) => console.log(error.message))  // on failure
  .finally(() => console.log('done'));     // either way

The Three States of a Promise

Every promise is in exactly one of these states:

StateWhat it meansHow it gets thereWhich handler runs
pendingStill waiting. No value yet.Every promise starts hereNone yet
fulfilledFinished with a value.resolve(value) was calledthen(onFulfilled)
rejectedFailed with a reason (usually an Error).reject(error) was called, or the executor threwcatch(onRejected)

Fulfilled and rejected together are called settled. A settled promise is final: calling resolve or reject again does nothing, and every handler, even one added later, sees the same result. finally() runs for both settled states.

Creating and Consuming a Promise

Most of the time you consume promises that other code gives you, such as the result of the Fetch API. When you create one yourself, new Promise(executor) calls your executor straight away with two functions, resolve and reject. You can also start from Promise.resolve(), Promise.reject(), or Promise.withResolvers().

On the consuming side, then() returns a new promise. Whatever your callback returns becomes the next value in the chain; if it throws, the chain jumps to the next catch(). The same flow written with async/await reads top to bottom:

JavaScript
// with then / catch
getUser()
  .then((user) => console.log(user.name))
  .catch((error) => console.log('Failed: ' + error.message));

// the same with async / await
async function showUser() {
  try {
    const user = await getUser();
    console.log(user.name);
  } catch (error) {
    console.log('Failed: ' + error.message);
  }
}

To work with several promises at once, use the combinators: Promise.all(), Promise.allSettled(), Promise.any(), and Promise.race().

When Do Promise Handlers Run?

Handlers never run in the middle of your code. When a promise settles, its then, catch, and finally callbacks are put in the microtask queue. JavaScript empties that queue as soon as the current synchronous code has finished, and before any timer callback. So the order is always the same:

RunsWhatExample
1stAll synchronous code, top to bottomconsole.log('sync')
2ndPromise handlers (microtasks), in the order they were queuedp.then(...), code after await
3rdTimer callbacks (tasks)setTimeout(fn, 0)

Even an already fulfilled promise, like Promise.resolve(1), runs its then callback after the synchronous code. Example 2 below shows this step by step.

Common Promise Mistakes

MistakeWhat happensFix
Forgetting return inside thenThe next step gets undefined and does not waitReturn the value or promise
No catch at the endUnhandled rejection: a console error in browsers; Node.js 15+ stops the programEnd every chain with catch() or use try/catch with await
Reading the value too earlyYou get the promise object, not the valueUse the value inside then or after await
Awaiting tasks one by oneIndependent tasks run in sequence and take longerStart them all, then use Promise.all()

JavaScript Examples

Three short programs that show how promises settle, in which order handlers run, and how a chain passes values and errors along.

Example 1 — Your First Promise

A restaurant buzzer in code: the kitchen starts at once, you keep waiting, and the buzzer rings when the meal is ready.

JavaScript
const order = new Promise((resolve) => {
  console.log('1. kitchen starts cooking');
  setTimeout(() => resolve('pizza'), 50);
});

console.log('2. you wait with the buzzer');

order.then((meal) => {
  console.log('3. buzzer rings: ' + meal + ' is ready');
});
then() tutorial

How It Works

  1. The executor runs right away. new Promise() calls the function you pass immediately, so line 1 prints before anything else. The promise is now pending.
  2. Your code does not wait. The timer is only scheduled, so the next line prints at once. order is still a placeholder with no value.
  3. resolve() fulfills it later. After 50 ms resolve('pizza') fulfills the promise, and the then callback receives 'pizza' as meal.

Example 2 — Synchronous Code, Then Microtasks, Then Timers

The letters show the order in which the lines run. The order is the same every time, in every browser and in Node.js.

JavaScript
console.log('A: sync start');

setTimeout(() => console.log('E: timer callback'), 0);

Promise.resolve('C: first then')
  .then((text) => {
    console.log(text);
    return 'D: second then';
  })
  .then((text) => console.log(text));

console.log('B: sync end');

How It Works

  1. All synchronous lines first. A and B print first. Even though Promise.resolve() is already fulfilled, its callback is queued, not called on the spot.
  2. Then the microtask queue. After the script ends, the first then runs (C). Its return value fulfills the next promise, so the second then runs right after (D).
  3. Timers come last. A setTimeout of 0 ms is a task, and tasks wait until the microtask queue is empty, so E prints last.

Example 3 — A Chain Passes Values and Errors Along

Each step of a chain receives what the previous step returned. An error skips ahead to catch(), and finally() runs either way.

JavaScript
function checkStock(item) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (item === 'lamp') reject(new Error('lamp is out of stock'));
      else resolve(item);
    }, 30);
  });
}

function buy(item) {
  return checkStock(item)
    .then((name) => name.toUpperCase())
    .then((label) => 'ordered ' + label)
    .catch((error) => 'sorry, ' + error.message)
    .finally(() => console.log('checked ' + item));
}

buy('chair')
  .then((message) => console.log(message))
  .then(() => buy('lamp'))
  .then((message) => console.log(message));
catch() tutorial

How It Works

  1. Values flow down the chain. For the chair, each then returns a new value: 'chair' becomes 'CHAIR', then 'ordered CHAIR'. catch is skipped.
  2. A rejection jumps to catch. For the lamp, checkStock rejects, so both then steps are skipped. catch returns a normal string, which recovers the chain.
  3. finally runs first, result unchanged. finally logs checked ... for both items and passes the message through untouched to the outer then, which prints it.

All 11 Promise Methods

Each method has a full tutorial with examples you can run in the browser.

MethodUse it to
Promise.all()Wait for every promise; stop at the first failure
Promise.allSettled()Wait for every promise and get a report for each
Promise.any()Take the first success; fail only if all fail
Promise.race()Follow whichever promise settles first
Promise.reject()Make a promise that is already rejected
Promise.resolve()Make a promise from any value
Promise.try()Call a function and always get a promise
Promise.withResolvers()Make a promise and settle it later from outside
catch()Handle an error, optionally recover
finally()Clean up after success or failure
then()Use the value and chain the next step

Grouped by task: Promise Methods index.

Frequently Asked Questions

A Promise is an object that represents a value that is not available yet, such as the result of a network request. It starts pending and later becomes fulfilled with a value or rejected with an error.
Pending (still waiting), fulfilled (finished with a value), and rejected (failed with a reason). Fulfilled and rejected are both called settled, and a settled promise never changes again.
No. async/await is a nicer way to write promise code. An async function always returns a promise, and await waits for a promise to settle, just like then does.
Promise callbacks run as microtasks, which start only after the current synchronous code has finished. This happens even when the promise is already fulfilled.
It becomes an unhandled rejection. Browsers print an error in the console, and Node.js 15 and newer stop the program. End every chain with catch, or use try and catch around await.

Browse every Promise method

Open the index for all(), allSettled(), any(), race(), then(), catch(), finally(), and more.

Promise Methods index →

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.

16 people found this page helpful