JavaScript Reference ยท Operators
The await operator
Reference for the JavaScript await operator: awaiting promises, thenables and plain values, top-level await, error handling with try/catch and parallel patterns.
The await operator pauses an async function until a promise settles. If the promise fulfills, the await expression evaluates to the fulfillment value. If it rejects, the rejection reason is thrown at the await, so you can catch it with an ordinary try...catch. While the function is paused, the rest of the program keeps running; await never blocks the thread.
await is allowed inside async functions and at the top level of ES modules.
const value = await somePromise;
Try it
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
await expression
| Part | Description |
|---|---|
expression |
Usually a promise. Any other value (or a thenable) is converted with Promise.resolve() first. |
Return value: the fulfillment value of the promise, or the value itself when expression is not a promise.
Exceptions: if the promise rejects, await throws the reason. Using await outside an async function or module is a SyntaxError (in a classic script, await is just an identifier).
Usage notes
- Always a pause, even for ready values.
await 1still yields to the microtask queue, so code after it runs later than synchronous code. - Sequential by default. Two awaits in a row run one after the other. Start independent work first and await together with
Promise.all(). awaitin loops.for...ofwithawaitprocesses items one at a time;array.forEach(async ...)does not wait for the callbacks. Usefor...oforPromise.all(array.map(...)).- Error handling. Wrap awaits in
try...catch, or attach.catch()to the promise. An unhandled rejection from an un-awaited promise is easy to miss. - Missing
awaitis a common bug: the code receives a pending promise instead of the value. Intry...catch,return promisewithoutawaitalso skips the catch block for that promise. - Precedence.
awaitis a unary operator, soawait a + bmeans(await a) + b. Use parentheses for(await fetchUser()).name. - Top-level
awaitworks in modules and delays modules that import the one using it. - Stack traces from async functions keep the awaited call chain in modern engines, but they are less complete than synchronous traces.
Browser support
await in async functions is supported in every current browser (ES2017). Top-level await in modules is also supported in current browsers (ES2022); check a compatibility table for older environments.