Skip to main content
HTML5ANDCSS3 logoHTML5ANDCSS3Tools and Tutorials

JavaScript Asynchronous

JavaScript async and await

Written by Published

async and await let you write asynchronous code that reads like ordinary code.

await pauses inside an async function until a promise settles.

Nothing else is blocked while it waits.

Example

Example

javascript

function delay(value) {
  return new Promise(function (resolve) {
    setTimeout(function () {
      resolve(value);
    }, 10);
  });
}

async function run() {
  const name = await delay("Ada");
  console.log("got " + name);
}

run();

The output is got Ada, with no then in sight.

async and await

async before a function makes it always return a promise.

await pauses until the promise it is given settles, then gives you the value.

await only works inside an async function, or at the top level of a module.

Syntax

Syntax

javascript

async function name() {
  const value = await promise;
}

await outside an async function is a syntax error.

An async Function Returns a Promise

Even returning a plain value gives you a promise.

Example

Example

javascript

async function getName() {
  return "Ada";
}

getName().then(function (name) {
  console.log(name);
});

The value is wrapped in a resolved promise automatically.

The Same Work, Two Ways

await is doing exactly what the chain did, in fewer lines.

Example

Example

javascript

function delay(value) {
  return Promise.resolve(value);
}

async function withAwait() {
  const a = await delay("one");
  const b = await delay(a + " two");
  console.log(b);
}

withAwait();

Each await replaces a then.

Waiting in a Loop

This is where await really shines.

The same thing with promise chaining is genuinely awkward.

Example

Example

javascript

function double(n) {
  return Promise.resolve(n * 2);
}

async function run() {
  let total = 0;
  for (const n of [1, 2, 3]) {
    total += await double(n);
  }
  console.log(total);
}

run();

The output is 12.

Forgetting await

Without it you get the promise object rather than the value.

This shows up as [object Promise] in the output.

Example

Example

javascript

async function run() {
  const value = await Promise.resolve("ready");
  console.log(value);
}

run();

Dropping the await here would print [object Promise].

It Still Does Not Block

Only the async function pauses; the rest of the program carries on.

The code after run() runs before the awaited value arrives.

Example

Example

javascript

async function run() {
  await Promise.resolve();
  console.log("inside, after await");
}

run();

console.log("outside");

The output is outside first, then inside.

Complete Example

Complete Example

html

<!DOCTYPE html>
<html>
<head>
  <title>JavaScript async and await</title>
</head>
<body>

  <h1>async and await</h1>

  <p id="out">Loading...</p>

  <script>
    function loadUser() {
      return new Promise(function (resolve) {
        setTimeout(function () {
          resolve("Ada Lovelace");
        }, 1000);
      });
    }

    async function show() {
      const name = await loadUser();
      document.getElementById("out").textContent = "Welcome, " + name;
    }

    show();
  </script>

</body>
</html>

Try It Yourself

Run the above example in the Try It Editor.

Try removing await:

Drop the await and see [object Promise] appear instead of the name.

Important Points

  • async makes a function return a promise.
  • await waits for a promise and gives you its value.
  • await only works inside an async function.
  • Forgetting await gives you the promise, not the value.
  • Awaiting pauses the function, not the whole program.

Conclusion

async and await are the clearest way to write asynchronous JavaScript.

They are promises underneath, which is why the earlier lessons matter.

Loops and conditions become straightforward again.

PreviousJavaScript Promise ErrorsNextJavaScript async Error Handling