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.
Syntax
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
States
The Three States of a Promise
Every promise is in exactly one of these states:
State
What it means
How it gets there
Which handler runs
pending
Still waiting. No value yet.
Every promise starts here
None yet
fulfilled
Finished with a value.
resolve(value) was called
then(onFulfilled)
rejected
Failed with a reason (usually an Error).
reject(error) was called, or the executor threw
catch(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.
Flow
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);
}
}
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:
Runs
What
Example
1st
All synchronous code, top to bottom
console.log('sync')
2nd
Promise handlers (microtasks), in the order they were queued
p.then(...), code after await
3rd
Timer 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.
Watch out
Common Promise Mistakes
Mistake
What happens
Fix
Forgetting return inside then
The next step gets undefined and does not wait
Return the value or promise
No catch at the end
Unhandled rejection: a console error in browsers; Node.js 15+ stops the program
End every chain with catch() or use try/catch with await
Reading the value too early
You get the promise object, not the value
Use the value inside then or after await
Awaiting tasks one by one
Independent tasks run in sequence and take longer
Start them all, then use Promise.all()
Code
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');
});
A: sync start
B: sync end
C: first then
D: second then
E: timer callback
How It Works
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.
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).
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));
checked chair
ordered CHAIR
checked lamp
sorry, lamp is out of stock
How It Works
Values flow down the chain. For the chair, each then returns a new value: 'chair' becomes 'CHAIR', then 'ordered CHAIR'. catch is skipped.
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.
finally runs first, result unchanged.finally logs checked ... for both items and passes the message through untouched to the outer then, which prints it.
Continue
All 11 Promise Methods
Each method has a full tutorial with examples you can run in the browser.
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.