JavaScript Promise then() Method

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

Definition

promise.then(onFulfilled, onRejected) tells a promise what to do next. When the promise fulfills, your function receives its value. The key point: then() always returns a new promise. What your function returns becomes the value of that new promise, and a thrown error makes it reject. That is how steps are chained.

Remember
const next = promise.then(onFulfilled, onRejected);

next is a NEW promise, never the same object
fn returns 5         → next fulfills with 5
fn returns a promise → next waits and copies it
fn throws an error   → next rejects with that error

Syntax

Call then on any promise. Pass one function for success, and optionally a second one for failure.

JavaScript
promise.then(onFulfilled)
promise.then(onFulfilled, onRejected)
CallWhat it does
promise.then(onFulfilled)Run onFulfilled(value) when the promise fulfills.
promise.then(onFulfilled, onRejected)Also run onRejected(reason) when it rejects.

Built into JavaScript since ES2015. Both arguments are optional.

Library declarations
JavaScript
promise.then(onFulfilled, onRejected)   // returns a new Promise
// onFulfilled(value) runs on success, onRejected(reason) on failure

Parameters

ParameterDescription
onFulfilledOptional. Called with the fulfilled value. Its return value becomes the value of the new promise.
onRejectedOptional. Called with the rejection reason. If it returns normally, the new promise fulfills.

Return Value

Return ValueDescription
PromiseA new promise. It fulfills with the handler's return value, follows a returned promise, and rejects if the handler throws.

JavaScript Examples

Example 1 — then() Returns a New Promise

Start with a promise that holds 5. Each then() makes a fresh promise, and the last line shows when callbacks run.

JavaScript
const start = Promise.resolve(5);
const doubled = start.then((n) => n * 2);
const message = doubled.then((n) => "Result: " + n);

console.log(doubled === start);
console.log(doubled instanceof Promise);

message.then((text) => {
  console.log(text);
});

console.log("This line runs first");
Try It Yourself

How It Works

  1. Every then() makes a new promise. start.then(...) leaves start alone and gives back doubled. They are two different objects, so the comparison prints false.
  2. The callback waits its turn. JavaScript finishes the whole script first, so This line runs first appears before Result: 10, although the then call is higher up.
  3. Return values travel down the chain. The first callback turns 5 into 10. That 10 is the value of doubled, and the next callback joins it into Result: 10.

Example 2 — Why return Matters Inside then()

Load a name, then its orders. Run the chain twice: with a forgotten return, then with the fix.

JavaScript
function loadOrders(name) {
  return new Promise((resolve) => {
    setTimeout(() => resolve([name + " order 1", name + " order 2"]), 30);
  });
}

Promise.resolve("Asha")
  .then((name) => {
    loadOrders(name);
  })
  .then((orders) => {
    console.log("Without return: " + orders);
    return "Asha";
  })
  .then((name) => {
    return loadOrders(name);
  })
  .then((orders) => {
    console.log("With return: " + JSON.stringify(orders));
  });
Try It Yourself

How It Works

  1. A function without return gives undefined. The first callback calls loadOrders(name) but throws the promise away. It ends with nothing, so the next step gets undefined at once.
  2. Returning a promise makes then() wait. With return loadOrders(name), then() follows that promise. The chain pauses about 30 ms and continues with the real orders.
  3. Always return what the next step needs. Write return for any value or promise you want later. Short arrow functions such as (name) => loadOrders(name) return on their own.

Example 3 — The Second Argument and Thrown Errors

The failure function belongs to the promise it is attached to. See what it can and cannot catch.

JavaScript
const failed = Promise.reject(new Error("server is down"));

failed.then(
  (value) => {
    console.log("ok: " + value);
  },
  (error) => {
    console.log("rejected: " + error.message);
  }
);

const twoArgs = Promise.resolve("data").then(
  (value) => {
    throw new Error("bug inside the success handler");
  },
  (error) => {
    console.log("never printed");
  }
);

twoArgs.then(
  () => {},
  (error) => {
    console.log("found later: " + error.message);
  }
);
Try It Yourself

How It Works

  1. Two functions, one of them runs. failed is already rejected, so then() skips the success function and calls the second one, printing rejected: server is down.
  2. Neighbors do not protect each other. In twoArgs the success function throws. The failure function next to it only watches the original promise, so never printed stays unprinted.
  3. The next link receives the error. The throw makes twoArgs a rejected promise, and the last then() handles it. A .catch() there does the same with less typing.

Browser & Runtime Support

Promise.prototype.then() is part of ES2015 (ES6), together with the Promise constructor.

✓ Baseline · ES2015

Promise.prototype.then()

Supported in every modern browser, plus Node.js, Deno, and Bun. Internet Explorer has no native Promise.

Baseline Every modern browser
Google Chrome All modern versions
Full support
Mozilla Firefox All modern versions
Full support
Apple Safari All modern versions
Full support
Microsoft Edge All modern versions
Full support
Node.js All current releases
Supported
Deno All releases
Supported
Internet Explorer No native support
Not supported
then() Excellent

Bottom line: Safe everywhere today. Only very old browsers such as Internet Explorer need a polyfill.

Frequently Asked Questions

A new promise. It fulfills with what your callback returns, follows a returned promise, and rejects if your callback throws. The original promise is never changed.
Promise callbacks are queued and run only after the current synchronous code has finished. So lines after promise.then(...) always run first.
With then(a, b), function b only handles a rejection of the original promise. If a throws, b does not see it. With then(a).catch(b), the catch also handles errors thrown inside a.
The previous callback did not return anything, and a function without a return statement gives undefined. Add return before the value or promise the next step needs.
They use the same promise machinery. await pauses an async function and gives you the value, as if the rest of the function were inside promise.then(...).

Back to the Promise Method Index

You have seen all three instance methods. Return to the Promise method index and explore the static helpers.

Promise methods →

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