MDN wants to talk to developers like you:

Our volunteers haven't translated this article into Română yet. Join us and help get the job done!
You can also read the article in English (US).

The Promise object represents the eventual completion (or failure) of an asynchronous operation, and its resulting value.

This entry is for the Promise constructor. To learn about promises, read Using promises first. The constructor is primarily used to wrap functions that do not already support promises.


new Promise( /* executor */ function(resolve, reject) { ... } );


A function that is passed with the arguments resolve and reject. The executor function is executed immediately by the Promise implementation, passing resolve and reject functions (the executor is called before the Promise constructor even returns the created object). The resolve and reject functions, when called, resolve or reject the promise, respectively. The executor normally initiates some asynchronous work, and then, once that completes, either calls the resolve function to resolve the promise or else rejects it if an error occurred.
If an error is thrown in the executor function, the promise is rejected. The return value of the executor is ignored.


A Promise is a proxy for a value not necessarily known when the promise is created. It allows you to associate handlers with an asynchronous action's eventual success value or failure reason. This lets asynchronous methods return values like synchronous methods: instead of immediately returning the final value, the asynchronous method returns a promise to supply the value at some point in the future.

A Promise is in one of these states:

  • pending: initial state, not fulfilled or rejected.
  • fulfilled: meaning that the operation completed successfully.
  • rejected: meaning that the operation failed.

A pending promise can either be fulfilled with a value, or rejected with a reason (error). When either of these options happen, the associated handlers queued up by a promise's then method are called. (If the promise has already been fulfilled or rejected when a corresponding handler is attached, the handler will be called, so there is no race condition between an asynchronous operation completing and its handlers being attached.)

As the Promise.prototype.then() and Promise.prototype.catch() methods return promises, they can be chained.

Not to be confused with: Several other languages have mechanisms for lazy evaluation and deferring a computation, which they also call “promises” — e.g. Scheme. Promises in JavaScript represent processes which are already happening, which can be chained with callback functions. If you are looking to lazily evaluate an expression, consider the arrow function with no arguments: f = () => expression to create the lazily-evaluated expression, and f() to evaluate.

Note: A promise is said to be settled if it is either fulfilled or rejected, but not pending. You will also hear the term resolved used with promises — this means that the promise is settled, or it is locked into a promise chain. Domenic Denicola's States and fates contains more details about promise terminology.


Length property whose value is always 1 (number of constructor arguments).
Represents the prototype for the Promise constructor.


Returns a promise that either fulfills when all of the promises in the iterable argument have fulfilled or rejects as soon as one of the promises in the iterable argument rejects. If the returned promise fulfills, it is fulfilled with an array of the values from the fulfilled promises in the same order as defined in the iterable. If the returned promise rejects, it is rejected with the reason from the first promise in the iterable that rejected. This method can be useful for aggregating results of multiple promises.
Returns a promise that fulfills or rejects as soon as one of the promises in the iterable fulfills or rejects, with the value or reason from that promise.
Returns a Promise object that is rejected with the given reason.
Returns a Promise object that is resolved with the given value. If the value is a thenable (i.e. has a then method), the returned promise will "follow" that thenable, adopting its eventual state; otherwise the returned promise will be fulfilled with the value. Generally, if you don't know if a value is a promise or not, Promise.resolve(value) it instead and work with the return value as a promise.

Promise prototype


Returns the function that created an instance's prototype. This is the Promise function by default.


Appends a rejection handler callback to the promise, and returns a new promise resolving to the return value of the callback if it is called, or to its original fulfillment value if the promise is instead fulfilled.
Promise.prototype.then(onFulfilled, onRejected)
Appends fulfillment and rejection handlers to the promise, and returns a new promise resolving to the return value of the called handler, or to its original settled value if the promise was not handled (i.e. if the relevant handler onFulfilled or onRejected is not a function).


Super simple (6 lines!)

let myFirstPromise = new Promise((resolve, reject) => {
  // We call resolve(...) when what we were doing made async successful, and reject(...) when it failed.
  // In this example, we use setTimeout(...) to simulate async code. 
  // In reality, you will probably be using something like XHR or an HTML5 API.
    resolve("Success!"); // Yay! Everything went well!
  }, 250);

myFirstPromise.then((successMessage) => {
  // successMessage is whatever we passed in the resolve(...) function above.
  // It doesn't have to be a string, but if it is only a succeed message, it probably will be.
  console.log("Yay! " + successMessage);

Creating a Promise

This small example shows the mechanism of a Promise. The testPromise() method is called each time the <button> is clicked. It creates a promise that will be fulfilled, using window.setTimeout(), to the promise count (number starting from 1) every 1-3 seconds, at random. The Promise() constructor is used to create the promise.

The fulfillment of the promise is simply logged, via a fulfill callback set using p1.then(). A few logs show how the synchronous part of the method is decoupled from the asynchronous completion of the promise.

'use strict';
var promiseCount = 0;

function testPromise() {
    let thisPromiseCount = ++promiseCount;

    let log = document.getElementById('log');
    log.insertAdjacentHTML('beforeend', thisPromiseCount +
        ') Started (<small>Sync code started</small>)<br/>');

    // We make a new promise: we promise a numeric count of this promise, starting from 1 (after waiting 3s)
    let p1 = new Promise(
        // The resolver function is called with the ability to resolve or
        // reject the promise
       (resolve, reject) => {
            log.insertAdjacentHTML('beforeend', thisPromiseCount +
                ') Promise started (<small>Async code started</small>)<br/>');
            // This is only an example to create asynchronism
                function() {
                    // We fulfill the promise !
                }, Math.random() * 2000 + 1000);

    // We define what to do when the promise is resolved/rejected with the then() call,
    // and the catch() method defines what to do if the promise is rejected.
        // Log the fulfillment value
        function(val) {
            log.insertAdjacentHTML('beforeend', val +
                ') Promise fulfilled (<small>Async code terminated</small>)<br/>');
        // Log the rejection reason
       (reason) => {
            console.log('Handle rejected promise ('+reason+') here.');

    log.insertAdjacentHTML('beforeend', thisPromiseCount +
        ') Promise made (<small>Sync code terminated</small>)<br/>');

This example is started by clicking the button. You need a browser that supports Promise. By clicking the button several times in a short amount of time, you'll even see the different promises being fulfilled one after another.

Loading an image with XHR

Another simple example using Promise and XMLHttpRequest to load an image is available at the MDN GitHub js-examples repository. You can also see it in action. Each step is commented and allows you to follow the Promise and XHR architecture closely.


Specification Status Comment
ECMAScript 2015 (6th Edition, ECMA-262)
The definition of 'Promise' in that specification.
Standard Initial definition in an ECMA standard.
ECMAScript Latest Draft (ECMA-262)
The definition of 'Promise' in that specification.

Browser compatibility

Feature Chrome Edge Firefox Internet Explorer Opera Safari Servo
Promise32.0(Yes)29.01No support197.12No support
Promise.all32.0(Yes)29.0No support197.1No support
Promise.prototype32.0(Yes)29.0No support197.1No support
Promise.prototype.catch32.0(Yes)29.0No support197.1No support
Promise.prototype.then32.0(Yes)29.0No support197.1No support
Promise.race32.0(Yes)29.0No support197.1No support
Promise.reject32.0(Yes)29.0No support197.1No support
Promise.resolve32.0(Yes)29.0No support197.1No support
Feature Android Chrome for Android Edge Mobile Firefox for Android IE Mobile Opera Mobile Safari Mobile
Promise4.4.432.0(Yes)291No support(Yes)8.02
Promise.all4.4.432.0(Yes)29No support(Yes)8.0
Promise.prototype4.4.432.0(Yes)29No support(Yes)8.0
Promise.prototype.catch4.4.432.0(Yes)29No support(Yes)8.0
Promise.prototype.then4.4.432.0(Yes)29No support(Yes)8.0
Promise.race4.4.432.0(Yes)29No support(Yes)8.0
Promise.reject4.4.432.0(Yes)29No support(Yes)8.0
Promise.resolve4.4.432.0(Yes)29No support(Yes)8.0

1. Constructor requires a new operator since version 37.

2. Constructor requires a new operator since version 10.

See also