Setting the file. One moment.
Chapter 04 · Svelte Core Bestpractices
Subchapter 4.2
references/await-expressions.mdMarkdown6 KBView on GitHub
As of Svelte 5.36, you can use the await keyword inside your components in three places where it was previously unavailable:
<script>$derived(...) declarationsThis feature is currently experimental, and you must opt in by adding the experimental.async option wherever you configure (opens in a new tab) Svelte, usually svelte.config.js:
/// file: svelte.config.js
export default {
compilerOptions: {
experimental: {
async: true
}
}
};The experimental flag will be removed in Svelte 6.
When an await expression depends on a particular piece of state, changes to that state will not be reflected in the UI until the asynchronous work has completed, so that the UI is not left in an inconsistent state. In other words, in an example like this…
<!--- file: App.svelte --->
<script>
let a = $state(1);
let b = $state(2);
async function add(a, b) {
await new Promise((f) => setTimeout(f, 500)); // artificial delay
return a + b;
}
</script>
<input type="number" bind:value={a}>
<input type="number" bind:value={b}>
<p>{a} + {b} = {await add(a, b)}</p>…if you increment a, the contents of the <p> will not immediately update to read this —
<p>2 + 2 = 3</p>— instead, the text will update to 2 + 2 = 4 when add(a, b) resolves.
Updates can overlap — a fast update will be reflected in the UI while an earlier slow update is still ongoing.
Svelte will do as much asynchronous work as it can in parallel. For example if you have two await expressions in your markup…
<p>{await one(x)}</p>
<p>{await two(y)}</p>…both functions will run at the same time, as they are independent expressions, even though they are visually sequential.
This does not apply to sequential await expressions inside your <script> or inside async functions — these run like any other asynchronous JavaScript. An exception is that independent $derived expressions will update independently, even though they will run sequentially when they are first created:
// `b` will not be created until `a` has resolved,
// but once created they will update independently
// even if `x` and `y` update simultaneously
let a = $derived(await one(x));
let b = $derived(await two(y));[!NOTE] If you write code like this, expect Svelte to give you an
await_waterfall(opens in a new tab) warning
To render placeholder UI, you can wrap content in a <svelte:boundary> with a pending (opens in a new tab) snippet. This will be shown when the boundary is first created, but not for subsequent updates, which are globally coordinated.
After the contents of a boundary have resolved for the first time and have replaced the pending snippet, you can detect subsequent async work with $effect.pending() (opens in a new tab). This is what you would use to display a “we’re asynchronously validating your input” spinner next to a form field, for example.
You can also use settled() (opens in a new tab) to get a promise that resolves when the current update is complete:
import { tick, settled } from 'svelte';
async function onclick() {
updating = true;
// without this, the change to `updating` will be
// grouped with the other changes, meaning it
// won't be reflected in the UI
await tick();
color = 'octarine';
answer = 42;
await settled();
// any updates affected by `color` or `answer`
// have now been applied
updating = false;
}Errors in await expressions will bubble to the nearest error boundary (opens in a new tab).
Svelte supports asynchronous server-side rendering (SSR) with the render(...) API. To use it, simply await the return value:
/// file: server.js
import { render } from 'svelte/server';
import App from './App.svelte';
const { head, body } = +++await+++ render(App);[!NOTE] If you’re using a framework like SvelteKit, this is done on your behalf.
If a <svelte:boundary> with a pending snippet is encountered during SSR, that snippet will be rendered while the rest of the content is ignored. All await expressions encountered outside boundaries with pending snippets will resolve and render their contents prior to await render(...) returning.
[!NOTE] In the future, we plan to add a streaming implementation that renders the content in the background.
The fork(...) (opens in a new tab) API, added in 5.42, makes it possible to run await expressions that you expect to happen in the near future. This is mainly intended for frameworks like SvelteKit to implement preloading when (for example) users signal an intent to navigate.
<script>
import { fork } from 'svelte';
import Menu from './Menu.svelte';
let open = $state(false);
/** @type {import('svelte').Fork | null} */
let pending = null;
function preload() {
pending ??= fork(() => {
open = true;
});
}
function discard() {
pending?.discard();
pending = null;
}
</script>
<button
onfocusin={preload}
onfocusout={discard}
onpointerenter={preload}
onpointerleave={discard}
onclick={() => {
pending?.commit();
pending = null;
// in case `pending` didn't exist
// (if it did, this is a no-op)
open = true;
}}
>open menu</button>
{#if open}
<!-- any async work inside this component will start
as soon as the fork is created -->
<Menu onclose={() => open = false} />
{/if}As an experimental feature, the details of how await is handled (and related APIs like $effect.pending()) are subject to breaking changes outside of a semver major release, though we intend to keep such changes to a bare minimum.
Effects run in a slightly different order when the experimental.async option is true. Specifically, block effects like {#if ...} and {#each ...} now run before an $effect.pre or beforeUpdate in the same component, which means that in very rare situations.