# $bindable

### On this page

  * [$bindable]($bindable)

Ordinarily, props go one way, from parent to child. This makes it easy to
understand how data flows around your app.

In Svelte, component props can be _bound_ , which means that data can also
flow _up_ from child to parent. This isn’t something you should do often, but
it can simplify your code if used sparingly and carefully.

It also means that a state proxy can be _mutated_ in the child.

> Mutation is also possible with normal props, but is strongly discouraged —
> Svelte will warn you if it detects that a component is mutating state it
> does not ‘own’.

To mark a prop as bindable, we use the `$bindable` rune:

FancyInput

    
    
    <script>
    	let { value = $bindable(), ...props } = $props();
    </script>
    
    <input bind:value={value} {...props} />
    
    <style>
    	input {
    		font-family: 'Comic Sans MS';
    		color: deeppink;
    	}
    </style>
    
    
    <script lang="ts">
    	let { value = $bindable(), ...props } = $props();
    </script>
    
    <input bind:value={value} {...props} />
    
    <style>
    	input {
    		font-family: 'Comic Sans MS';
    		color: deeppink;
    	}
    </style>

Now, a component that uses `<FancyInput>` can add the [`bind:`](bind)
directive
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3WQwWrDMBBEf2URBSfg2nfFMZRCoYeecqx6UJx1IyqvhLUONcb_XqSkTUOSk1az7DBvJtEai0HI90nw6FHIJIhckO7i78n7IhzQctS2OuAtvXHESByEFFVoeuO5VqTYdN71DC-
amvGV_MDQ9q6DrCjP0skkWymKJxYZOgxBfyKs4SGwZlxke7TWZcuVoqo8-1P1z3lraCcP2g64nk4GM5S1osrXf0JV-
lrkgvGbheR-wDm_g30V8JL-1vpOCZFogpQsEsWcemtxscyhKArfOx9gjps0Lq4hzRVfemaYfu-
PoIqqwKPFY_XpaIqj4tYRP7a6M3aUkD27zjSw0RTgbZN6Z8WNs66XsEP03tBXUueUJFlelvYx_wCuI3leNwIAAA==)):

App

    
    
    <script>
    	import FancyInput from './FancyInput.svelte';
    
    	let message = $state('hello');
    </script>
    
    <FancyInput bind:value={message} />
    <p>{message}</p>
    
    
    <script lang="ts">
    	import FancyInput from './FancyInput.svelte';
    
    	let message = $state('hello');
    </script>
    
    <FancyInput bind:value={message} />
    <p>{message}</p>

The parent component doesn’t _have_ to use `bind:` — it can just pass a normal
prop. Some parents don’t want to listen to what their children have to say.

In this case, you can specify a fallback value for when no prop is passed at
all:

FancyInput

    
    
    let { value = $bindable('fallback'), ...props } = $props();

# $derived

### On this page

  * [$derived]($derived)
  * $derived.by
  * Understanding dependencies
  * Overriding derived values
  * Deriveds and reactivity
  * Update propagation

Derived state is declared with the `$derived` rune:

    
    
    <script>
    	let count = $state(0);
    	let doubled = $derived(count * 2);
    </script>
    
    <button onclick={() => count++}>
    	{doubled}
    </button>
    
    <p>{count} doubled is {doubled}</p>

The expression inside `$derived(...)` should be free of side-effects. Svelte
will disallow state changes (e.g. `count++`) inside derived expressions.

As with `$state`, you can mark class fields as `$derived`.

> Code in Svelte components is only executed once at creation. Without the
> `$derived` rune, `doubled` would maintain its original value even when
> `count` changes.

##  $derived.by

Sometimes you need to create complex derivations that don’t fit inside a short
expression. In these cases, you can use `$derived.by` which accepts a function
as its argument.

    
    
    <script>
    	let numbers = $state([1, 2, 3]);
    	let total = $derived.by(() => {
    		let total = 0;
    		for (const n of numbers) {
    			total += n;
    		}
    		return total;
    	});
    </script>
    
    <button onclick={() => numbers.push(numbers.length + 1)}>
    	{numbers.join(' + ')} = {total}
    </button>

In essence, `$derived(expression)` is equivalent to `$derived.by(() =>
expression)`.

##  Understanding dependencies

Anything read synchronously inside the `$derived` expression (or `$derived.by`
function body) is considered a _dependency_ of the derived state. When the
state changes, the derived will be marked as _dirty_ and recalculated when it
is next read.

To exempt a piece of state from being treated as a dependency, use
[`untrack`](svelte#untrack).

##  Overriding derived values

Derived expressions are recalculated when their dependencies change, but you
can temporarily override their values by reassigning them (unless they are
declared with `const`). This can be useful for things like _optimistic UI_ ,
where a value is derived from the ‘source of truth’ (such as data from your
server) but you’d like to show immediate feedback to the user:

    
    
    <script>
    	let { post, like } = $props();
    
    	let likes = $derived(post.likes);
    
    	async function onclick() {
    		// increment the `likes` count immediately...
    		likes += 1;
    
    		// and tell the server, which will eventually update `post`
    		try {
    			await like();
    		} catch {
    			// failed! roll back the change
    			likes -= 1;
    		}
    	}
    </script>
    
    <button {onclick}>🧡 {likes}</button>

> Prior to Svelte 5.25, deriveds were read-only.

##  Deriveds and reactivity

Unlike `$state`, which converts objects and arrays to [deeply reactive
proxies]($state#Deep-state), `$derived` values are left as-is. For example,
[in a case like
this](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE4VU22rjMBD9lUHd3aaQi9PdstS1A3t5XvpQ2Ic4D7I1iUUV2UjjNMX431eS7TRdSosxgjMzZ45mjt0yzffIYibvy0ojFJWqDKCQVBk2ZVup0LJ43TJ6rn2aBxw-
FP2o67k9oCKP5dziW3hRaUJNjoYltjCyplWmM1JIIAn3FlL4ZIkTTtYez6jtj4w8WwyXv9GiIXiQxLVs9pfTMR7EuoSLIuLFbX7Z4930bZo_nBrD1bs834tlfvsBz9_SyX6PZXu9XaL4gOWn4sXjeyzftv4ZWfyxubpzxzg6LfD4MrooxELEosKCUPigQCMPKCZh0OtQE1iSxcsmdHuBvCiHZXALLXiN08EL3RRkaJ_kDVGle0HcSD5TPEeVtj67O4Nrg9aiSNtBY5oODJkrL5QsHtN2cgXp6nSJMWzpWWGasdlsGEMbzi5jPr5KFr0Ep7pdeM2-TCelCddIhDxAobi1jqF3cMaC1RKp64bAW9iFAmXGIHfd4wNXDabtOLN53w8W53VvJoZLh7xk4Rr3CoL-
UNoLhWHrT1JQGcM17u96oES5K-kc2XOzkzqGCKL5De79OUTyyrg1zgwXsrEx3ESfx4Bz0M5UjVMHB24mw9SuXtXFoN13fYKOM1tyUT3FbvbWmSWCZX2Er-41u5xPoml45svRahl9Wb9aasbINJixDZwcPTbyTLZSUsAvrg_cPuCR7s782_WU8343Y72Qtlb8OYatwuOQvuN13M_hJKNfxann1v1U_B1KZ_D_mzhzhz24fw85CSz2irtN9w9HshBK7AQAAA==)...

    
    
    let items = $state([...]);
    
    let index = $state(0);
    let selected = $derived(items[index]);

...you can change (or `bind:` to) properties of `selected` and it will affect
the underlying `items` array. If `items` was _not_ deeply reactive, mutating
`selected` would have no effect.

##  Update propagation

Svelte uses something called _push-pull reactivity_ — when state is updated,
everything that depends on the state (whether directly or indirectly) is
immediately notified of the change (the ‘push’), but derived values are not
re-evaluated until they are actually read (the ‘pull’).

If the new value of a derived is referentially identical to its previous
value, downstream updates will be skipped. In other words, Svelte will only
update the text inside the button when `large` changes, not when `count`
changes, even though `large` depends on `count`:

    
    
    <script>
    	let count = $state(0);
    	let large = $derived(count > 10);
    </script>
    
    <button onclick={() => count++}>
    	{large}
    </button>

# $effect

### On this page

  * [$effect]($effect)
  * $effect.pre
  * $effect.tracking
  * $effect.root
  * When not to use $effect

Effects are functions that run when state updates, and can be used for things
like calling third-party libraries, drawing on `<canvas>` elements, or making
network requests. They only run in the browser, not during server-side
rendering.

Generally speaking, you should _not_ update state inside effects, as it will
make code more convoluted and will often lead to never-ending update cycles.
If you find yourself doing so, see when not to use `$effect` to learn about
alternative approaches.

You can create an effect with the `$effect` rune
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE31S246bMBD9lZF3pSRSAqTVvrCAVPUP2sdSKY4ZwJJjkD0hSVH-
vbINuWxXfQH5zMyZc2ZmZLVUaFn6a2R06ZGlHmBrpvnBvb71fWQHVOSwPbf4GS46TajJspRlVhjZU1HqkhQSWPkHIYdXS5xw-
Zas3ueI6FRn7qHFS11_xSRZhIxbFtcDtw7SJb1iXaOg5XIFeQGjzyPRaevYNOGZIJ8qogbpe8CWiy_VzEpTXiQUcvPDkSVrSNZz1UlW1N5eLcqmpdXUvaQ4BmqlhZNUCgxuzFHDqUWNAxrYeUM76AzsnOsdiJbrBp_71lKpn3RRbii-4P3f-IMsRxS-
wcDV_bL4PmSdBa2wl7pKnbp8DMgVvJm8ZNskKRkEM_OzyOKQFkgqOYBQ3Nq89Ns0nbIl81vMFN-
jKoLMTOr-SOBOJS-Z8f5Y6D1wdcR8dFqvEBdetK-PHwj-z-
cH8oHPY54wRJ8Ys7iSQ3Bg3VA9azQbmC9k35kKzYa6PoVtfwbbKVnBixBiGn7Pq0rqJoUtHiCZwAM3jdTPWCVtr_glhVrhecIa3vuksJ_b7TqFs4DPyriSjd5IwoNNQaAmNI-
ESfR2p8zimzvN1swdCkvJHPH6-_oX8o1SgcIDAAA=)):

    
    
    <script>
    	let size = $state(50);
    	let color = $state('#ff3e00');
    
    	let canvas;
    
    	$effect(() => {
    		const context = canvas.getContext('2d');
    		context.clearRect(0, 0, canvas.width, canvas.height);
    
    		// this will re-run whenever `color` or `size` change
    		context.fillStyle = color;
    		context.fillRect(0, 0, size, size);
    	});
    </script>
    
    <canvas bind:this={canvas} width="100" height="100"></canvas>

When Svelte runs an effect function, it tracks which pieces of state (and
derived state) are accessed (unless accessed inside
[`untrack`](svelte#untrack)), and re-runs the function when that state later
changes.

> If you’re having difficulty understanding why your `$effect` is rerunning or
> is not running see understanding dependencies. Effects are triggered
> differently than the `$:` blocks you may be used to if coming from Svelte 4.

###  Understanding lifecycle

Your effects run after the component has been mounted to the DOM, and in a
[microtask](https://developer.mozilla.org/en-
US/docs/Web/API/HTML_DOM_API/Microtask_guide) after state changes. Re-runs are
batched (i.e. changing `color` and `size` in the same moment won’t cause two
separate runs), and happen after any DOM updates have been applied.

You can use `$effect` anywhere, not just at the top level of a component, as
long as it is called while a parent effect is running.

> Svelte uses effects internally to represent logic and expressions in your
> template — this is how `<h1>hello {name}!</h1>` updates when `name` changes.

An effect can return a _teardown function_ which will run immediately before
the effect re-runs
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE42SQVODMBCF_8pOxkPRKq3HCsx49K4n64xpskjGkDDJ0tph-O8uINo6HjxB3u7HvrehE07WKDbiyZEhi1osRWksRrF57gQdm6E2CKx_dd43zU3co6VB28mIf-
nKO0JH_BmRRRVMQ8XWbXkAgfKtI8jhIpIkXKySu7lSG2tNRGZ1_GlYr1ZTD3ddYFmiosUigbyAbpC2lKbwWJkIB8ZhhxBQBWRSw6FCh3sM8GrYTthL-
wqqku4N44TyqEgwF3lmRHr4Op0PGXoH31c5rO8mqV-
eOZ49bikgtcHBL55tmhIkEMqg_cFB2TpFxjtg703we6NRL8HQFCS07oSUCZi6Rm04lz1yytIHBKoQpo1w6Gsm4gmyS8b8Y5PydeMdX8gwS2Ok4I-ov5NZtvQde95GMsccn_1wzNKfu3RZtS66cSl9lvL7qO1aIk7knbJGvefdtIOzi73M4bYvovUHDFk6AcX_0HRESxnpBOW_jfCDxIZCi_1L_wm4xGQ60wIAAA==)).

    
    
    <script>
    	let count = $state(0);
    	let milliseconds = $state(1000);
    
    	$effect(() => {
    		// This will be recreated whenever `milliseconds` changes
    		const interval = setInterval(() => {
    			count += 1;
    		}, milliseconds);
    
    		return () => {
    			// if a teardown function is provided, it will run
    			// a) immediately before the effect re-runs
    			// b) when the component is destroyed
    			clearInterval(interval);
    		};
    	});
    </script>
    
    <h1>{count}</h1>
    
    <button onclick={() => (milliseconds *= 2)}>slower</button>
    <button onclick={() => (milliseconds /= 2)}>faster</button>

Teardown functions also run when the effect is destroyed, which happens when
its parent is destroyed (for example, a component is unmounted) or the parent
effect re-runs.

###  Understanding dependencies

`$effect` automatically picks up any reactive values (`$state`, `$derived`,
`$props`) that are _synchronously_ read inside its function body (including
indirectly, via function calls) and registers them as dependencies. When those
dependencies change, the `$effect` schedules a re-run.

If `$state` and `$derived` are used directly inside the `$effect` (for
example, during creation of a [reactive class]($state#Classes)), those values
will _not_ be treated as dependencies.

Values that are read _asynchronously_ — after an `await` or inside a
`setTimeout`, for example — will not be tracked. Here, the canvas will be
repainted when `color` changes, but not when `size` changes
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE31T246bMBD9lZF3pWSlBEirfaEQqdo_2PatVIpjBrDkGGQPJGnEv1e2IZfVal-
wfHzmzJyZ4cIqqdCy9M-F0blDlnqArZjmB3f72XWRHVCRw_bc4me4aDWhJstSlllhZEfbQhekkMDKfwg5PFvihMvX5OXH_CJa1Zrb0-Kpqr5jkiwC48rieuDWQbqgZ6wqFLRcvkC-
hYvnkWi1dWqa8ESQTxFRjfQWsOXiWzmr0sSLhEJu3p1YsoJkNUcdZUnN9dagrBu6FVRQHAM10sJRKgUG16bXcGxQ44AGdt7SDkTDdY02iqLHnJVU6hedlWuIp94JW6Tf8oBt_8GdTxlF0b4n0C35ZLBzXb3mmYn3ae6cOW74zj0YVzDNYXRHFt9mprNgHfZSl6mzml8CMoLvTV6wTZIUDEJv5us2iwMtiJRyAKG4tXnhl8O0yhbML0Wm-B7VNlSSSd31BG7z8oIZZ6dgIffAVY_5xdU9Qrz1Bnx8fCfwtZ7v8Qc9j3nB8PqgmMWlHIID6-bkVaPZwDySfWtKNGtquxQ23Qlsq2QJT0KIqb8dL0up6xQ2eIBkAg_c1FI_YqW0neLnFCqFpwmreedJYT7XX8FVOBfwWRhXstZrSXiwKQjUhOZeMIleb5JZfHWn2Yq5pWEpmR7Hv-
N_wEqT8hEEAAA=)):

    
    
    $effect(() => {
    	const context = canvas.getContext('2d');
    	context.clearRect(0, 0, canvas.width, canvas.height);
    
    	// this will re-run whenever `color` changes...
    	context.fillStyle = color;
    
    	setTimeout(() => {
    		// ...but not when `size` changes
    		context.fillRect(0, 0, size, size);
    	}, 0);
    });

An effect only reruns when the object it reads changes, not when a property
inside it changes. (If you want to observe changes _inside_ an object at dev
time, you can use [`$inspect`]($inspect).)

    
    
    <script>
    	let state = $state({ value: 0 });
    	let derived = $derived({ value: state.value * 2 });
    
    	// this will run once, because `state` is never reassigned (only mutated)
    	$effect(() => {
    		state;
    	});
    
    	// this will run whenever `state.value` changes...
    	$effect(() => {
    		state.value;
    	});
    
    	// ...and so will this, because `derived` is a new object each time
    	$effect(() => {
    		derived;
    	});
    </script>
    
    <button onclick={() => (state.value += 1)}>
    	{state.value}
    </button>
    
    <p>{state.value} doubled is {derived.value}</p>

An effect only depends on the values that it read the last time it ran. This
has interesting implications for effects that have conditional code.

For instance, if `condition` is `true` in the code snippet below, the code
inside the `if` block will run and `color` will be evaluated. As such, changes
to either `condition` or `color` [will cause the effect to re-
run](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE21RQW6DMBD8ytaNBJHaJFLViwNIVZ8RcnBgXVk1xsILTYT4e20TQg89IOPZ2fHM7siMaJBx9tmaWpFqjQNlAKXEihx7YVJpdIyfRkY3G4gB8Pi97cPanRtQU8AuwuF_eNUaQuPlOMtc1SlLRWlKUo1tOwJflUikQHZtA0klzCDc64Imx0ANn8bInV1CDhtHgjClrsftcSXotluLybOUb3g4JJHhOZs5WZpuIS9gjNqkJKQP5e2ClrR4SMdZ13E4xZ8zTPOTJU2A2uE_PQ9COCI926_hTVarIU4hu_REPlBrKq2q73ycrf1N-vS4TMUsulaVg3EtR8H9rFgsg8uUsT1B2F9eshigZHBRpuaD0D3mY8Qm2BfB5N2YyRzdNEYVDy0Ja-
WsFjcOUuP1HvFLWA6H3XuHTUSmmDV2--0TXonxsKbp7G9C6R__NONS-MFNvxj_d6mBAgAA).

Conversely, if `condition` is `false`, `color` will not be evaluated, and the
effect will _only_ re-run again when `condition` changes.

    
    
    import confetti from 'canvas-confetti';
    
    let condition = $state(true);
    let color = $state('#ff3e00');
    
    $effect(() => {
    	if (condition) {
    		confetti({ colors: [color] });
    	} else {
    		confetti();
    	}
    });

##  $effect.pre

In rare cases, you may need to run code _before_ the DOM updates. For this we
can use the `$effect.pre` rune:

    
    
    <script>
    	import { tick } from 'svelte';
    
    	let div = $state();
    	let messages = $state([]);
    
    	// ...
    
    	$effect.pre(() => {
    		if (!div) return; // not yet mounted
    
    		// reference `messages` array length so that this code re-runs whenever it changes
    		messages.length;
    
    		// autoscroll when new messages are added
    		if (div.offsetHeight + div.scrollTop > div.scrollHeight - 20) {
    			tick().then(() => {
    				div.scrollTo(0, div.scrollHeight);
    			});
    		}
    	});
    </script>
    
    <div bind:this={div}>
    	{#each messages as message}
    		<p>{message}</p>
    	{/each}
    </div>

Apart from the timing, `$effect.pre` works exactly like `$effect`.

##  $effect.tracking

The `$effect.tracking` rune is an advanced feature that tells you whether or
not the code is running inside a tracking context, such as an effect or inside
your template
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAACn3PwYrCMBDG8VeZDYIt2PYeY8Dn2HrIhqkU08nQjItS-u6buAt7UDzmz8ePyaKGMWBS-
nNRcmdU-
hHUTpGbyuvI3KZvDFLal0v4qvtIgiSZUSb5eWSxPfWSc4oB2xDP1XYk8HHiSHkICeXKeruDDQ4Demlldv4y0rmq6z10HQwuJMxGVv4mVVXDwcJS0jP9u3knynwtoKz1vifT_Z9Jhm0WBCcOTlDD8kyspmML5qNpHg40jc3fFryJ0iWsp_UHgz3180oBAAA=)):

    
    
    <script>
    	console.log('in component setup:', $effect.tracking()); // false
    
    	$effect(() => {
    		console.log('in effect:', $effect.tracking()); // true
    	});
    </script>
    
    <p>in template: {$effect.tracking()}</p> <!-- true -->

It is used to implement abstractions like [`createSubscriber`](svelte-
reactivity#createSubscriber), which will create listeners to update reactive
values but _only_ if those values are being tracked (rather than, for example,
read inside an event handler).

##  $effect.root

The `$effect.root` rune is an advanced feature that creates a non-tracked
scope that doesn’t auto-cleanup. This is useful for nested effects that you
want to manually control. This rune also allows for the creation of effects
outside of the component initialisation phase.

    
    
    const destroy = $effect.root(() => {
    	$effect(() => {
    		// setup
    	});
    
    	return () => {
    		// cleanup
    	};
    });
    
    // later...
    destroy();

##  When not to use $effect

In general, `$effect` is best considered something of an escape hatch — useful
for things like analytics and direct DOM manipulation — rather than a tool you
should use frequently. In particular, avoid using it to synchronise state.
Instead of this...

    
    
    <script>
    	let count = $state(0);
    	let doubled = $state();
    
    	// don't do this!
    	$effect(() => {
    		doubled = count * 2;
    	});
    </script>

...do this:

    
    
    <script>
    	let count = $state(0);
    	let doubled = $derived(count * 2);
    </script>

> For things that are more complicated than a simple expression like `count *
> 2`, you can also use `$derived.by`.

If you’re using an effect because you want to be able to reassign the derived
value (to build an optimistic UI, for example) note that [deriveds can be
directly overridden]($derived#Overriding-derived-values) as of Svelte 5.25.

You might be tempted to do something convoluted with effects to link one value
to another. The following example shows two inputs for “money spent” and
“money left” that are connected to each other. If you update one, the other
should update accordingly. Don’t use effects for this
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE5WRTWrDMBCFryKGLBJoY3fRjWIHeoiu6i6UZBwEY0VE49TB-O6VxrFTSih0qe_Ne_OjHpxpEDS8O7ZMeIAnqC1hAP3RA1990hKI_Fb55v06XJA4sZ0J-IjvT47RcYyBIuzP1vO2chVHHFjxiQ2pUr3k-SZRQlbBx_LIFoEN4zJfzQph_UMQr4hRXmBd456Xy5Uqt6pPKHmkfmzyPAZL2PCnbRpg8qWYu63I7lu4gswOSRYqrPNt3CgeqqzgbNwRK1A76w76YqjFspfcQTWmK3vJHlQm1puSTVSeqdOc_r9GaeCHfUSY26TXry6Br4RSK3C6yMEGT-
aqVU3YbUZ2NF6rfP2KzXgbuYzY46czdgyazy0On_FlLH3F-UDXhgIO35UGlA1rAgAA)):

    
    
    <script>
    	const total = 100;
    	let spent = $state(0);
    	let left = $state(total);
    
    	$effect(() => {
    		left = total - spent;
    	});
    
    	$effect(() => {
    		spent = total - left;
    	});
    </script>
    
    <label>
    	<input type="range" bind:value={spent} max={total} />
    	{spent}/{total} spent
    </label>
    
    <label>
    	<input type="range" bind:value={left} max={total} />
    	{left}/{total} left
    </label>

Instead, use `oninput` callbacks or — better still — [function
bindings](bind#Function-bindings) where possible
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE5VRvW7CMBB-
FcvqECQK6dDFJEgsnfoGTQdDLsjSxVjxhYKivHvPBwFUsXS8774_nwftbQva6I_e78gdvNo6Xzu_j3quG4cQtfkaNJ1DIiWA8atkE8IiHgEpYVsb4Rm-O3gCT2yji7jrXKB15StiOJKiA1lUpXrL81VCEUjFwHTGXiJZgiyf3TYIjSxq6NwR6uyifr0ohMbEZnpHH2rWf7ImS8KZGtK6osl_UqelRIyVL5b3ir5AuwWUtoXzoee6fIWy0p31e6i0XMocLfZQDuI6qtaeykGcR7UU6XWznFAZU9LN_X9B2UyVayk9f3ji0-REugen6U9upDOCcAWcLlS7GNCejWoQTqsLtrfBqHzxDu3DrUTOf0xwIm2o62H85sk6_OHG2jQWI4y_3byXXGMCAAA=)):

    
    
    <script>
    	const total = 100;
    	let spent = $state(0);
    	let left = $derived(total - spent);
    
    	function updateLeft(left) {
    		spent = total - left;
    	}
    </script>
    
    <label>
    	<input type="range" bind:value={spent} max={total} />
    	{spent}/{total} spent
    </label>
    
    <label>
    	<input type="range" bind:value={() => left, updateLeft} max={total} />
    	{left}/{total} left
    </label>

If you absolutely have to update `$state` within an effect and run into an
infinite loop because you read and write to the same `$state`, use
[untrack](svelte#untrack).

# $host

### On this page

  * [$host]($host)

When compiling a component as a [custom element](custom-elements), the `$host`
rune provides access to the host element, allowing you to (for example)
dispatch custom events
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE41Ry2rDMBD8FSECtqkTt1fHFpSSL-
ix7sFRNkTEXglrnTYY_3uRlDgxTaEHIfYxs7szA9-rBizPPwZOZwM89wmecqxbF70as7InaMjltrWFR3mpkQDJ8pwXVnbKkKiwItUa3RGLVtk7gTHQXRDR2lXda4CY1D0SK9nCUk0QPyfrCovsRoNFe17aQOAwGncgO2gBqRzihJXiQrEs2csYOhQ-7HgKHaLIbpRhhBG-I2eD_8ciM4KnnOCbeE5dD2P6h0Dz0-Yi_arNhPLJXBtSGi2TvSXdbpqwdsXvjuYsC1veabvvUTog2ylrapKH2G2XsMFLS4uDthQnq2t1cwKkGOGLvYU5PvaQxLsxOkPmsm97Io1Mo2yUPF6VnOZFkw1RMoopKLKAE_9gmGxyDFMwMcwN-
Bx_ABXQWmOtAgAA)):

Stepper

    
    
    <svelte:options customElement="my-stepper" />
    
    <script>
    	function dispatch(type) {
    		$host().dispatchEvent(new CustomEvent(type));
    	}
    </script>
    
    <button onclick={() => dispatch('decrement')}>decrement</button>
    <button onclick={() => dispatch('increment')}>increment</button>
    
    
    <svelte:options customElement="my-stepper" />
    
    <script lang="ts">
    	function dispatch(type) {
    		$host().dispatchEvent(new CustomEvent(type));
    	}
    </script>
    
    <button onclick={() => dispatch('decrement')}>decrement</button>
    <button onclick={() => dispatch('increment')}>increment</button>

App

    
    
    <script>
    	import './Stepper.svelte';
    
    	let count = $state(0);
    </script>
    
    <my-stepper
    	ondecrement={() => count -= 1}
    	onincrement={() => count += 1}
    ></my-stepper>
    
    <p>count: {count}</p>
    
    
    <script lang="ts">
    	import './Stepper.svelte';
    
    	let count = $state(0);
    </script>
    
    <my-stepper
    	ondecrement={() => count -= 1}
    	onincrement={() => count += 1}
    ></my-stepper>
    
    <p>count: {count}</p>

# $inspect

### On this page

  * [$inspect]($inspect)
  * $inspect(...).with
  * $inspect.trace(...)

> `$inspect` only works during development. In a production build it becomes a
> noop.

The `$inspect` rune is roughly equivalent to `console.log`, with the exception
that it will re-run whenever its argument changes. `$inspect` tracks reactive
state deeply, meaning that updating something inside an object or array using
fine-grained reactivity will cause it to re-fire
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAACkWQ0YqDQAxFfyUMhSotdZ-
tCvu431AXtGOqQ2NmmMm0LOK_r7Utfby5JzeXTOpiCIPKT5PidkSVq2_n1F7Jn3uIcEMSXHSw0evHpAjaGydVzbUQCmgbWaCETZBWMPlKj29nxBDaHj_edkAiu12JhdkYDg61JGvE_s2nR8gyuBuiJZuDJTyQ7eE-
IEOzog1YD80Lb0APLfdYc5F9qnFxjiKWwbImo6_llKRQVs-2u91c_bD2OCJLkT3JZasw7KLA2XCX31qKWE6vIzNk1fKE0XbmYrBTufiI8-_8D2cUWBA_AQAA)):

    
    
    <script>
    	let count = $state(0);
    	let message = $state('hello');
    
    	$inspect(count, message); // will console.log when `count` or `message` change
    </script>
    
    <button onclick={() => count++}>Increment</button>
    <input bind:value={message} />

##  $inspect(...).with

`$inspect` returns a property `with`, which you can invoke with a callback,
which will then be invoked instead of `console.log`. The first argument to the
callback is either `"init"` or `"update"`; subsequent arguments are the values
passed to `$inspect`
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAACkVQ24qDMBD9lSEUqlTqPlsj7ON-w7pQG8c2VCchmVSK-
O-bKMs-
DefKYRYx6BG9qL4XQd2EohKf1opC8Nsm4F84MkbsTXAqMbVXTltuWmp5RAZlAjFIOHjuGLOP_BKVqB00eYuKs82Qn2fNjyxLtcWeyUE2sCRry3qATQIpJRyD7WPVMf9TW-7xFu53dBcoSzAOrsqQNyOe2XUKr0Xi5kcMvdDB2wSYO-I9vKazplV1-T-d6ltgNgSG1KjVUy7ZtmdbdjqtzRcphxMS1-XubOITJtPrQWMvKnYB15_1F7KKadA_AQAA)):

    
    
    <script>
    	let count = $state(0);
    
    	$inspect(count).with((type, count) => {
    		if (type === 'update') {
    			debugger; // or `console.trace`, or whatever you want
    		}
    	});
    </script>
    
    <button onclick={() => count++}>Increment</button>

A convenient way to find the origin of some change is to pass `console.trace`
to `with`:

    
    
    $inspect(stuff).with(console.trace);

##  $inspect.trace(...)

This rune, added in 5.14, causes the surrounding function to be _traced_ in
development. Any time the function re-runs as part of an [effect]($effect) or
a [derived]($derived), information will be printed to the console about which
pieces of reactive state caused the effect to fire.

    
    
    <script>
    	import { doSomeWork } from './elsewhere';
    
    	$effect(() => {
    		// $inspect.trace must be the first statement of a function body
    		$inspect.trace();
    		doSomeWork();
    	});
    </script>

`$inspect.trace` takes an optional first argument which will be used as the
label.

# $props

### On this page

  * [$props]($props)
  * Fallback values
  * Renaming props
  * Rest props
  * Updating props
  * Type safety
  * $props.id()

The inputs to a component are referred to as _props_ , which is short for
_properties_. You pass props to components just like you pass attributes to
elements:

App

    
    
    <script>
    	import MyComponent from './MyComponent.svelte';
    </script>
    
    <MyComponent adjective="cool" />
    
    
    <script lang="ts">
    	import MyComponent from './MyComponent.svelte';
    </script>
    
    <MyComponent adjective="cool" />

On the other side, inside `MyComponent.svelte`, we can receive props with the
`$props` rune...

MyComponent

    
    
    <script>
    	let props = $props();
    </script>
    
    <p>this component is {props.adjective}</p>
    
    
    <script lang="ts">
    	let props = $props();
    </script>
    
    <p>this component is {props.adjective}</p>

...though more commonly, you’ll
[_destructure_](https://developer.mozilla.org/en-
US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) your
props:

MyComponent

    
    
    <script>
    	let { adjective } = $props();
    </script>
    
    <p>this component is {adjective}</p>
    
    
    <script lang="ts">
    	let { adjective } = $props();
    </script>
    
    <p>this component is {adjective}</p>

##  Fallback values

Destructuring allows us to declare fallback values, which are used if the
parent component does not set a given prop (or the value is `undefined`):

    
    
    let { adjective = 'happy' } = $props();

> Fallback values are not turned into reactive state proxies (see Updating
> props for more info)

##  Renaming props

We can also use the destructuring assignment to rename props, which is
necessary if they’re invalid identifiers, or a JavaScript keyword like
`super`:

    
    
    let { super: trouper = 'lights are gonna find me' } = $props();

##  Rest props

Finally, we can use a _rest property_ to get, well, the rest of the props:

    
    
    let { a, b, c, ...others } = $props();

##  Updating props

References to a prop inside a component update when the prop itself updates —
when `count` changes in `App.svelte`, it will also change inside
`Child.svelte`. But the child component is able to temporarily override the
prop value, which can be useful for unsaved ephemeral state
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE6WQ0WrDMAxFf0WIQR0Wmu3VTQJln7HsIfVcZubIxlbGRvC_DzuBraN92qPula50tODZWB1RPi_IX16jLALWSOOUq6P3-_ihLWftNEZ9TVeOWBNHlNhGFYznfqCBzeRdYHh6M_YVzsFNsNs3pdpGd4eBcqPVDMrNxNDBXeSRtXioDgO1zU8ataeZ2RE4Utao924RFXQ9iHXwvoPHKpW1xY4g_Bg0cSVhKS0p560Za95612ZC02ONrD8ZJYdZp_rGQ37ff_mSP86Np2TWZaNNmdcH56P4P67K66_SXoK9pG-5dF5Z9QEAAA==)):

App

    
    
    <script>
    	import Child from './Child.svelte';
    
    	let count = $state(0);
    </script>
    
    <button onclick={() => (count += 1)}>
    	clicks (parent): {count}
    </button>
    
    <Child {count} />
    
    
    <script lang="ts">
    	import Child from './Child.svelte';
    
    	let count = $state(0);
    </script>
    
    <button onclick={() => (count += 1)}>
    	clicks (parent): {count}
    </button>
    
    <Child {count} />

Child

    
    
    <script>
    	let { count } = $props();
    </script>
    
    <button onclick={() => (count += 1)}>
    	clicks (child): {count}
    </button>
    
    
    <script lang="ts">
    	let { count } = $props();
    </script>
    
    <button onclick={() => (count += 1)}>
    	clicks (child): {count}
    </button>

While you can temporarily _reassign_ props, you should not _mutate_ props
unless they are [bindable]($bindable).

If the prop is a regular object, the mutation will have no effect
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3WQwU7DMBBEf2W1QmorQgJXk0RC3PkBwiExG9WQrC17U4Es_ztKUkQp9OjxzM7bjcjtSKjwyfKNp1aLORA4b13ADHszUED1HFE-3eyaBcy-
Mw_O5eFAg8xa1wb6T9eWhVgCKiyD9sZJ3XAjZnTWCzzuzfAKvbcjbPJieR2jm_uGy-
InweXqtd0baaliBG0nFgW3kBIUNWYo9CGoxE-
UsgvIpw2_oc9-LmAPJBCPDJCggqvlVtvdH9puErEMlvVg9HsVtzuoaojzkKKAfRuALVDfk5ZZW0fmy05wXcFdwyktlUs-
KIinljTXrRVnm7-kL9dYLVbUAQAA)):

App

    
    
    <script>
    	import Child from './Child.svelte';
    </script>
    
    <Child object={{ count: 0 }} />
    
    
    <script lang="ts">
    	import Child from './Child.svelte';
    </script>
    
    <Child object={{ count: 0 }} />

Child

    
    
    <script>
    	let { object } = $props();
    </script>
    
    <button onclick={() => {
    	// has no effect
    	object.count += 1
    }}>
    	clicks: {object.count}
    </button>
    
    
    <script lang="ts">
    	let { object } = $props();
    </script>
    
    <button onclick={() => {
    	// has no effect
    	object.count += 1
    }}>
    	clicks: {object.count}
    </button>

If the prop is a reactive state proxy, however, then mutations _will_ have an
effect but you will see an [`ownership_invalid_mutation`](runtime-
warnings#Client-warnings-ownership_invalid_mutation) warning, because the
component is mutating state that does not ‘belong’ to it
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3WR0U7DMAxFf8VESBuiauG1WycheOEbKA9p67FA6kSNszJV-
XeUZhMw2GN8r-1znUmQ7FGU4pn2UqsOes-
SlSGRia3S6ET5Mgk-2OiJBZGdOh6szd0eNcdaIx3-V28NMRI7UYq1awdleVNTzaq3ZmB43CndwXYwPSzyYn4dWxermqJRI4Np3rFlqODasWRcTtAaT1zCHYSbVU3r4nsyrdPMKTUFKDYiE4yfLEoePIbsQpqfy3_nOVMuJIqg0wk1RFg7GOuWfwEbz2wIDLVatR_VtLyBagNTHFIUMCqtoZXeIfAOU1JoUJsR2IC3nWTMjt7GM4yKdyBhlAMpesvhydCC0y_i0ZagHByMh26WzUhXUUxKnpbcVnBfUwhznJnNlac7JkuIURL-2VVfwxflyrWcSQIAAA==)):

App

    
    
    <script>
    	import Child from './Child.svelte';
    
    	let object = $state({count: 0});
    </script>
    
    <Child {object} />
    
    
    <script lang="ts">
    	import Child from './Child.svelte';
    
    	let object = $state({count: 0});
    </script>
    
    <Child {object} />

Child

    
    
    <script>
    	let { object } = $props();
    </script>
    
    <button onclick={() => {
    	// will cause the count below to update,
    	// but with a warning. Don't mutate
    	// objects you don't own!
    	object.count += 1
    }}>
    	clicks: {object.count}
    </button>
    
    
    <script lang="ts">
    	let { object } = $props();
    </script>
    
    <button onclick={() => {
    	// will cause the count below to update,
    	// but with a warning. Don't mutate
    	// objects you don't own!
    	object.count += 1
    }}>
    	clicks: {object.count}
    </button>

The fallback value of a prop not declared with `$bindable` is left untouched —
it is not turned into a reactive state proxy — meaning mutations will not
cause updates
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3WQwU7DMBBEf2VkIbUVoYFraCIh7vwA4eC4G9Wta1vxpgJZ_nfkBEQp9OjxzOzTRGHlkUQlXpy9G0gq1idCL43ppDrAD84HUYheGwqieo2CP3y2Z0EU3-En79fhRIaz1slA_-
nKWSbLQVRiE9SgPTetbVkfvRsYzztttugHd8RiXU6vr-
jisbWb8idhN7O3bEQhmN5ZVDyMlIorcOddv_Eufq4AGmJEuG5PilEjQrnRcoV7JCTUuJlGWq7-YHYjs7NwVhmtDnVcrlA3iLmzLLGTAdaB-j736h68Oxv-
JM1I0AFjoG1OzPfX023c1nhobUoT39QeKsRzS8owM8DFTG_pE6dcVl70AQAA))

Child

    
    
    <script>
    	let { object = { count: 0 } } = $props();
    </script>
    
    <button onclick={() => {
    	// has no effect if the fallback value is used
    	object.count += 1
    }}>
    	clicks: {object.count}
    </button>
    
    
    <script lang="ts">
    	let { object = { count: 0 } } = $props();
    </script>
    
    <button onclick={() => {
    	// has no effect if the fallback value is used
    	object.count += 1
    }}>
    	clicks: {object.count}
    </button>

In summary: don’t mutate props. Either use callback props to communicate
changes, or — if parent and child should share the same object — use the
[`$bindable`]($bindable) rune.

##  Type safety

You can add type safety to your components by annotating your props, as you
would with any other variable declaration. In TypeScript that might look like
this...

    
    
    <script lang="ts">
    	let { adjective }: { adjective: string } = $props();
    </script>

...while in JSDoc you can do this:

    
    
    <script>
    	/** @type {{ adjective: string }} */
    	let { adjective } = $props();
    </script>

You can, of course, separate the type declaration from the annotation:

    
    
    <script lang="ts">
    	interface Props {
    		adjective: string;
    	}
    
    	let { adjective }: Props = $props();
    </script>

> Interfaces for native DOM elements are provided in the `svelte/elements`
> module (see [Typing wrapper components](typescript#Typing-wrapper-
> components))

Adding types is recommended, as it ensures that people using your component
can easily discover which props they should provide.

##  $props.id()

This rune, added in version 5.20.0, generates an ID that is unique to the
current component instance. When hydrating a server-rendered component, the
value will be consistent between server and client.

This is useful for linking elements via attributes like `for` and `aria-
labelledby`.

    
    
    <script>
    	const uid = $props.id();
    </script>
    
    <form>
    	<label for="{uid}-firstname">First Name: </label>
    	<input id="{uid}-firstname" type="text" />
    
    	<label for="{uid}-lastname">Last Name: </label>
    	<input id="{uid}-lastname" type="text" />
    </form>

# $state

### On this page

  * [$state]($state)
  * $state.raw
  * $state.snapshot
  * Passing state into functions
  * Passing state across modules

The `$state` rune allows you to create _reactive state_ , which means that
your UI _reacts_ when it changes.

    
    
    <script>
    	let count = $state(0);
    </script>
    
    <button onclick={() => count++}>
    	clicks: {count}
    </button>

Unlike other frameworks you may have encountered, there is no API for
interacting with state — `count` is just a number, rather than an object or a
function, and you can update it like you would update any other variable.

###  Deep state

If `$state` is used with an array or a simple object, the result is a deeply
reactive _state proxy_. [Proxies](https://developer.mozilla.org/en-
US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) allow Svelte to run
code when you read or write properties, including via methods like
`array.push(...)`, triggering granular updates.

State is proxified recursively until Svelte finds something other than an
array or simple object (like a class). In a case like this...

    
    
    let todos = $state([
    	{
    		done: false,
    		text: 'add more todos'
    	}
    ]);

...modifying an individual todo’s property will trigger updates to anything in
your UI that depends on that specific property:

    
    
    todos[0].done = !todos[0].done;

If you push a new object to the array, it will also be proxified:

    
    
    todos.push({
    	done: false,
    	text: 'eat lunch'
    });

> When you update properties of proxies, the original object is _not_ mutated.

Note that if you destructure a reactive value, the references are not reactive
— as in normal JavaScript, they are evaluated at the point of destructuring:

    
    
    let { done, text } = todos[0];
    
    // this will not affect the value of `done`
    todos[0].done = !todos[0].done;

###  Classes

Class instances are not proxied. Instead, you can use `$state` in class fields
(whether public or private), or as the first assignment to a property
immediately inside the `constructor`:

    
    
    class Todo {
    	done = $state(false);
    
    	constructor(text) {
    		this.text = $state(text);
    	}
    
    	reset() {
    		this.text = '';
    		this.done = false;
    	}
    }

> The compiler transforms `done` and `text` into `get` / `set` methods on the
> class prototype referencing private fields. This means the properties are
> not enumerable.

When calling methods in JavaScript, the value of
[`this`](https://developer.mozilla.org/en-
US/docs/Web/JavaScript/Reference/Operators/this) matters. This won’t work,
because `this` inside the `reset` method will be the `<button>` rather than
the `Todo`:

    
    
    <button onclick={todo.reset}>
    	reset
    </button>

You can either use an inline function...

    
    
    <button onclick={() => todo.reset()}>
    	reset
    </button>

...or use an arrow function in the class definition:

    
    
    class Todo {
    	done = $state(false);
    
    	constructor(text) {
    		this.text = $state(text);
    	}
    
    	reset = () => {
    		this.text = '';
    		this.done = false;
    	}
    }

> Svelte provides reactive implementations of built-in classes like `Set` and
> `Map` that can be imported from [`svelte/reactivity`](svelte-reactivity).

##  $state.raw

In cases where you don’t want objects and arrays to be deeply reactive you can
use `$state.raw`.

State declared with `$state.raw` cannot be mutated; it can only be
_reassigned_. In other words, rather than assigning to a property of an
object, or using an array method like `push`, replace the object or array
altogether if you’d like to update it:

    
    
    let person = $state.raw({
    	name: 'Heraclitus',
    	age: 49
    });
    
    // this will have no effect
    person.age += 1;
    
    // this will work, because we're creating a new person
    person = {
    	name: 'Heraclitus',
    	age: 50
    };

This can improve performance with large arrays and objects that you weren’t
planning to mutate anyway, since it avoids the cost of making them reactive.
Note that raw state can _contain_ reactive state (for example, a raw array of
reactive objects).

As with `$state`, you can declare class fields using `$state.raw`.

##  $state.snapshot

To take a static snapshot of a deeply reactive `$state` proxy, use
`$state.snapshot`:

    
    
    <script>
    	let counter = $state({ count: 0 });
    
    	function onclick() {
    		// Will log `{ count: ... }` rather than `Proxy { ... }`
    		console.log($state.snapshot(counter));
    	}
    </script>

This is handy when you want to pass some state to an external library or API
that doesn’t expect a proxy, such as `structuredClone`.

##  Passing state into functions

JavaScript is a _pass-by-value_ language — when you call a function, the
arguments are the _values_ rather than the _variables_. In other words:

index

    
    
    /**
     * @param {number} a
     * @param {number} b
     */
    function add(a, b) {
    	return a + b;
    }
    
    let a = 1;
    let b = 2;
    let total = add(a, b);
    console.log(total); // 3
    
    a = 3;
    b = 4;
    console.log(total); // still 3!
    
    
    function add(a: number, b: number) {
    	return a + b;
    }
    
    let a = 1;
    let b = 2;
    let total = add(a, b);
    console.log(total); // 3
    
    a = 3;
    b = 4;
    console.log(total); // still 3!

If `add` wanted to have access to the _current_ values of `a` and `b`, and to
return the current `total` value, you would need to use functions instead:

index

    
    
    /**
     * @param {() => number} getA
     * @param {() => number} getB
     */
    function add(getA, getB) {
    	return () => getA() + getB();
    }
    
    let a = 1;
    let b = 2;
    let total = add(() => a, () => b);
    console.log(total()); // 3
    
    a = 3;
    b = 4;
    console.log(total()); // 7
    
    
    function add(getA: () => number, getB: () => number) {
    	return () => getA() + getB();
    }
    
    let a = 1;
    let b = 2;
    let total = add(() => a, () => b);
    console.log(total()); // 3
    
    a = 3;
    b = 4;
    console.log(total()); // 7

State in Svelte is no different — when you reference something declared with
the `$state` rune...

    
    
    let a = 
    namespace $state
    namespace $state

Declares reactive state.

Example:

    
    
    let count = $state(0);

[https://svelte.dev/docs/svelte/$state]($state)

@paraminitial The initial value

$state(1); let `let b: number`b = `

    
    
    function $state<2>(initial: 2): 2 (+1 overload)

` namespace $state

Declares reactive state.

Example:

    
    
    let count = $state(0);

[https://svelte.dev/docs/svelte/$state]($state)

@paraminitial The initial value

$state(2);

...you’re accessing its _current value_.

Note that ‘functions’ is broad — it encompasses properties of proxies and
[`get`](https://developer.mozilla.org/en-
US/docs/Web/JavaScript/Reference/Functions/get)/[`set`](https://developer.mozilla.org/en-
US/docs/Web/JavaScript/Reference/Functions/set) properties...

index

    
    
    /**
     * @param {{ a: number, b: number }} input
     */
    function add(input) {
    	return {
    		get value() {
    			return input.a + input.b;
    		}
    	};
    }
    
    let input = $state({ a: 1, b: 2 });
    let total = add(input);
    console.log(total.value); // 3
    
    input.a = 3;
    input.b = 4;
    console.log(total.value); // 7
    
    
    function add(input: { a: number, b: number }) {
    	return {
    		get value() {
    			return input.a + input.b;
    		}
    	};
    }
    
    let input = $state({ a: 1, b: 2 });
    let total = add(input);
    console.log(total.value); // 3
    
    input.a = 3;
    input.b = 4;
    console.log(total.value); // 7

...though if you find yourself writing code like that, consider using classes
instead.

##  Passing state across modules

You can declare state in `.svelte.js` and `.svelte.ts` files, but you can only
_export_ that state if it’s not directly reassigned. In other words you can’t
do this:

state.svelte

    
    
    export let count = $state(0);
    
    export function increment() {
    	count += 1;
    }

That’s because every reference to `count` is transformed by the Svelte
compiler — the code above is roughly equivalent to this:

state.svelte

    
    
    export let count = $.state(0);
    
    export function increment() {
    	$.set(count, $.get(count) + 1);
    }

> You can see the code Svelte generates by clicking the ‘JS Output’ tab in the
> [playground](https://svelte.dev/playground).

Since the compiler only operates on one file at a time, if another file
imports `count` Svelte doesn’t know that it needs to wrap each reference in
`$.get` and `$.set`:

    
    
    import { count } from './state.svelte.js';
    
    console.log(typeof count); // 'object', not 'number'

This leaves you with two options for sharing state between modules — either
don’t reassign it...

    
    
    // This is allowed — since we're updating
    // `counter.count` rather than `counter`,
    // Svelte doesn't wrap it in `$.state`
    export const counter = $state({
    	count: 0
    });
    
    export function increment() {
    	counter.count += 1;
    }

...or don’t directly export it:

    
    
    let count = $state(0);
    
    export function getCount() {
    	return count;
    }
    
    export function increment() {
    	count += 1;
    }

# {@attach ...}

### On this page

  * [{@attach ...}](@attach)
  * Attachment factories
  * Inline attachments
  * Passing attachments to components
  * Controlling when attachments re-run
  * Creating attachments programmatically
  * Converting actions to attachments

Attachments are functions that run in an [effect]($effect) when an element is
mounted to the DOM or when [state]($state) read inside the function updates.

Optionally, they can return a function that is called before the attachment
re-runs, or after the element is later removed from the DOM.

> Attachments are available in Svelte 5.29 and newer.

App

    
    
    <script>
    	/** @type {import('svelte/attachments').Attachment} */
    	function myAttachment(element) {
    		console.log(element.nodeName); // 'DIV'
    
    		return () => {
    			console.log('cleaning up');
    		};
    	}
    </script>
    
    <div {@attach myAttachment}>...</div>
    
    
    <script lang="ts">
    	import type { Attachment } from 'svelte/attachments';
    
    	const myAttachment: Attachment = (element) => {
    		console.log(element.nodeName); // 'DIV'
    
    		return () => {
    			console.log('cleaning up');
    		};
    	};
    </script>
    
    <div {@attach myAttachment}>...</div>

An element can have any number of attachments.

##  Attachment factories

A useful pattern is for a function, such as `tooltip` in this example, to
_return_ an attachment
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3VT0XLaMBD8lavbDiaNCUlbHhTItG_5h5AH2T5ArdBppDOEMv73SkbGJGnH47F9t3un3TsfMyO3mInsh2SW1Sa7zlZKo8_E0zHjg42pGAjxBPxp7cTvUHOMldLjv-
IVGUbDoUw295VTlh-
WZslqa8kxsLL2ACtHWxh175NffnQfAAGikSGxYQGfPEvGfPSIWtOH0TiBVo2pWJEBJtKhQp4YYzjG9JIdcuMM5IZqHMPioY8vOSA997zQoevf4a7heO7cdp34olRiTGr07OhwH1IdoO2A7dLMbwahZq6MbRhKZWqxk7rBxTGVbuHmhCgb5qDgmIx_J6XtHHukHTrYYqx_YpzYng8aO4RYayql7hU-1ZJl0akqHBE_D9KLolwL-
Dibzc7iSln9XjtqTF1UpMkJ2EmXR-
BgQErsN4pxIJKr0RVO1qrxAqaTO4fbc9bKulZm3cfDY3aZDgvFGErWjmzhN7KmfX5rXyDeX8Pt1mU-
hXjdBOrtuB97vK4GPUtmJ41XcRMEGDLD8do0nJ73zhUhSlyRw0t3vPqD8cjfLs-
axiFgNBrkUd9Ulp50c-GLxlXAVlJX-
ffpZyiSn7H0eLCUySZQcQdXlxj4El0Yv_FZvIKElqqGTruVLhzu7VRKCh22_5toOyxsWqLwwzK-
cCbYNdg-hy-p9D7sbiZWUnts_wLUOF3CJgQAAA==)):

App

    
    
    <script>
    	import tippy from 'tippy.js';
    
    	let content = $state('Hello!');
    
    	/**
    	 * @param {string} content
    	 * @returns {import('svelte/attachments').Attachment}
    	 */
    	function tooltip(content) {
    		return (element) => {
    			const tooltip = tippy(element, { content });
    			return tooltip.destroy;
    		};
    	}
    </script>
    
    <input bind:value={content} />
    
    <button {@attach tooltip(content)}>
    	Hover me
    </button>
    
    
    <script lang="ts">
    	import tippy from 'tippy.js';
    	import type { Attachment } from 'svelte/attachments';
    
    	let content = $state('Hello!');
    
    	function tooltip(content: string): Attachment {
    		return (element) => {
    			const tooltip = tippy(element, { content });
    			return tooltip.destroy;
    		};
    	}
    </script>
    
    <input bind:value={content} />
    
    <button {@attach tooltip(content)}>
    	Hover me
    </button>

Since the `tooltip(content)` expression runs inside an [effect]($effect), the
attachment will be destroyed and recreated whenever `content` changes. The
same thing would happen for any state read _inside_ the attachment function
when it first runs. (If this isn’t what you want, see Controlling when
attachments re-run.)

##  Inline attachments

Attachments can also be created inline
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE71Wf3OaWBT9KoyTTnW3MS-I3dYmnWXVtnRAazRJzbozRSQEApiRhwKO333vuY8m225m_9yZGOT9OPfcc84D943UTfxGr_G7K6Xr3TVeNW7D2M8avT_3DVk-
YAoDNF4vNB8e2tnWjyXGlm7mPzfurVPpp5JgGmeZtwkf5PtFupCxLzVvHa832rl2lElX-s2Xm2DZFNqp_hs-
rZetd4v07ORpT3qmQHu7MF2td0BZp8k6z_xkvfXP902_pZ2_1_aYWEiqm0kN8I4r79qbdZ6umnq3q_2iNf22F4dE6qt2oimwdpim_uY6XMm7Fuo-
IQT_iTD_CeGTHwZ38ieIJUFQRxirR1Xf39Dw0X5z0I72Af4tD61vvPNwWKQnqmfPTbduhsEd2J3vO_oBd3dc6fF2X7umNdWGf0vBRhSS6qoV7cCXfTXWfKmvWG61_si_vfU92Wz-E4RhsLhNIYinsox9QKGVd8-tuACCeKXRX12P-T_eKf7fhTq0Hvt-f3ailtSeoxJHRo1-58NoPe1UiBc1hkL8Yeh45y_vQ3mcuNl9T8s3cXPRWLnS7YWJG_gn2Tb4tUjid8jua-
PVl08j_ab8I14mH8Llx0s5Tz5Err4ql52r_GYg0mVy1bEGZuD0ze64b5TWYFiM-16wSuJ4JT5vfVpDcztrcG_YkRU4s6HxufzDWF4XuVeJ1P10IbzBemt3Vp1V2e04ZXfrJd7Wicyd039brRIv_RIVu_nXi7X1cfL2sy66ztToUp1TO7qJ7NlwZ0f30pld5qNSVE5o6PbMojFHjgZB7oSicPpGteyLclQap7SvY0dXtM_LR1NT2JFHey3aaxa0VxCeYJ7RMHemoiCcgPZV9pR7o7kgcOjeGliYk9hjDZx8FAq6enwlTPSZj_vYPw9Il64dXdIY8ZmapzwfEd8-1ZyaxWhqkIZOibXUd-6Upqi1pD4uMicCV1GA_7zi73UN8BaF4sC8peJtMjfmjbHZBFwq5ov50qRaE0l96NZggnW4KqypYRAW-
uhSz9ADvklwJF2J-5W0Z5fQPBhDX92R6I_0IFxRgDftge4l4dP-gH1hjD7uqU6fsOEZ9UNrCdPB-
nys6uXgY6O3ZMd9sy5T9PghqrWHdjo4jB51CgLiKJaDYYA-7WgYONf1FbjkI-
mE3EAfUY_rijfuJ_CVPaR50oe9JF7Q0pI8Dw3osxxYHdYPGbp2CnwHF8KvwJv2wEv0Z3ilQI6U9uwbZxbYJXvEmjjQjjCHkvNLvNg3yhzXQd1olamsT4IRrZmX0MUDpwL7R8zzHj7pSh9hPHFSHjLezKqAST51uC5zmtQ87skDUaneLokT5RbXkPWSYz53Abgjc8_o4KFGUZ-
Hgv2Z1l5OTYM9D-HfUD0L-EwxH5wRnIG61gS-
khfgY1bq7IAP_DA4l5xRuh9xlm8yGjutc8t-wHtkhWv3hc7aqGwiK5KzgvM5xRkZYn193uEln-
su55j1GaIv7oM4iPrsVHiG0Dx7TR9-1lBfqFdwfvSd5LNL5xyZVp5NoHFZ57FkfiF6vKs4k5zvIfrX5xX6MXmt0gM5MTu8DjnhukrHHzTRd3jm0dma0_f_x5cxP9f4jBdqHvmbq2fUjzqcKh2Cp-
yWj9ntcHanXmBXxhu7Q--
eyjhfNFpaV7zgz4nWEUb7zUOhpevjjf_gu_KZ99pxFlZ-T3sttkmYqrco_26q35v0Ewzv5EZPbnL_8BfduWGMnyyN3q0bZ_7hb_7KG_L4CQAA)):

App

    
    
    <canvas
    	width={32}
    	height={32}
    	{@attach (canvas) => {
    		const context = canvas.getContext('2d');
    
    		$effect(() => {
    			context.fillStyle = color;
    			context.fillRect(0, 0, canvas.width, canvas.height);
    		});
    	}}
    ></canvas>

> The nested effect runs whenever `color` changes, while the outer effect
> (where `canvas.getContext(...)` is called) only runs once, since it doesn’t
> read any reactive state.

##  Passing attachments to components

When used on a component, `{@attach ...}` will create a prop whose key is a
[`Symbol`](https://developer.mozilla.org/en-
US/docs/Web/JavaScript/Reference/Global_Objects/Symbol). If the component then
[spreads](https://svelte.dev/tutorial/svelte/spread-props) props onto an
element, the element will receive those attachments.

This allows you to create _wrapper components_ that augment elements
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3VUS3ObMBD-
KxvajnFqsJM2PhA7TXrKob31FjITAbKtRkiMtDhJPfz3LiAMdpxhGJvdb1_fPnaeYjn3Iu-
WIbJ04028lZDcetHDzsO3olbVApI74F1RhHbLJdayhFl-
Sp5qhVwhufEWNjWiwJtYxSjyQhsEFEXxBiujcxg1_8O_dnQ9APwsEbVyiHDafjrvDZCgkiO4MLCEzxYZcn90z6XUZ6OxA61KlaIgV6i1pFC-
sxjDrlbHaDiWRoGvdMbHsLzp5DES0mJnRxGaRBvcBHb7yFUTCQeunEWYcYtGv12TqgFUDbCK1WLaM6IWQhUlQiJUFm2ZLPly51xXMG0Rjoyd69C7UqqG2nu95QZyXvtvLVpri2-SN4hoLXXCZFfhQ8aQBU1VgdEaH_vSgyBZR_BpPp_vi0tY-
rw2ulRZkGqpTQRbZvwa2BPgFC8bgbw31CbjJjAsE6WNYBZeGp7vtQXLMqHWnZx-5kM1TR5ycpkZXQR2wzL94l8Ur1C_3-g168SfQf1MyfRi3LW9fs77emJEw5QV9SREoLTq06tcczq7d6xEUcJX2vAhO1b843XK34e5unZEMBr15ekuKEusluWAF8lXhE2ZTP2r2RcIHJ-163FPKerCgYJLOB9i4GvNwviI5-gAQiFFBk3tBTOU3HFXEk0R8o86WvUD64aINhv5K3oRmpJXkw8uxMG6Hh6JY9X7OwGSqfUy9tDG3sHNoEi0d_d_fv9qndxRU0VClFqo3KVo3U655Hnt1PXB3Qra2Y2QGdEwgTAMCxopsoxOe6SD0gD8movDhT0LAnhqlE8gVCpLWnRoV7OJCkFAwEXitrYL1W7p7pbiE_P7XH6E_rihODm5s52XtiH9Ekaw0VgI9exadWL1uoEYjPtg2672k5szsxbKyWB2fdT0w5Y_0hcT8oXOlRetmLS8-g-6TLXXQgYAAA==)):

Button

    
    
    <script>
    	/** @type {import('svelte/elements').HTMLButtonAttributes} */
    	let { children, ...props } = $props();
    </script>
    
    <!-- `props` includes attachments -->
    <button {...props}>
    	{@render children?.()}
    </button>
    
    
    <script lang="ts">
    	import type { HTMLButtonAttributes } from 'svelte/elements';
    
    	let { children, ...props }: HTMLButtonAttributes = $props();
    </script>
    
    <!-- `props` includes attachments -->
    <button {...props}>
    	{@render children?.()}
    </button>

App

    
    
    <script>
    	import tippy from 'tippy.js';
    	import Button from './Button.svelte';
    
    	let content = $state('Hello!');
    
    	/**
    	 * @param {string} content
    	 * @returns {import('svelte/attachments').Attachment}
    	 */
    	function tooltip(content) {
    		return (element) => {
    			const tooltip = tippy(element, { content });
    			return tooltip.destroy;
    		};
    	}
    </script>
    
    <input bind:value={content} />
    
    <Button {@attach tooltip(content)}>
    	Hover me
    </Button>
    
    
    <script lang="ts">
    	import tippy from 'tippy.js';
    	import Button from './Button.svelte';
    	import type { Attachment } from 'svelte/attachments';
    
    	let content = $state('Hello!');
    
    	function tooltip(content: string): Attachment {
    		return (element) => {
    			const tooltip = tippy(element, { content });
    			return tooltip.destroy;
    		};
    	}
    </script>
    
    <input bind:value={content} />
    
    <Button {@attach tooltip(content)}>
    	Hover me
    </Button>

##  Controlling when attachments re-run

Attachments, unlike [actions](use), are fully reactive: `{@attach foo(bar)}`
will re-run on changes to `foo` _or_ `bar` (or any state read inside `foo`):

    
    
    function foo(bar) {
    	return (node) => {
    		veryExpensiveSetupWork(node);
    		update(node, bar);
    	};
    }

In the rare case that this is a problem (for example, if `foo` does expensive
and unavoidable setup work) consider passing the data inside a function and
reading it in a child effect:

    
    
    function foo(getBar) {
    	return (node) => {
    		veryExpensiveSetupWork(node);
    
    		
    namespace $effect
    namespace $effect

Runs code when a component is mounted to the DOM, and then whenever its
dependencies change, i.e. `$state` or `$derived` values. The timing of the
execution is after the DOM has been updated.

Example:

    
    
    $effect(() => console.log('The count is now ' + count));

If you return a function from the effect, it will be called right before the
effect is run again, or when the component is unmounted.

Does not run during server side rendering.

[https://svelte.dev/docs/svelte/$effect]($effect)

@paramfn The function to execute

$effect(() => { update(`node: any`node, `getBar: any`getBar()); }); } }

##  Creating attachments programmatically

To add attachments to an object that will be spread onto a component or
element, use [`createAttachmentKey`](svelte-attachments#createAttachmentKey).

##  Converting actions to attachments

If you’re using a library that only provides actions, you can convert them to
attachments with [`fromAction`](svelte-attachments#fromAction), allowing you
to (for example) use them with components.

# {@const ...}

### On this page

  * [{@const ...}](@const)

The `{@const ...}` tag defines a local constant.

    
    
    {#each boxes as box}
    	{@const area = box.width * box.height}
    	{box.width} * {box.height} = {area}
    {/each}

`{@const}` is only allowed as an immediate child of a block — `{#if ...}`,
`{#each ...}`, `{#snippet ...}` and so on — a `<Component />` or a
`<svelte:boundary>`.

# {@debug ...}

### On this page

  * [{@debug ...}](@debug)

The `{@debug ...}` tag offers an alternative to `console.log(...)`. It logs
the values of specific variables whenever they change, and pauses code
execution if you have devtools open.

    
    
    <script>
    	let user = {
    		firstname: 'Ada',
    		lastname: 'Lovelace'
    	};
    </script>
    
    {@debug user}
    
    <h1>Hello {user.firstname}!</h1>

`{@debug ...}` accepts a comma-separated list of variable names (not arbitrary
expressions).

    
    
    <!-- Compiles -->
    {@debug user}
    {@debug user1, user2, user3}
    
    <!-- WON'T compile -->
    {@debug user.firstname}
    {@debug myArray[0]}
    {@debug !isReady}
    {@debug typeof user === 'object'}

The `{@debug}` tag without any arguments will insert a `debugger` statement
that gets triggered when _any_ state changes, as opposed to the specified
variables.

# {@html ...}

### On this page

  * [{@html ...}](@html)
  * Styling

To inject raw HTML into your component, use the `{@html ...}` tag:

    
    
    <article>
    	{@html content}
    </article>

> Make sure that you either escape the passed string or only populate it with
> values that are under your control in order to prevent [XSS
> attacks](https://owasp.org/www-community/attacks/xss/). Never render
> unsanitized content.

The expression should be valid standalone HTML — this will not work, because
`</div>` is not valid HTML:

    
    
    {@html '<div>'}content{@html '</div>'}

It also will not compile Svelte code.

##  Styling

Content rendered this way is ‘invisible’ to Svelte and as such will not
receive [scoped styles](scoped-styles) — in other words, this will not work,
and the `a` and `img` styles will be regarded as unused:

    
    
    <article>
    	{@html content}
    </article>
    
    <style>
    	article {
    		a { color: hotpink }
    		img { width: 100% }
    	}
    </style>

Instead, use the `:global` modifier to target everything inside the
`<article>`:

    
    
    <style>
    	article :global {
    		a { color: hotpink }
    		img { width: 100% }
    	}
    </style>

# {@render ...}

### On this page

  * [{@render ...}](@render)
  * Optional snippets

To render a [snippet](snippet), use a `{@render ...}` tag.

    
    
    {#snippet sum(a, b)}
    	<p>{a} + {b} = {a + b}</p>
    {/snippet}
    
    {@render sum(1, 2)}
    {@render sum(3, 4)}
    {@render sum(5, 6)}

The expression can be an identifier like `sum`, or an arbitrary JavaScript
expression:

    
    
    {@render (cool ? coolSnippet : lameSnippet)()}

##  Optional snippets

If the snippet is potentially undefined — for example, because it’s an
incoming prop — then you can use optional chaining to only render it when it
_is_ defined:

    
    
    {@render children?.()}

Alternatively, use an [`{#if ...}`](if) block with an `:else` clause to render
fallback content:

    
    
    {#if children}
    	{@render children()}
    {:else}
    	<p>fallback content</p>
    {/if}

# animate:

### On this page

  * [animate:](animate)
  * Animation Parameters
  * Custom animation functions

An animation is triggered when the contents of a [keyed each
block](each#Keyed-each-blocks) are re-ordered. Animations do not run when an
element is added or removed, only when the index of an existing data item
within the each block changes. Animate directives must be on an element that
is an _immediate_ child of a keyed each block.

Animations can be used with Svelte’s [built-in animation functions](svelte-
animate) or custom animation functions.

    
    
    <!-- When `list` is reordered the animation will run -->
    {#each list as item, index (item)}
    	<li animate:flip>{item}</li>
    {/each}

##  Animation Parameters

As with actions and transitions, animations can have parameters.

(The double `{{curlies}}` aren’t a special syntax; this is an object literal
inside an expression tag.)

    
    
    {#each list as item, index (item)}
    	<li animate:flip={{ delay: 500 }}>{item}</li>
    {/each}

##  Custom animation functions

    
    
    animation = (node: HTMLElement, { from: DOMRect, to: DOMRect } , params: any) => {
    	delay?: number,
    	duration?: number,
    	easing?: (t: number) => number,
    	css?: (t: number, u: number) => string,
    	tick?: (t: number, u: number) => void
    }

Animations can use custom functions that provide the `node`, an `animation`
object and any `parameters` as arguments. The `animation` parameter is an
object containing `from` and `to` properties each containing a
[DOMRect](https://developer.mozilla.org/en-US/docs/Web/API/DOMRect#Properties)
describing the geometry of the element in its `start` and `end` positions. The
`from` property is the DOMRect of the element in its starting position, and
the `to` property is the DOMRect of the element in its final position after
the list has been reordered and the DOM updated.

If the returned object has a `css` method, Svelte will create a [web
animation](https://developer.mozilla.org/en-
US/docs/Web/API/Web_Animations_API) that plays on the element.

The `t` argument passed to `css` is a value that goes from `0` and `1` after
the `easing` function has been applied. The `u` argument is equal to `1 - t`.

The function is called repeatedly _before_ the animation begins, with
different `t` and `u` arguments.

App

    
    
    <script>
    	import { cubicOut } from 'svelte/easing';
    
    	/**
    	 * @param {HTMLElement} node
    	 * @param {{ from: DOMRect; to: DOMRect }} states
    	 * @param {any} params
    	 */
    	function whizz(node, { from, to }, params) {
    		const dx = from.left - to.left;
    		const dy = from.top - to.top;
    
    		const d = Math.sqrt(dx * dx + dy * dy);
    
    		return {
    			delay: 0,
    			duration: Math.sqrt(d) * 120,
    			easing: cubicOut,
    			css: (t, u) => `transform: translate(${u * dx}px, ${u * dy}px) rotate(${t * 360}deg);`
    		};
    	}
    </script>
    
    {#each list as item, index (item)}
    	<div animate:whizz>{item}</div>
    {/each}
    
    
    <script lang="ts">
    	import { cubicOut } from 'svelte/easing';
    
    	function whizz(node: HTMLElement, { from, to }: { from: DOMRect; to: DOMRect }, params: any) {
    		const dx = from.left - to.left;
    		const dy = from.top - to.top;
    
    		const d = Math.sqrt(dx * dx + dy * dy);
    
    		return {
    			delay: 0,
    			duration: Math.sqrt(d) * 120,
    			easing: cubicOut,
    			css: (t, u) => `transform: translate(${u * dx}px, ${u * dy}px) rotate(${t * 360}deg);`
    		};
    	}
    </script>
    
    {#each list as item, index (item)}
    	<div animate:whizz>{item}</div>
    {/each}

A custom animation function can also return a `tick` function, which is called
_during_ the animation with the same `t` and `u` arguments.

> If it’s possible to use `css` instead of `tick`, do so — web animations can
> run off the main thread, preventing jank on slower devices.

App

    
    
    <script>
    	import { cubicOut } from 'svelte/easing';
    
    	/**
    	 * @param {HTMLElement} node
    	 * @param {{ from: DOMRect; to: DOMRect }} states
    	 * @param {any} params
    	 */
    	function whizz(node, { from, to }, params) {
    		const dx = from.left - to.left;
    		const dy = from.top - to.top;
    
    		const d = Math.sqrt(dx * dx + dy * dy);
    
    		return {
    			delay: 0,
    			duration: Math.sqrt(d) * 120,
    			easing: cubicOut,
    			tick: (t, u) => Object.assign(node.style, { color: t > 0.5 ? 'Pink' : 'Blue' })
    		};
    	}
    </script>
    
    {#each list as item, index (item)}
    	<div animate:whizz>{item}</div>
    {/each}
    
    
    <script lang="ts">
    	import { cubicOut } from 'svelte/easing';
    
    	function whizz(node: HTMLElement, { from, to }: { from: DOMRect; to: DOMRect }, params: any) {
    		const dx = from.left - to.left;
    		const dy = from.top - to.top;
    
    		const d = Math.sqrt(dx * dx + dy * dy);
    
    		return {
    			delay: 0,
    			duration: Math.sqrt(d) * 120,
    			easing: cubicOut,
    			tick: (t, u) => Object.assign(node.style, { color: t > 0.5 ? 'Pink' : 'Blue' })
    		};
    	}
    </script>
    
    {#each list as item, index (item)}
    	<div animate:whizz>{item}</div>
    {/each}

# {#await ...}

### On this page

  * [{#await ...}](await)

    
    
    {#await expression}...{:then name}...{:catch name}...{/await}
    
    
    {#await expression}...{:then name}...{/await}
    
    
    {#await expression then name}...{/await}
    
    
    {#await expression catch name}...{/await}

Await blocks allow you to branch on the three possible states of a
[`Promise`](https://developer.mozilla.org/en-
US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — pending, fulfilled
or rejected.

    
    
    {#await promise}
    	<!-- promise is pending -->
    	<p>waiting for the promise to resolve...</p>
    {:then value}
    	<!-- promise was fulfilled or not a Promise -->
    	<p>The value is {value}</p>
    {:catch error}
    	<!-- promise was rejected -->
    	<p>Something went wrong: {error.message}</p>
    {/await}

> During server-side rendering, only the pending branch will be rendered.
>
> If the provided expression is not a `Promise`, only the `:then` branch will
> be rendered, including during server-side rendering.

The `catch` block can be omitted if you don’t need to render anything when the
promise rejects (or no error is possible).

    
    
    {#await promise}
    	<!-- promise is pending -->
    	<p>waiting for the promise to resolve...</p>
    {:then value}
    	<!-- promise was fulfilled -->
    	<p>The value is {value}</p>
    {/await}

If you don’t care about the pending state, you can also omit the initial
block.

    
    
    {#await promise then value}
    	<p>The value is {value}</p>
    {/await}

Similarly, if you only want to show the error state, you can omit the `then`
block.

    
    
    {#await promise catch error}
    	<p>The error is {error}</p>
    {/await}

> You can use `#await` with [`import(...)`](https://developer.mozilla.org/en-
> US/docs/Web/JavaScript/Reference/Operators/import) to render components
> lazily:
>  
>  
>     {#await import('./Component.svelte') then { default: Component }}
>       <Component />
>     {/await}

# Basic markup

### On this page

  * [Basic markup](basic-markup)
  * Tags
  * Element attributes
  * Component props
  * Spread attributes
  * Events
  * Text expressions
  * Comments

Markup inside a Svelte component can be thought of as HTML++.

##  Tags

A lowercase tag, like `<div>`, denotes a regular HTML element. A capitalised
tag or a tag that uses dot notation, such as `<Widget>` or `<my.stuff>`,
indicates a _component_.

    
    
    <script>
    	import Widget from './Widget.svelte';
    </script>
    
    <div>
    	<Widget />
    </div>

##  Element attributes

By default, attributes work exactly like their HTML counterparts.

    
    
    <div class="foo">
    	<button disabled>can't touch this</button>
    </div>

As in HTML, values may be unquoted.

    
    
    <input type=checkbox />

Attribute values can contain JavaScript expressions.

    
    
    <a href="page/{p}">page {p}</a>

Or they can _be_ JavaScript expressions.

    
    
    <button disabled={!clickable}>...</button>

Boolean attributes are included on the element if their value is
[truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy) and
excluded if it’s [falsy](https://developer.mozilla.org/en-
US/docs/Glossary/Falsy).

All other attributes are included unless their value is
[nullish](https://developer.mozilla.org/en-US/docs/Glossary/Nullish) (`null`
or `undefined`).

    
    
    <input required={false} placeholder="This input field is not required" />
    <div title={null}>This div has no title attribute</div>

> Quoting a singular expression does not affect how the value is parsed, but
> in Svelte 6 it will cause the value to be coerced to a string:
>  
>  
>     <button disabled="{number !== 42}">...</button>

When the attribute name and value match (`name={name}`), they can be replaced
with `{name}`.

    
    
    <button {disabled}>...</button>
    <!-- equivalent to
    <button disabled={disabled}>...</button>
    -->

##  Component props

By convention, values passed to components are referred to as _properties_ or
_props_ rather than _attributes_ , which are a feature of the DOM.

As with elements, `name={name}` can be replaced with the `{name}` shorthand.

    
    
    <Widget foo={bar} answer={42} text="hello" />

##  Spread attributes

_Spread attributes_ allow many attributes or properties to be passed to an
element or component at once.

An element or component can have multiple spread attributes, interspersed with
regular ones. Order matters — if `things.a` exists it will take precedence
over `a="b"`, while `c="d"` would take precedence over `things.c`:

    
    
    <Widget a="b" {...things} c="d" />

##  Events

Listening to DOM events is possible by adding attributes to the element that
start with `on`. For example, to listen to the `click` event, add the
`onclick` attribute to a button:

    
    
    <button onclick={() => console.log('clicked')}>click me</button>

Event attributes are case sensitive. `onclick` listens to the `click` event,
`onClick` listens to the `Click` event, which is different. This ensures you
can listen to custom events that have uppercase characters in them.

Because events are just attributes, the same rules as for attributes apply:

  * you can use the shorthand form: `<button {onclick}>click me</button>`
  * you can spread them: `<button {...thisSpreadContainsEventAttributes}>click me</button>`

Timing-wise, event attributes always fire after events from bindings (e.g.
`oninput` always fires after an update to `bind:value`). Under the hood, some
event handlers are attached directly with `addEventListener`, while others are
_delegated_.

When using `ontouchstart` and `ontouchmove` event attributes, the handlers are
[passive](https://developer.mozilla.org/en-
US/docs/Web/API/EventTarget/addEventListener#using_passive_listeners) for
better performance. This greatly improves responsiveness by allowing the
browser to scroll the document immediately, rather than waiting to see if the
event handler calls `event.preventDefault()`.

In the very rare cases that you need to prevent these event defaults, you
should use [`on`](svelte-events#on) instead (for example inside an action).

###  Event delegation

To reduce memory footprint and increase performance, Svelte uses a technique
called event delegation. This means that for certain events — see the list
below — a single event listener at the application root takes responsibility
for running any handlers on the event’s path.

There are a few gotchas to be aware of:

  * when you manually dispatch an event with a delegated listener, make sure to set the `{ bubbles: true }` option or it won’t reach the application root
  * when using `addEventListener` directly, avoid calling `stopPropagation` or the event won’t reach the application root and handlers won’t be invoked. Similarly, handlers added manually inside the application root will run _before_ handlers added declaratively deeper in the DOM (with e.g. `onclick={...}`), in both capturing and bubbling phases. For these reasons it’s better to use the `on` function imported from `svelte/events` rather than `addEventListener`, as it will ensure that order is preserved and `stopPropagation` is handled correctly.

The following event handlers are delegated:

  * `beforeinput`
  * `click`
  * `change`
  * `dblclick`
  * `contextmenu`
  * `focusin`
  * `focusout`
  * `input`
  * `keydown`
  * `keyup`
  * `mousedown`
  * `mousemove`
  * `mouseout`
  * `mouseover`
  * `mouseup`
  * `pointerdown`
  * `pointermove`
  * `pointerout`
  * `pointerover`
  * `pointerup`
  * `touchend`
  * `touchmove`
  * `touchstart`

##  Text expressions

A JavaScript expression can be included as text by surrounding it with curly
braces.

    
    
    {expression}

Expressions that are `null` or `undefined` will be omitted; all others are
[coerced to strings](https://developer.mozilla.org/en-
US/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion).

Curly braces can be included in a Svelte template by using their [HTML
entity](https://developer.mozilla.org/docs/Glossary/Entity) strings:
`&lbrace;`, `&lcub;`, or `&#123;` for `{` and `&rbrace;`, `&rcub;`, or
`&#125;` for `}`.

If you’re using a regular expression (`RegExp`) [literal
notation](https://developer.mozilla.org/en-
US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#literal_notation_and_constructor),
you’ll need to wrap it in parentheses.

    
    
    <h1>Hello {name}!</h1>
    <p>{a} + {b} = {a + b}.</p>
    
    <div>{(/^[A-Za-z ]+$/).test(value) ? x : y}</div>

The expression will be stringified and escaped to prevent code injections. If
you want to render HTML, use the `{@html}` tag instead.

    
    
    {@html potentiallyUnsafeHtmlString}

> Make sure that you either escape the passed string or only populate it with
> values that are under your control in order to prevent [XSS
> attacks](https://owasp.org/www-community/attacks/xss/)

##  Comments

You can use HTML comments inside components.

    
    
    <!-- this is a comment! --><h1>Hello world</h1>

Comments beginning with `svelte-ignore` disable warnings for the next block of
markup. Usually, these are accessibility warnings; make sure that you’re
disabling them for a good reason.

    
    
    <!-- svelte-ignore a11y_autofocus -->
    <input bind:value={name} autofocus />

You can add a special comment starting with `@component` that will show up
when hovering over the component name in other files.

    
    
    <!--
    @component
    - You can use markdown here.
    - You can also use code blocks here.
    - Usage:
      ```html
      <Main name="Arethra">
      ```
    -->
    <script>
    	let { name } = $props();
    </script>
    
    <main>
    	<h1>
    		Hello, {name}
    	</h1>
    </main>

# bind:

### On this page

  * [bind:](bind)
  * Function bindings
  * <input bind:value>
  * <input bind:checked>
  * <input bind:indeterminate>
  * <input bind:group>
  * <input bind:files>
  * <select bind:value>
  * <audio>
  * <video>
  * <img>
  * <details bind:open>
  * window and document
  * Contenteditable bindings
  * Dimensions
  * bind:this
  * bind:_property_ for components

Data ordinarily flows down, from parent to child. The `bind:` directive allows
data to flow the other way, from child to parent.

The general syntax is `bind:property={expression}`, where `expression` is an
[_lvalue_](https://press.rebus.community/programmingfundamentals/chapter/lvalue-
and-rvalue/) (i.e. a variable or an object property). When the expression is
an identifier with the same name as the property, we can omit the expression —
in other words these are equivalent:

    
    
    <input bind:value={value} />
    <input bind:value />

Svelte creates an event listener that updates the bound value. If an element
already has a listener for the same event, that listener will be fired before
the bound value is updated.

Most bindings are _two-way_ , meaning that changes to the value will affect
the element and vice versa. A few bindings are _readonly_ , meaning that
changing their value will have no effect on the element.

##  Function bindings

You can also use `bind:property={get, set}`, where `get` and `set` are
functions, allowing you to perform validation and transformation:

    
    
    <input bind:value={
    	() => value,
    	(v) => value = v.toLowerCase()}
    />

In the case of readonly bindings like dimension bindings, the `get` value
should be `null`:

    
    
    <div
    	bind:clientWidth={null, redraw}
    	bind:clientHeight={null, redraw}
    >...</div>

> Function bindings are available in Svelte 5.9.0 and newer.

##  <input bind:value>

A `bind:value` directive on an `<input>` element binds the input’s `value`
property:

    
    
    <script>
    	let message = $state('hello');
    </script>
    
    <input bind:value={message} />
    <p>{message}</p>

In the case of a numeric input (`type="number"` or `type="range"`), the value
will be coerced to a number
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE6WPwYoCMQxAfyWEPeyiOOqx2w74Hds9pBql0IllmhGXYf5dKqwiyILsLXnwwsuI-5i4oPkaUX8yo7kCnKNQV7dNzoty4qSVBSr8jG-
Poixa0KAt2z5mbb14TaxA4OCtKCm_rz4-f2m403WltrlrYhMFTtcLNkoeFGqZ8yhDF7j3CCHKzpwoDexGmqCL4jwuPUJHZ-
dxVcfmyYGe5MAv-La5pbxYFf5Z9Zf_UJXb-
sEMquFgJJhBmGyTW5yj8lnRaD_w9D1dAKSSj7zqAQAA)):

    
    
    <script>
    	let a = $state(1);
    	let b = $state(2);
    </script>
    
    <label>
    	<input type="number" bind:value={a} min="0" max="10" />
    	<input type="range" bind:value={a} min="0" max="10" />
    </label>
    
    <label>
    	<input type="number" bind:value={b} min="0" max="10" />
    	<input type="range" bind:value={b} min="0" max="10" />
    </label>
    
    <p>{a} + {b} = {a + b}</p>

If the input is empty or invalid (in the case of `type="number"`), the value
is `undefined`.

Since 5.6.0, if an `<input>` has a `defaultValue` and is part of a form, it
will revert to that value instead of the empty string when the form is reset.
Note that for the initial render the value of the binding takes precedence
unless it is `null` or `undefined`.

    
    
    <script>
    	let value = $state('');
    </script>
    
    <form>
    	<input bind:value defaultValue="not the empty string">
    	<input type="reset" value="Reset">
    </form>

> Use reset buttons sparingly, and ensure that users won’t accidentally click
> them while trying to submit the form.

##  <input bind:checked>

Checkbox and radio inputs can be bound with `bind:checked`:

    
    
    <label>
    	<input type="checkbox" bind:checked={accepted} />
    	Accept terms and conditions
    </label>

Since 5.6.0, if an `<input>` has a `defaultChecked` attribute and is part of a
form, it will revert to that value instead of `false` when the form is reset.
Note that for the initial render the value of the binding takes precedence
unless it is `null` or `undefined`.

    
    
    <script>
    	let checked = $state(true);
    </script>
    
    <form>
    	<input type="checkbox" bind:checked defaultChecked={true}>
    	<input type="reset" value="Reset">
    </form>

##  <input bind:indeterminate>

Checkboxes can be in an [indeterminate](https://developer.mozilla.org/en-
US/docs/Web/API/HTMLInputElement/indeterminate) state, independently of
whether they are checked or unchecked:

    
    
    <script>
    	let checked = $state(false);
    	let indeterminate = $state(true);
    </script>
    
    <form>
    	<input type="checkbox" bind:checked bind:indeterminate>
    
    	{#if indeterminate}
    		waiting...
    	{:else if checked}
    		checked
    	{:else}
    		unchecked
    	{/if}
    </form>

##  <input bind:group>

Inputs that work together can use `bind:group`
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE62T32_TMBDH_5XDQkpbrct7SCMGEvCEECDxsO7BSW6L2c227EvbKOv_jp0f6jYhQKJv5_P3PvdL1wstH1Bk4hMSGdgbRzUssFaM9VJciFtF6EV23QvubNRFR_BPUVfWXvodEkdfKT3-zl8Zzag5YETuK6csF1u9ZUIGNo4VkYQNvPYsGRfJF5JKJ8s3QRJE6WoFb2Nq6K-ck13u2Sl9Vxxhlc6QUBIFnz9Brm9ifJ6esun81XoNd860FmtwslYGlLYte5AO4aHlVhJ1gIeKWq92COt1iMtJlkhFPkgh1rHZiiF6K6BUus4G5KafGznCTlIbVUMfQZUWMJh5OrL-
C_qjMYSwb1DyiH7iOEuCb1ZpWTUjfHqcwC_GWDVY3ZfmME_SGttSmD9IHaYatvWHIc6xLyqad3mq6KuqcCwnWn9p8p-p71BqP2IH81zc9w2in-
od7XORP7ayCpd5YCeXI_-p59mObPF9WmwGpx3nqS2Gzw8TO3zOaS5_GqUXyQUkS3h8hOSz0ZhMESHGc0c4Hm3MAn00t1wrb0l2GZRkqvt4sXwczm6Qh8vnUJzI2LV4vAkvqWgfehTZrSSPx19WiVfFfAQAAA==)):

BurritoChooser

    
    
    <script>
    	let tortilla = $state('Plain');
    
    	/** @type {string[]} */
    	let fillings = $state([]);
    </script>
    
    <!-- grouped radio inputs are mutually exclusive -->
    <label><input type="radio" bind:group={tortilla} value="Plain" /> Plain</label>
    <label><input type="radio" bind:group={tortilla} value="Whole wheat" /> Whole wheat</label>
    <label><input type="radio" bind:group={tortilla} value="Spinach" /> Spinach</label>
    
    <!-- grouped checkbox inputs populate an array -->
    <label><input type="checkbox" bind:group={fillings} value="Rice" /> Rice</label>
    <label><input type="checkbox" bind:group={fillings} value="Beans" /> Beans</label>
    <label><input type="checkbox" bind:group={fillings} value="Cheese" /> Cheese</label>
    <label><input type="checkbox" bind:group={fillings} value="Guac (extra)" /> Guac (extra)</label>
    
    
    <script lang="ts">
    	let tortilla = $state('Plain');
    	let fillings: string[] = $state([]);
    </script>
    
    <!-- grouped radio inputs are mutually exclusive -->
    <label><input type="radio" bind:group={tortilla} value="Plain" /> Plain</label>
    <label><input type="radio" bind:group={tortilla} value="Whole wheat" /> Whole wheat</label>
    <label><input type="radio" bind:group={tortilla} value="Spinach" /> Spinach</label>
    
    <!-- grouped checkbox inputs populate an array -->
    <label><input type="checkbox" bind:group={fillings} value="Rice" /> Rice</label>
    <label><input type="checkbox" bind:group={fillings} value="Beans" /> Beans</label>
    <label><input type="checkbox" bind:group={fillings} value="Cheese" /> Cheese</label>
    <label><input type="checkbox" bind:group={fillings} value="Guac (extra)" /> Guac (extra)</label>

> `bind:group` only works if the inputs are in the same Svelte component.

##  <input bind:files>

On `<input>` elements with `type="file"`, you can use `bind:files` to get the
[`FileList` of selected files](https://developer.mozilla.org/en-
US/docs/Web/API/FileList). When you want to update the files programmatically,
you always need to use a `FileList` object. Currently `FileList` objects
cannot be constructed directly, so you need to create a new
[`DataTransfer`](https://developer.mozilla.org/en-
US/docs/Web/API/DataTransfer) object and get `files` from there.

    
    
    <script>
    	let files = $state();
    
    	function clear() {
    		files = new DataTransfer().files; // null or undefined does not work
    	}
    </script>
    
    <label for="avatar">Upload a picture:</label>
    <input accept="image/png, image/jpeg" bind:files id="avatar" name="avatar" type="file" />
    <button onclick={clear}>clear</button>

`FileList` objects also cannot be modified, so if you want to e.g. delete a
single file from the list, you need to create a new `DataTransfer` object and
add the files you want to keep.

> `DataTransfer` may not be available in server-side JS runtimes. Leaving the
> state that is bound to `files` uninitialized prevents potential errors if
> components are server-side rendered.

##  <select bind:value>

A `<select>` value binding corresponds to the `value` property on the selected
`<option>`, which can be any value (not just strings, as is normally the case
in the DOM).

    
    
    <select bind:value={selected}>
    	<option value={a}>a</option>
    	<option value={b}>b</option>
    	<option value={c}>c</option>
    </select>

A `<select multiple>` element behaves similarly to a checkbox group. The bound
variable is an array with an entry corresponding to the `value` property of
each selected `<option>`.

    
    
    <select multiple bind:value={fillings}>
    	<option value="Rice">Rice</option>
    	<option value="Beans">Beans</option>
    	<option value="Cheese">Cheese</option>
    	<option value="Guac (extra)">Guac (extra)</option>
    </select>

When the value of an `<option>` matches its text content, the attribute can be
omitted.

    
    
    <select multiple bind:value={fillings}>
    	<option>Rice</option>
    	<option>Beans</option>
    	<option>Cheese</option>
    	<option>Guac (extra)</option>
    </select>

You can give the `<select>` a default value by adding a `selected` attribute
to the`<option>` (or options, in the case of `<select multiple>`) that should
be initially selected. If the `<select>` is part of a form, it will revert to
that selection when the form is reset. Note that for the initial render the
value of the binding takes precedence if it’s not `undefined`.

    
    
    <select bind:value={selected}>
    	<option value={a}>a</option>
    	<option value={b} selected>b</option>
    	<option value={c}>c</option>
    </select>

##  <audio>

`<audio>` elements have their own set of bindings — five two-way ones...

  * [`currentTime`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/currentTime)
  * [`playbackRate`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/playbackRate)
  * [`paused`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/paused)
  * [`volume`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/volume)
  * [`muted`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/muted)

...and six readonly ones:

  * [`duration`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/duration)
  * [`buffered`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/buffered)
  * [`seekable`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/seekable)
  * [`seeking`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/seeking_event)
  * [`ended`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/ended)
  * [`readyState`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/readyState)
  * [`played`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/played)

    
    
    <audio src={clip} bind:duration bind:currentTime bind:paused></audio>

##  <video>

`<video>` elements have all the same bindings as `<audio>` elements, plus
readonly [`videoWidth`](https://developer.mozilla.org/en-
US/docs/Web/API/HTMLVideoElement/videoWidth) and
[`videoHeight`](https://developer.mozilla.org/en-
US/docs/Web/API/HTMLVideoElement/videoHeight) bindings.

##  <img>

`<img>` elements have two readonly bindings:

  * [`naturalWidth`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/naturalWidth)
  * [`naturalHeight`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/naturalHeight)

##  <details bind:open>

`<details>` elements support binding to the `open` property.

    
    
    <details bind:open={isOpen}>
    	<summary>How do you comfort a JavaScript bug?</summary>
    	<p>You console it.</p>
    </details>

##  window and document

To bind to properties of `window` and `document`, see
[`<svelte:window>`](svelte-window) and [`<svelte:document>`](svelte-document).

##  Contenteditable bindings

Elements with the `contenteditable` attribute support the following bindings:

  * [`innerHTML`](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML)
  * [`innerText`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText)
  * [`textContent`](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent)

> There are [subtle differences between `innerText` and
> `textContent`](https://developer.mozilla.org/en-
> US/docs/Web/API/Node/textContent#differences_from_innertext).
    
    
    <div contenteditable="true" bind:innerHTML={html}></div>

##  Dimensions

All visible elements have the following readonly bindings, measured with a
`ResizeObserver`:

  * [`clientWidth`](https://developer.mozilla.org/en-US/docs/Web/API/Element/clientWidth)
  * [`clientHeight`](https://developer.mozilla.org/en-US/docs/Web/API/Element/clientHeight)
  * [`offsetWidth`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetWidth)
  * [`offsetHeight`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetHeight)
  * [`contentRect`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry/contentRect)
  * [`contentBoxSize`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry/contentBoxSize)
  * [`borderBoxSize`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry/borderBoxSize)
  * [`devicePixelContentBoxSize`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry/devicePixelContentBoxSize)

    
    
    <div bind:offsetWidth={width} bind:offsetHeight={height}>
    	<Chart {width} {height} />
    </div>

> `display: inline` elements do not have a width or height (except for
> elements with ‘intrinsic’ dimensions, like `<img>` and `<canvas>`), and
> cannot be observed with a `ResizeObserver`. You will need to change the
> `display` style of these elements to something else, such as `inline-block`.
> Note that CSS transformations do not trigger `ResizeObserver` callbacks.

##  bind:this

    
    
    bind:this={dom_node}

To get a reference to a DOM node, use `bind:this`. The value will be
`undefined` until the component is mounted — in other words, you should read
it inside an effect or an event handler, but not during component
initialisation:

    
    
    <script>
    	/** @type {HTMLCanvasElement} */
    	let canvas;
    
    	$effect(() => {
    		const ctx = canvas.getContext('2d');
    		drawStuff(ctx);
    	});
    </script>
    
    <canvas bind:this={canvas}></canvas>

Components also support `bind:this`, allowing you to interact with component
instances programmatically.

App

    
    
    <ShoppingCart bind:this={cart} />
    
    <button onclick={() => cart.empty()}> Empty shopping cart </button>

ShoppingCart

    
    
    <script>
    	// All instance exports are available on the instance object
    	export function empty() {
    		// ...
    	}
    </script>
    
    
    <script lang="ts">
    	// All instance exports are available on the instance object
    	export function empty() {
    		// ...
    	}
    </script>

##  bind:_property_ for components

    
    
    bind:property={variable}

You can bind to component props using the same syntax as for elements.

    
    
    <Keypad bind:value={pin} />

While Svelte props are reactive without binding, that reactivity only flows
downward into the component by default. Using `bind:property` allows changes
to the property from within the component to flow back up out of the
component.

To mark a property as bindable, use the [`$bindable`]($bindable) rune:

    
    
    <script>
    	let { readonlyProperty, bindableProperty = $bindable() } = $props();
    </script>

Declaring a property as bindable means it _can_ be used using `bind:`, not
that it _must_ be used using `bind:`.

Bindable properties can have a fallback value:

    
    
    <script>
    	let { bindableProperty = $bindable('fallback value') } = $props();
    </script>

This fallback value _only_ applies when the property is _not_ bound. When the
property is bound and a fallback value is present, the parent is expected to
provide a value other than `undefined`, else a runtime error is thrown. This
prevents hard-to-reason-about situations where it’s unclear which value should
apply.

# class

### On this page

  * [class](class)
  * Attributes
  * The class: directive

There are two ways to set classes on elements: the `class` attribute, and the
`class:` directive.

##  Attributes

Primitive values are treated like any other attribute:

    
    
    <div class={large ? 'large' : 'small'}>...</div>

> For historical reasons, falsy values (like `false` and `NaN`) are
> stringified (`class="false"`), though `class={undefined}` (or `null`) cause
> the attribute to be omitted altogether. In a future version of Svelte, all
> falsy values will cause `class` to be omitted.

###  Objects and arrays

Since Svelte 5.16, `class` can be an object or array, and is converted to a
string using [clsx](https://github.com/lukeed/clsx).

If the value is an object, the truthy keys are added:

    
    
    <script>
    	let { cool } = $props();
    </script>
    
    <!-- results in `class="cool"` if `cool` is truthy,
    	 `class="lame"` otherwise -->
    <div class={{ cool, lame: !cool }}>...</div>

If the value is an array, the truthy values are combined:

    
    
    <!-- if `faded` and `large` are both truthy, results in
    	 `class="saturate-0 opacity-50 scale-200"` -->
    <div class={[faded && 'saturate-0 opacity-50', large && 'scale-200']}>...</div>

Note that whether we’re using the array or object form, we can set multiple
classes simultaneously with a single condition, which is particularly useful
if you’re using things like Tailwind.

Arrays can contain arrays and objects, and clsx will flatten them. This is
useful for combining local classes with props, for example:

Button

    
    
    <script>
    	let props = $props();
    </script>
    
    <button {...props} class={['cool-button', props.class]}>
    	{@render props.children?.()}
    </button>
    
    
    <script lang="ts">
    	let props = $props();
    </script>
    
    <button {...props} class={['cool-button', props.class]}>
    	{@render props.children?.()}
    </button>

The user of this component has the same flexibility to use a mixture of
objects, arrays and strings:

App

    
    
    <script>
    	import Button from './Button.svelte';
    	let useTailwind = $state(false);
    </script>
    
    <Button
    	onclick={() => useTailwind = true}
    	class={{ 'bg-blue-700 sm:w-1/2': useTailwind }}
    >
    	Accept the inevitability of Tailwind
    </Button>
    
    
    <script lang="ts">
    	import Button from './Button.svelte';
    	let useTailwind = $state(false);
    </script>
    
    <Button
    	onclick={() => useTailwind = true}
    	class={{ 'bg-blue-700 sm:w-1/2': useTailwind }}
    >
    	Accept the inevitability of Tailwind
    </Button>

Svelte also exposes the `ClassValue` type, which is the type of value that the
`class` attribute on elements accept. This is useful if you want to use a
type-safe class name in component props:

    
    
    <script lang="ts">
    	import type { ClassValue } from 'svelte/elements';
    
    	const props: { class: ClassValue } = $props();
    </script>
    
    <div class={['original', props.class]}>...</div>

##  The class: directive

Prior to Svelte 5.16, the `class:` directive was the most convenient way to
set classes on elements conditionally.

    
    
    <!-- These are equivalent -->
    <div class={{ cool, lame: !cool }}>...</div>
    <div class:cool={cool} class:lame={!cool}>...</div>

As with other directives, we can use a shorthand when the name of the class
coincides with the value:

    
    
    <div class:cool class:lame={!cool}>...</div>

> Unless you’re using an older version of Svelte, consider avoiding `class:`,
> since the attribute is more powerful and composable.

# Compiler errors

### On this page

  * [Compiler errors](compiler-errors)

###  animation_duplicate

    
    
    An element can only have one 'animate' directive

###  animation_invalid_placement

    
    
    An element that uses the `animate:` directive must be the only child of a keyed `{#each ...}` block

###  animation_missing_key

    
    
    An element that uses the `animate:` directive must be the only child of a keyed `{#each ...}` block. Did you forget to add a key to your each block?

###  attribute_contenteditable_dynamic

    
    
    'contenteditable' attribute cannot be dynamic if element uses two-way binding

###  attribute_contenteditable_missing

    
    
    'contenteditable' attribute is required for textContent, innerHTML and innerText two-way bindings

###  attribute_duplicate

    
    
    Attributes need to be unique

###  attribute_empty_shorthand

    
    
    Attribute shorthand cannot be empty

###  attribute_invalid_event_handler

    
    
    Event attribute must be a JavaScript expression, not a string

###  attribute_invalid_multiple

    
    
    'multiple' attribute must be static if select uses two-way binding

###  attribute_invalid_name

    
    
    '%name%' is not a valid attribute name

###  attribute_invalid_sequence_expression

    
    
    Sequence expressions are not allowed as attribute/directive values in runes mode, unless wrapped in parentheses

###  attribute_invalid_type

    
    
    'type' attribute must be a static text value if input uses two-way binding

###  attribute_unquoted_sequence

    
    
    Attribute values containing `{...}` must be enclosed in quote marks, unless the value only contains the expression

###  bind_group_invalid_expression

    
    
    `bind:group` can only bind to an Identifier or MemberExpression

###  bind_group_invalid_snippet_parameter

    
    
    Cannot `bind:group` to a snippet parameter

###  bind_invalid_expression

    
    
    Can only bind to an Identifier or MemberExpression or a `{get, set}` pair

###  bind_invalid_name

    
    
    `bind:%name%` is not a valid binding
    
    
    `bind:%name%` is not a valid binding. %explanation%

###  bind_invalid_parens

    
    
    `bind:%name%={get, set}` must not have surrounding parentheses

###  bind_invalid_target

    
    
    `bind:%name%` can only be used with %elements%

###  bind_invalid_value

    
    
    Can only bind to state or props

###  bindable_invalid_location

    
    
    `$bindable()` can only be used inside a `$props()` declaration

###  block_duplicate_clause

    
    
    %name% cannot appear more than once within a block

###  block_invalid_continuation_placement

    
    
    {:...} block is invalid at this position (did you forget to close the preceding element or block?)

###  block_invalid_elseif

    
    
    'elseif' should be 'else if'

###  block_invalid_placement

    
    
    {#%name% ...} block cannot be %location%

###  block_unclosed

    
    
    Block was left open

###  block_unexpected_character

    
    
    Expected a `%character%` character immediately following the opening bracket

###  block_unexpected_close

    
    
    Unexpected block closing tag

###  component_invalid_directive

    
    
    This type of directive is not valid on components

###  const_tag_cycle

    
    
    Cyclical dependency detected: %cycle%

###  const_tag_invalid_expression

    
    
    {@const ...} must consist of a single variable declaration

###  const_tag_invalid_placement

    
    
    `{@const}` must be the immediate child of `{#snippet}`, `{#if}`, `{:else if}`, `{:else}`, `{#each}`, `{:then}`, `{:catch}`, `<svelte:fragment>`, `<svelte:boundary` or `<Component>`

###  constant_assignment

    
    
    Cannot assign to %thing%

###  constant_binding

    
    
    Cannot bind to %thing%

###  css_empty_declaration

    
    
    Declaration cannot be empty

###  css_expected_identifier

    
    
    Expected a valid CSS identifier

###  css_global_block_invalid_combinator

    
    
    A `:global` selector cannot follow a `%name%` combinator

###  css_global_block_invalid_declaration

    
    
    A top-level `:global {...}` block can only contain rules, not declarations

###  css_global_block_invalid_list

    
    
    A `:global` selector cannot be part of a selector list with entries that don't contain `:global`

The following CSS is invalid:

    
    
    :global, x {
    	y {
    		color: red;
    	}
    }

This is mixing a `:global` block, which means “everything in here is
unscoped”, with a scoped selector (`x` in this case). As a result it’s not
possible to transform the inner selector (`y` in this case) into something
that satisfies both requirements. You therefore have to split this up into two
selectors:

    
    
    :global {
    	y {
    		color: red;
    	}
    }
    
    x y {
    	color: red;
    }

###  css_global_block_invalid_modifier

    
    
    A `:global` selector cannot modify an existing selector

###  css_global_block_invalid_modifier_start

    
    
    A `:global` selector can only be modified if it is a descendant of other selectors

###  css_global_block_invalid_placement

    
    
    A `:global` selector cannot be inside a pseudoclass

###  css_global_invalid_placement

    
    
    `:global(...)` can be at the start or end of a selector sequence, but not in the middle

###  css_global_invalid_selector

    
    
    `:global(...)` must contain exactly one selector

###  css_global_invalid_selector_list

    
    
    `:global(...)` must not contain type or universal selectors when used in a compound selector

###  css_nesting_selector_invalid_placement

    
    
    Nesting selectors can only be used inside a rule or as the first selector inside a lone `:global(...)`

###  css_selector_invalid

    
    
    Invalid selector

###  css_type_selector_invalid_placement

    
    
    `:global(...)` must not be followed by a type selector

###  debug_tag_invalid_arguments

    
    
    {@debug ...} arguments must be identifiers, not arbitrary expressions

###  declaration_duplicate

    
    
    `%name%` has already been declared

###  declaration_duplicate_module_import

    
    
    Cannot declare a variable with the same name as an import inside `<script module>`

###  derived_invalid_export

    
    
    Cannot export derived state from a module. To expose the current derived value, export a function returning its value

###  directive_invalid_value

    
    
    Directive value must be a JavaScript expression enclosed in curly braces

###  directive_missing_name

    
    
    `%type%` name cannot be empty

###  dollar_binding_invalid

    
    
    The $ name is reserved, and cannot be used for variables and imports

###  dollar_prefix_invalid

    
    
    The $ prefix is reserved, and cannot be used for variables and imports

###  each_item_invalid_assignment

    
    
    Cannot reassign or bind to each block argument in runes mode. Use the array and index variables instead (e.g. `array[i] = value` instead of `entry = value`, or `bind:value={array[i]}` instead of `bind:value={entry}`)

In legacy mode, it was possible to reassign or bind to the each block argument
itself:

    
    
    <script>
    	let array = [1, 2, 3];
    </script>
    
    {#each array as entry}
    	<!-- reassignment -->
    	<button on:click={() => entry = 4}>change</button>
    
    	<!-- binding -->
    	<input bind:value={entry}>
    {/each}

This turned out to be buggy and unpredictable, particularly when working with
derived values (such as `array.map(...)`), and as such is forbidden in runes
mode. You can achieve the same outcome by using the index instead:

    
    
    <script>
    	let array = $state([1, 2, 3]);
    </script>
    
    {#each array as entry, i}
    	<!-- reassignment -->
    	<button onclick={() => array[i] = 4}>change</button>
    
    	<!-- binding -->
    	<input bind:value={array[i]}>
    {/each}

###  effect_invalid_placement

    
    
    `$effect()` can only be used as an expression statement

###  element_invalid_closing_tag

    
    
    `</%name%>` attempted to close an element that was not open

###  element_invalid_closing_tag_autoclosed

    
    
    `</%name%>` attempted to close element that was already automatically closed by `<%reason%>` (cannot nest `<%reason%>` inside `<%name%>`)

###  element_unclosed

    
    
    `<%name%>` was left open

###  event_handler_invalid_component_modifier

    
    
    Event modifiers other than 'once' can only be used on DOM elements

###  event_handler_invalid_modifier

    
    
    Valid event modifiers are %list%

###  event_handler_invalid_modifier_combination

    
    
    The '%modifier1%' and '%modifier2%' modifiers cannot be used together

###  expected_attribute_value

    
    
    Expected attribute value

###  expected_block_type

    
    
    Expected 'if', 'each', 'await', 'key' or 'snippet'

###  expected_identifier

    
    
    Expected an identifier

###  expected_pattern

    
    
    Expected identifier or destructure pattern

###  expected_token

    
    
    Expected token %token%

###  expected_whitespace

    
    
    Expected whitespace

###  export_undefined

    
    
    `%name%` is not defined

###  global_reference_invalid

    
    
    `%name%` is an illegal variable name. To reference a global variable called `%name%`, use `globalThis.%name%`

###  host_invalid_placement

    
    
    `$host()` can only be used inside custom element component instances

###  illegal_element_attribute

    
    
    `<%name%>` does not support non-event attributes or spread attributes

###  import_svelte_internal_forbidden

    
    
    Imports of `svelte/internal/*` are forbidden. It contains private runtime code which is subject to change without notice. If you're importing from `svelte/internal/*` to work around a limitation of Svelte, please open an issue at https://github.com/sveltejs/svelte and explain your use case

###  inspect_trace_generator

    
    
    `$inspect.trace(...)` cannot be used inside a generator function

###  inspect_trace_invalid_placement

    
    
    `$inspect.trace(...)` must be the first statement of a function body

###  invalid_arguments_usage

    
    
    The arguments keyword cannot be used within the template or at the top level of a component

###  js_parse_error

    
    
    %message%

###  legacy_export_invalid

    
    
    Cannot use `export let` in runes mode — use `$props()` instead

###  legacy_props_invalid

    
    
    Cannot use `$$props` in runes mode

###  legacy_reactive_statement_invalid

    
    
    `$:` is not allowed in runes mode, use `$derived` or `$effect` instead

###  legacy_rest_props_invalid

    
    
    Cannot use `$$restProps` in runes mode

###  let_directive_invalid_placement

    
    
    `let:` directive at invalid position

###  mixed_event_handler_syntaxes

    
    
    Mixing old (on:%name%) and new syntaxes for event handling is not allowed. Use only the on%name% syntax

###  module_illegal_default_export

    
    
    A component cannot have a default export

###  node_invalid_placement

    
    
    %message%. The browser will 'repair' the HTML (by moving, removing, or inserting elements) which breaks Svelte's assumptions about the structure of your components.

HTML restricts where certain elements can appear. In case of a violation the
browser will ‘repair’ the HTML in a way that breaks Svelte’s assumptions about
the structure of your components. Some examples:

  * `<p>hello <div>world</div></p>` will result in `<p>hello </p><div>world</div><p></p>` (the `<div>` autoclosed the `<p>` because `<p>` cannot contain block-level elements)
  * `<option><div>option a</div></option>` will result in `<option>option a</option>` (the `<div>` is removed)
  * `<table><tr><td>cell</td></tr></table>` will result in `<table><tbody><tr><td>cell</td></tr></tbody></table>` (a `<tbody>` is auto-inserted)

###  options_invalid_value

    
    
    Invalid compiler option: %details%

###  options_removed

    
    
    Invalid compiler option: %details%

###  options_unrecognised

    
    
    Unrecognised compiler option %keypath%

###  props_duplicate

    
    
    Cannot use `%rune%()` more than once

###  props_id_invalid_placement

    
    
    `$props.id()` can only be used at the top level of components as a variable declaration initializer

###  props_illegal_name

    
    
    Declaring or accessing a prop starting with `$$` is illegal (they are reserved for Svelte internals)

###  props_invalid_identifier

    
    
    `$props()` can only be used with an object destructuring pattern

###  props_invalid_pattern

    
    
    `$props()` assignment must not contain nested properties or computed keys

###  props_invalid_placement

    
    
    `$props()` can only be used at the top level of components as a variable declaration initializer

###  reactive_declaration_cycle

    
    
    Cyclical dependency detected: %cycle%

###  render_tag_invalid_call_expression

    
    
    Calling a snippet function using apply, bind or call is not allowed

###  render_tag_invalid_expression

    
    
    `{@render ...}` tags can only contain call expressions

###  render_tag_invalid_spread_argument

    
    
    cannot use spread arguments in `{@render ...}` tags

###  rune_invalid_arguments

    
    
    `%rune%` cannot be called with arguments

###  rune_invalid_arguments_length

    
    
    `%rune%` must be called with %args%

###  rune_invalid_computed_property

    
    
    Cannot access a computed property of a rune

###  rune_invalid_name

    
    
    `%name%` is not a valid rune

###  rune_invalid_spread

    
    
    `%rune%` cannot be called with a spread argument

###  rune_invalid_usage

    
    
    Cannot use `%rune%` rune in non-runes mode

###  rune_missing_parentheses

    
    
    Cannot use rune without parentheses

###  rune_removed

    
    
    The `%name%` rune has been removed

###  rune_renamed

    
    
    `%name%` is now `%replacement%`

###  runes_mode_invalid_import

    
    
    %name% cannot be used in runes mode

###  script_duplicate

    
    
    A component can have a single top-level `<script>` element and/or a single top-level `<script module>` element

###  script_invalid_attribute_value

    
    
    If the `%name%` attribute is supplied, it must be a boolean attribute

###  script_invalid_context

    
    
    If the context attribute is supplied, its value must be "module"

###  script_reserved_attribute

    
    
    The `%name%` attribute is reserved and cannot be used

###  slot_attribute_duplicate

    
    
    Duplicate slot name '%name%' in <%component%>

###  slot_attribute_invalid

    
    
    slot attribute must be a static value

###  slot_attribute_invalid_placement

    
    
    Element with a slot='...' attribute must be a child of a component or a descendant of a custom element

###  slot_default_duplicate

    
    
    Found default slot content alongside an explicit slot="default"

###  slot_element_invalid_attribute

    
    
    `<slot>` can only receive attributes and (optionally) let directives

###  slot_element_invalid_name

    
    
    slot attribute must be a static value

###  slot_element_invalid_name_default

    
    
    `default` is a reserved word — it cannot be used as a slot name

###  slot_snippet_conflict

    
    
    Cannot use `<slot>` syntax and `{@render ...}` tags in the same component. Migrate towards `{@render ...}` tags completely

###  snippet_conflict

    
    
    Cannot use explicit children snippet at the same time as implicit children content. Remove either the non-whitespace content or the children snippet block

###  snippet_invalid_export

    
    
    An exported snippet can only reference things declared in a `<script module>`, or other exportable snippets

It’s possible to export a snippet from a `<script module>` block, but only if
it doesn’t reference anything defined inside a non-module-level `<script>`.
For example you can’t do this...

    
    
    <script module>
    	export { greeting };
    </script>
    
    <script>
    	let message = 'hello';
    </script>
    
    {#snippet greeting(name)}
    	<p>{message} {name}!</p>
    {/snippet}

...because `greeting` references `message`, which is defined in the second
`<script>`.

###  snippet_invalid_rest_parameter

    
    
    Snippets do not support rest parameters; use an array instead

###  snippet_parameter_assignment

    
    
    Cannot reassign or bind to snippet parameter

###  snippet_shadowing_prop

    
    
    This snippet is shadowing the prop `%prop%` with the same name

###  state_field_duplicate

    
    
    `%name%` has already been declared on this class

An assignment to a class field that uses a `$state` or `$derived` rune is
considered a _state field declaration_. The declaration can happen in the
class body...

    
    
    class Counter {
    	count = $state(0);
    }

...or inside the constructor...

    
    
    class Counter {
    	constructor() {
    		this.count = $state(0);
    	}
    }

...but it can only happen once.

###  state_field_invalid_assignment

    
    
    Cannot assign to a state field before its declaration

###  state_invalid_export

    
    
    Cannot export state from a module if it is reassigned. Either export a function returning the state value or only mutate the state value's properties

###  state_invalid_placement

    
    
    `%rune%(...)` can only be used as a variable declaration initializer, a class field declaration, or the first assignment to a class field at the top level of the constructor.

###  store_invalid_scoped_subscription

    
    
    Cannot subscribe to stores that are not declared at the top level of the component

###  store_invalid_subscription

    
    
    Cannot reference store value inside `<script module>`

###  store_invalid_subscription_module

    
    
    Cannot reference store value outside a `.svelte` file

Using a `$` prefix to refer to the value of a store is only possible inside
`.svelte` files, where Svelte can automatically create subscriptions when a
component is mounted and unsubscribe when the component is unmounted. Consider
migrating to runes instead.

###  style_directive_invalid_modifier

    
    
    `style:` directive can only use the `important` modifier

###  style_duplicate

    
    
    A component can have a single top-level `<style>` element

###  svelte_body_illegal_attribute

    
    
    `<svelte:body>` does not support non-event attributes or spread attributes

###  svelte_boundary_invalid_attribute

    
    
    Valid attributes on `<svelte:boundary>` are `onerror` and `failed`

###  svelte_boundary_invalid_attribute_value

    
    
    Attribute value must be a non-string expression

###  svelte_component_invalid_this

    
    
    Invalid component definition — must be an `{expression}`

###  svelte_component_missing_this

    
    
    `<svelte:component>` must have a 'this' attribute

###  svelte_element_missing_this

    
    
    `<svelte:element>` must have a 'this' attribute with a value

###  svelte_fragment_invalid_attribute

    
    
    `<svelte:fragment>` can only have a slot attribute and (optionally) a let: directive

###  svelte_fragment_invalid_placement

    
    
    `<svelte:fragment>` must be the direct child of a component

###  svelte_head_illegal_attribute

    
    
    `<svelte:head>` cannot have attributes nor directives

###  svelte_meta_duplicate

    
    
    A component can only have one `<%name%>` element

###  svelte_meta_invalid_content

    
    
    <%name%> cannot have children

###  svelte_meta_invalid_placement

    
    
    `<%name%>` tags cannot be inside elements or blocks

###  svelte_meta_invalid_tag

    
    
    Valid `<svelte:...>` tag names are %list%

###  svelte_options_deprecated_tag

    
    
    "tag" option is deprecated — use "customElement" instead

###  svelte_options_invalid_attribute

    
    
    `<svelte:options>` can only receive static attributes

###  svelte_options_invalid_attribute_value

    
    
    Value must be %list%, if specified

###  svelte_options_invalid_customelement

    
    
    "customElement" must be a string literal defining a valid custom element name or an object of the form { tag?: string; shadow?: "open" | "none"; props?: { [key: string]: { attribute?: string; reflect?: boolean; type: .. } } }

###  svelte_options_invalid_customelement_props

    
    
    "props" must be a statically analyzable object literal of the form "{ [key: string]: { attribute?: string; reflect?: boolean; type?: "String" | "Boolean" | "Number" | "Array" | "Object" }"

###  svelte_options_invalid_customelement_shadow

    
    
    "shadow" must be either "open" or "none"

###  svelte_options_invalid_tagname

    
    
    Tag name must be lowercase and hyphenated

See <https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-
element-name> for more information on valid tag names

###  svelte_options_reserved_tagname

    
    
    Tag name is reserved

See <https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-
element-name> for more information on valid tag names

###  svelte_options_unknown_attribute

    
    
    `<svelte:options>` unknown attribute '%name%'

###  svelte_self_invalid_placement

    
    
    `<svelte:self>` components can only exist inside `{#if}` blocks, `{#each}` blocks, `{#snippet}` blocks or slots passed to components

###  tag_invalid_name

    
    
    Expected a valid element or component name. Components must have a valid variable name or dot notation expression

###  tag_invalid_placement

    
    
    {@%name% ...} tag cannot be %location%

###  textarea_invalid_content

    
    
    A `<textarea>` can have either a value attribute or (equivalently) child content, but not both

###  title_illegal_attribute

    
    
    `<title>` cannot have attributes nor directives

###  title_invalid_content

    
    
    `<title>` can only contain text and {tags}

###  transition_conflict

    
    
    Cannot use `%type%:` alongside existing `%existing%:` directive

###  transition_duplicate

    
    
    Cannot use multiple `%type%:` directives on a single element

###  typescript_invalid_feature

    
    
    TypeScript language features like %feature% are not natively supported, and their use is generally discouraged. Outside of `<script>` tags, these features are not supported. For use within `<script>` tags, you will need to use a preprocessor to convert it to JavaScript before it gets passed to the Svelte compiler. If you are using `vitePreprocess`, make sure to specifically enable preprocessing script tags (`vitePreprocess({ script: true })`)

###  unexpected_eof

    
    
    Unexpected end of input

###  unexpected_reserved_word

    
    
    '%word%' is a reserved word in JavaScript and cannot be used here

###  unterminated_string_constant

    
    
    Unterminated string constant

###  void_element_invalid_content

    
    
    Void elements cannot have children or closing tags

# Compiler warnings

### On this page

  * [Compiler warnings](compiler-warnings)

Svelte warns you at compile time if it catches potential mistakes, such as
writing inaccessible markup.

Some warnings may be incorrect in your concrete use case. You can disable such
false positives by placing a `<!-- svelte-ignore <code> -->` comment above the
line that causes the warning. Example:

    
    
    <!-- svelte-ignore a11y_autofocus -->
    <input autofocus />

You can list multiple rules in a single comment (separated by commas), and add
an explanatory note (in parentheses) alongside them:

    
    
    <!-- svelte-ignore a11y_click_events_have_key_events, a11y_no_static_element_interactions (because of reasons) -->
    <div onclick>...</div>

###  a11y_accesskey

    
    
    Avoid using accesskey

Enforce no `accesskey` on element. Access keys are HTML attributes that allow
web developers to assign keyboard shortcuts to elements. Inconsistencies
between keyboard shortcuts and keyboard commands used by screen reader and
keyboard-only users create accessibility complications. To avoid
complications, access keys should not be used.

    
    
    <!-- A11y: Avoid using accesskey -->
    <div accesskey="z"></div>

###  a11y_aria_activedescendant_has_tabindex

    
    
    An element with an aria-activedescendant attribute should have a tabindex value

An element with `aria-activedescendant` must be tabbable, so it must either
have an inherent `tabindex` or declare `tabindex` as an attribute.

    
    
    <!-- A11y: Elements with attribute aria-activedescendant should have tabindex value -->
    <div aria-activedescendant="some-id"></div>

###  a11y_aria_attributes

    
    
    `<%name%>` should not have aria-* attributes

Certain reserved DOM elements do not support ARIA roles, states and
properties. This is often because they are not visible, for example `meta`,
`html`, `script`, `style`. This rule enforces that these DOM elements do not
contain the `aria-*` props.

    
    
    <!-- A11y: <meta> should not have aria-* attributes -->
    <meta aria-hidden="false" />

###  a11y_autocomplete_valid

    
    
    '%value%' is an invalid value for 'autocomplete' on `<input type="%type%">`

###  a11y_autofocus

    
    
    Avoid using autofocus

Enforce that `autofocus` is not used on elements. Autofocusing elements can
cause usability issues for sighted and non-sighted users alike.

    
    
    <!-- A11y: Avoid using autofocus -->
    <input autofocus />

###  a11y_click_events_have_key_events

    
    
    Visible, non-interactive elements with a click event must be accompanied by a keyboard event handler. Consider whether an interactive element such as `<button type="button">` or `<a>` might be more appropriate

Enforce that visible, non-interactive elements with an `onclick` event are
accompanied by a keyboard event handler.

Users should first consider whether an interactive element might be more
appropriate such as a `<button type="button">` element for actions or `<a>`
element for navigations. These elements are more semantically meaningful and
will have built-in key handling. E.g. `Space` and `Enter` will trigger a
`<button>` and `Enter` will trigger an `<a>` element.

If a non-interactive element is required then `onclick` should be accompanied
by an `onkeyup` or `onkeydown` handler that enables the user to perform
equivalent actions via the keyboard. In order for the user to be able to
trigger a key press, the element will also need to be focusable by adding a
[`tabindex`](https://developer.mozilla.org/en-
US/docs/Web/HTML/Global_attributes/tabindex). While an `onkeypress` handler
will also silence this warning, it should be noted that the `keypress` event
is deprecated.

    
    
    <!-- A11y: visible, non-interactive elements with an onclick event must be accompanied by a keyboard event handler. -->
    <div onclick={() => {}}></div>

Coding for the keyboard is important for users with physical disabilities who
cannot use a mouse, AT compatibility, and screenreader users.

###  a11y_consider_explicit_label

    
    
    Buttons and links should either contain text or have an `aria-label` or `aria-labelledby` attribute

###  a11y_distracting_elements

    
    
    Avoid `<%name%>` elements

Enforces that no distracting elements are used. Elements that can be visually
distracting can cause accessibility issues with visually impaired users. Such
elements are most likely deprecated, and should be avoided.

The following elements are visually distracting: `<marquee>` and `<blink>`.

    
    
    <!-- A11y: Avoid <marquee> elements -->
    <marquee></marquee>

###  a11y_figcaption_index

    
    
    `<figcaption>` must be first or last child of `<figure>`

###  a11y_figcaption_parent

    
    
    `<figcaption>` must be an immediate child of `<figure>`

Enforce that certain DOM elements have the correct structure.

    
    
    <!-- A11y: <figcaption> must be an immediate child of <figure> -->
    <div>
    	<figcaption>Image caption</figcaption>
    </div>

###  a11y_hidden

    
    
    `<%name%>` element should not be hidden

Certain DOM elements are useful for screen reader navigation and should not be
hidden.

    
    
    <!-- A11y: <h2> element should not be hidden -->
    <h2 aria-hidden="true">invisible header</h2>

###  a11y_img_redundant_alt

    
    
    Screenreaders already announce `<img>` elements as an image

Enforce img alt attribute does not contain the word image, picture, or photo.
Screen readers already announce `img` elements as an image. There is no need
to use words such as _image_ , _photo_ , and/or _picture_.

    
    
    <img src="foo" alt="Foo eating a sandwich." />
    
    <!-- aria-hidden, won't be announced by screen reader -->
    <img src="bar" aria-hidden="true" alt="Picture of me taking a photo of an image" />
    
    <!-- A11y: Screen readers already announce <img> elements as an image. -->
    <img src="foo" alt="Photo of foo being weird." />
    
    <!-- A11y: Screen readers already announce <img> elements as an image. -->
    <img src="bar" alt="Image of me at a bar!" />
    
    <!-- A11y: Screen readers already announce <img> elements as an image. -->
    <img src="foo" alt="Picture of baz fixing a bug." />

###  a11y_incorrect_aria_attribute_type

    
    
    The value of '%attribute%' must be a %type%

Enforce that only the correct type of value is used for aria attributes. For
example, `aria-hidden` should only receive a boolean.

    
    
    <!-- A11y: The value of 'aria-hidden' must be exactly one of true or false -->
    <div aria-hidden="yes"></div>

###  a11y_incorrect_aria_attribute_type_boolean

    
    
    The value of '%attribute%' must be either 'true' or 'false'. It cannot be empty

###  a11y_incorrect_aria_attribute_type_id

    
    
    The value of '%attribute%' must be a string that represents a DOM element ID

###  a11y_incorrect_aria_attribute_type_idlist

    
    
    The value of '%attribute%' must be a space-separated list of strings that represent DOM element IDs

###  a11y_incorrect_aria_attribute_type_integer

    
    
    The value of '%attribute%' must be an integer

###  a11y_incorrect_aria_attribute_type_token

    
    
    The value of '%attribute%' must be exactly one of %values%

###  a11y_incorrect_aria_attribute_type_tokenlist

    
    
    The value of '%attribute%' must be a space-separated list of one or more of %values%

###  a11y_incorrect_aria_attribute_type_tristate

    
    
    The value of '%attribute%' must be exactly one of true, false, or mixed

###  a11y_interactive_supports_focus

    
    
    Elements with the '%role%' interactive role must have a tabindex value

Enforce that elements with an interactive role and interactive handlers (mouse
or key press) must be focusable or tabbable.

    
    
    <!-- A11y: Elements with the 'button' interactive role must have a tabindex value. -->
    <div role="button" onkeypress={() => {}} />

###  a11y_invalid_attribute

    
    
    '%href_value%' is not a valid %href_attribute% attribute

Enforce that attributes important for accessibility have a valid value. For
example, `href` should not be empty, `'#'`, or `javascript:`.

    
    
    <!-- A11y: '' is not a valid href attribute -->
    <a href="">invalid</a>

###  a11y_label_has_associated_control

    
    
    A form label must be associated with a control

Enforce that a label tag has a text label and an associated control.

There are two supported ways to associate a label with a control:

  * Wrapping a control in a label tag.
  * Adding `for` to a label and assigning it the ID of an input on the page.

    
    
    <label for="id">B</label>
    
    <label>C <input type="text" /></label>
    
    <!-- A11y: A form label must be associated with a control. -->
    <label>A</label>

###  a11y_media_has_caption

    
    
    `<video>` elements must have a `<track kind="captions">`

Providing captions for media is essential for deaf users to follow along.
Captions should be a transcription or translation of the dialogue, sound
effects, relevant musical cues, and other relevant audio information. Not only
is this important for accessibility, but can also be useful for all users in
the case that the media is unavailable (similar to `alt` text on an image when
an image is unable to load).

The captions should contain all important and relevant information to
understand the corresponding media. This may mean that the captions are not a
1:1 mapping of the dialogue in the media content. However, captions are not
necessary for video components with the `muted` attribute.

    
    
    <video><track kind="captions" /></video>
    
    <audio muted></audio>
    
    <!-- A11y: Media elements must have a <track kind=\"captions\"> -->
    <video></video>
    
    <!-- A11y: Media elements must have a <track kind=\"captions\"> -->
    <video><track /></video>

###  a11y_misplaced_role

    
    
    `<%name%>` should not have role attribute

Certain reserved DOM elements do not support ARIA roles, states and
properties. This is often because they are not visible, for example `meta`,
`html`, `script`, `style`. This rule enforces that these DOM elements do not
contain the `role` props.

    
    
    <!-- A11y: <meta> should not have role attribute -->
    <meta role="tooltip" />

###  a11y_misplaced_scope

    
    
    The scope attribute should only be used with `<th>` elements

The scope attribute should only be used on `<th>` elements.

    
    
    <!-- A11y: The scope attribute should only be used with <th> elements -->
    <div scope="row" />

###  a11y_missing_attribute

    
    
    `<%name%>` element should have %article% %sequence% attribute

Enforce that attributes required for accessibility are present on an element.
This includes the following checks:

  * `<a>` should have an href (unless it’s a [fragment-defining tag](https://github.com/sveltejs/svelte/issues/4697))
  * `<area>` should have alt, aria-label, or aria-labelledby
  * `<html>` should have lang
  * `<iframe>` should have title
  * `<img>` should have alt
  * `<object>` should have title, aria-label, or aria-labelledby
  * `<input type="image">` should have alt, aria-label, or aria-labelledby

    
    
    <!-- A11y: <input type=\"image\"> element should have an alt, aria-label or aria-labelledby attribute -->
    <input type="image" />
    
    <!-- A11y: <html> element should have a lang attribute -->
    <html></html>
    
    <!-- A11y: <a> element should have an href attribute -->
    <a>text</a>

###  a11y_missing_content

    
    
    `<%name%>` element should contain text

Enforce that heading elements (`h1`, `h2`, etc.) and anchors have content and
that the content is accessible to screen readers

    
    
    <!-- A11y: <a> element should have child content -->
    <a href="/foo"></a>
    
    <!-- A11y: <h1> element should have child content -->
    <h1></h1>

###  a11y_mouse_events_have_key_events

    
    
    '%event%' event must be accompanied by '%accompanied_by%' event

Enforce that `onmouseover` and `onmouseout` are accompanied by `onfocus` and
`onblur`, respectively. This helps to ensure that any functionality triggered
by these mouse events is also accessible to keyboard users.

    
    
    <!-- A11y: onmouseover must be accompanied by onfocus -->
    <div onmouseover={handleMouseover} />
    
    <!-- A11y: onmouseout must be accompanied by onblur -->
    <div onmouseout={handleMouseout} />

###  a11y_no_abstract_role

    
    
    Abstract role '%role%' is forbidden

###  a11y_no_interactive_element_to_noninteractive_role

    
    
    `<%element%>` cannot have role '%role%'

[WAI-ARIA](https://www.w3.org/TR/wai-aria-1.1/#usage_intro) roles should not
be used to convert an interactive element to a non-interactive element. Non-
interactive ARIA roles include `article`, `banner`, `complementary`, `img`,
`listitem`, `main`, `region` and `tooltip`.

    
    
    <!-- A11y: <textarea> cannot have role 'listitem' -->
    <textarea role="listitem"></textarea>

###  a11y_no_noninteractive_element_interactions

    
    
    Non-interactive element `<%element%>` should not be assigned mouse or keyboard event listeners

A non-interactive element does not support event handlers (mouse and key
handlers). Non-interactive elements include `<main>`, `<area>`, `<h1>`
(,`<h2>`, etc), `<p>`, `<img>`, `<li>`, `<ul>` and `<ol>`. Non-interactive
[WAI-ARIA roles](https://www.w3.org/TR/wai-aria-1.1/#usage_intro) include
`article`, `banner`, `complementary`, `img`, `listitem`, `main`, `region` and
`tooltip`.

    
    
    <!-- `A11y: Non-interactive element <li> should not be assigned mouse or keyboard event listeners.` -->
    <li onclick={() => {}}></li>
    
    <!-- `A11y: Non-interactive element <div> should not be assigned mouse or keyboard event listeners.` -->
    <div role="listitem" onclick={() => {}}></div>

###  a11y_no_noninteractive_element_to_interactive_role

    
    
    Non-interactive element `<%element%>` cannot have interactive role '%role%'

[WAI-ARIA](https://www.w3.org/TR/wai-aria-1.1/#usage_intro) roles should not
be used to convert a non-interactive element to an interactive element.
Interactive ARIA roles include `button`, `link`, `checkbox`, `menuitem`,
`menuitemcheckbox`, `menuitemradio`, `option`, `radio`, `searchbox`, `switch`
and `textbox`.

    
    
    <!-- A11y: Non-interactive element <h3> cannot have interactive role 'searchbox' -->
    <h3 role="searchbox">Button</h3>

###  a11y_no_noninteractive_tabindex

    
    
    noninteractive element cannot have nonnegative tabIndex value

Tab key navigation should be limited to elements on the page that can be
interacted with.

    
    
    <!-- A11y: noninteractive element cannot have nonnegative tabIndex value -->
    <div tabindex="0"></div>

###  a11y_no_redundant_roles

    
    
    Redundant role '%role%'

Some HTML elements have default ARIA roles. Giving these elements an ARIA role
that is already set by the browser [has no
effect](https://www.w3.org/TR/using-aria/#aria-does-nothing) and is redundant.

    
    
    <!-- A11y: Redundant role 'button' -->
    <button role="button">...</button>
    
    <!-- A11y: Redundant role 'img' -->
    <img role="img" src="foo.jpg" />

###  a11y_no_static_element_interactions

    
    
    `<%element%>` with a %handler% handler must have an ARIA role

Elements like `<div>` with interactive handlers like `click` must have an ARIA
role.

    
    
    <!-- A11y: <div> with click handler must have an ARIA role -->
    <div onclick={() => ''}></div>

###  a11y_positive_tabindex

    
    
    Avoid tabindex values above zero

Avoid positive `tabindex` property values. This will move elements out of the
expected tab order, creating a confusing experience for keyboard users.

    
    
    <!-- A11y: avoid tabindex values above zero -->
    <div tabindex="1"></div>

###  a11y_role_has_required_aria_props

    
    
    Elements with the ARIA role "%role%" must have the following attributes defined: %props%

Elements with ARIA roles must have all required attributes for that role.

    
    
    <!-- A11y: A11y: Elements with the ARIA role "checkbox" must have the following attributes defined: "aria-checked" -->
    <span role="checkbox" aria-labelledby="foo" tabindex="0"></span>

###  a11y_role_supports_aria_props

    
    
    The attribute '%attribute%' is not supported by the role '%role%'

Elements with explicit or implicit roles defined contain only `aria-*`
properties supported by that role.

    
    
    <!-- A11y: The attribute 'aria-multiline' is not supported by the role 'link'. -->
    <div role="link" aria-multiline></div>
    
    <!-- A11y: The attribute 'aria-required' is not supported by the role 'listitem'. This role is implicit on the element <li>. -->
    <li aria-required></li>

###  a11y_role_supports_aria_props_implicit

    
    
    The attribute '%attribute%' is not supported by the role '%role%'. This role is implicit on the element `<%name%>`

Elements with explicit or implicit roles defined contain only `aria-*`
properties supported by that role.

    
    
    <!-- A11y: The attribute 'aria-multiline' is not supported by the role 'link'. -->
    <div role="link" aria-multiline></div>
    
    <!-- A11y: The attribute 'aria-required' is not supported by the role 'listitem'. This role is implicit on the element <li>. -->
    <li aria-required></li>

###  a11y_unknown_aria_attribute

    
    
    Unknown aria attribute 'aria-%attribute%'
    
    
    Unknown aria attribute 'aria-%attribute%'. Did you mean '%suggestion%'?

Enforce that only known ARIA attributes are used. This is based on the [WAI-
ARIA States and Properties
spec](https://www.w3.org/WAI/PF/aria-1.1/states_and_properties).

    
    
    <!-- A11y: Unknown aria attribute 'aria-labeledby' (did you mean 'labelledby'?) -->
    <input type="image" aria-labeledby="foo" />

###  a11y_unknown_role

    
    
    Unknown role '%role%'
    
    
    Unknown role '%role%'. Did you mean '%suggestion%'?

Elements with ARIA roles must use a valid, non-abstract ARIA role. A reference
to role definitions can be found at [WAI-ARIA](https://www.w3.org/TR/wai-
aria/#role_definitions) site.

    
    
    <!-- A11y: Unknown role 'toooltip' (did you mean 'tooltip'?) -->
    <div role="toooltip"></div>

###  attribute_avoid_is

    
    
    The "is" attribute is not supported cross-browser and should be avoided

###  attribute_global_event_reference

    
    
    You are referencing `globalThis.%name%`. Did you forget to declare a variable with that name?

###  attribute_illegal_colon

    
    
    Attributes should not contain ':' characters to prevent ambiguity with Svelte directives

###  attribute_invalid_property_name

    
    
    '%wrong%' is not a valid HTML attribute. Did you mean '%right%'?

###  attribute_quoted

    
    
    Quoted attributes on components and custom elements will be stringified in a future version of Svelte. If this isn't what you want, remove the quotes

###  bidirectional_control_characters

    
    
    A bidirectional control character was detected in your code. These characters can be used to alter the visual direction of your code and could have unintended consequences

Bidirectional control characters can alter the direction in which text appears
to be in. For example, via control characters, you can make `defabc` look like
`abcdef`. As a result, if you were to unknowingly copy and paste some code
that has these control characters, they may alter the behavior of your code in
ways you did not intend. See [trojansource.codes](https://trojansource.codes/)
for more information.

###  bind_invalid_each_rest

    
    
    The rest operator (...) will create a new object and binding '%name%' with the original object will not work

###  block_empty

    
    
    Empty block

###  component_name_lowercase

    
    
    `<%name%>` will be treated as an HTML element unless it begins with a capital letter

###  css_unused_selector

    
    
    Unused CSS selector "%name%"

Svelte traverses both the template and the `<style>` tag to find out which of
the CSS selectors are not used within the template, so it can remove them.

In some situations a selector may target an element that is not ‘visible’ to
the compiler, for example because it is part of an `{@html ...}` tag or you’re
overriding styles in a child component. In these cases, use
[`:global`](global-styles) to preserve the selector as-is:

    
    
    <div class="post">{@html content}</div>
    
    <style>
      .post :global {
    	p {...}
      }
    </style>

###  custom_element_props_identifier

    
    
    Using a rest element or a non-destructured declaration with `$props()` means that Svelte can't infer what properties to expose when creating a custom element. Consider destructuring all the props or explicitly specifying the `customElement.props` option.

###  element_implicitly_closed

    
    
    This element is implicitly closed by the following `%tag%`, which can cause an unexpected DOM structure. Add an explicit `%closing%` to avoid surprises.

In HTML, some elements are implicitly closed by another element. For example,
you cannot nest a `<p>` inside another `<p>`:

    
    
    <!-- this HTML... -->
    <p><p>hello</p>
    
    <!-- results in this DOM structure -->
    <p></p>
    <p>hello</p>

Similarly, a parent element’s closing tag will implicitly close all child
elements, even if the `</` was a typo and you meant to create a _new_ element.
To avoid ambiguity, it’s always a good idea to have an explicit closing tag.

###  element_invalid_self_closing_tag

    
    
    Self-closing HTML tags for non-void elements are ambiguous — use `<%name% ...></%name%>` rather than `<%name% ... />`

In HTML, there’s [no such thing as a self-closing
tag](https://jakearchibald.com/2023/against-self-closing-tags-in-html/). While
this _looks_ like a self-contained element with some text next to it...

    
    
    <div>
    	<span class="icon" /> some text!
    </div>

...a spec-compliant HTML parser (such as a browser) will in fact parse it like
this, with the text _inside_ the icon:

    
    
    <div>
    	<span class="icon"> some text! </span>
    </div>

Some templating languages (including Svelte) will ‘fix’ HTML by turning `<span
/>` into `<span></span>`. Others adhere to the spec. Both result in ambiguity
and confusion when copy-pasting code between different contexts, and as such
Svelte prompts you to resolve the ambiguity directly by having an explicit
closing tag.

To automate this, run the dedicated migration:

    
    
    npx sv migrate self-closing-tags

In a future version of Svelte, self-closing tags may be upgraded from a
warning to an error.

###  event_directive_deprecated

    
    
    Using `on:%name%` to listen to the %name% event is deprecated. Use the event attribute `on%name%` instead

See [the migration guide](v5-migration-guide#Event-changes) for more info.

###  export_let_unused

    
    
    Component has unused export property '%name%'. If it is for external reference only, please consider using `export const %name%`

###  legacy_code

    
    
    `%code%` is no longer valid — please use `%suggestion%` instead

###  legacy_component_creation

    
    
    Svelte 5 components are no longer classes. Instantiate them using `mount` or `hydrate` (imported from 'svelte') instead.

See the [migration guide](v5-migration-guide#Components-are-no-longer-classes)
for more info.

###  node_invalid_placement_ssr

    
    
    %message%. When rendering this component on the server, the resulting HTML will be modified by the browser (by moving, removing, or inserting elements), likely resulting in a `hydration_mismatch` warning

HTML restricts where certain elements can appear. In case of a violation the
browser will ‘repair’ the HTML in a way that breaks Svelte’s assumptions about
the structure of your components. Some examples:

  * `<p>hello <div>world</div></p>` will result in `<p>hello </p><div>world</div><p></p>` (the `<div>` autoclosed the `<p>` because `<p>` cannot contain block-level elements)
  * `<option><div>option a</div></option>` will result in `<option>option a</option>` (the `<div>` is removed)
  * `<table><tr><td>cell</td></tr></table>` will result in `<table><tbody><tr><td>cell</td></tr></tbody></table>` (a `<tbody>` is auto-inserted)

This code will work when the component is rendered on the client (which is why
this is a warning rather than an error), but if you use server rendering it
will cause hydration to fail.

###  non_reactive_update

    
    
    `%name%` is updated, but is not declared with `$state(...)`. Changing its value will not correctly trigger updates

This warning is thrown when the compiler detects the following:

  * a variable was declared without `$state` or `$state.raw`
  * the variable is reassigned
  * the variable is read in a reactive context

In this case, changing the value will not correctly trigger updates. Example:

    
    
    <script>
    	let reactive = $state('reactive');
    	let stale = 'stale';
    </script>
    
    <p>This value updates: {reactive}</p>
    <p>This value does not update: {stale}</p>
    
    <button onclick={() => {
    	stale = 'updated';
    	reactive = 'updated';
    }}>update</button>

To fix this, wrap your variable declaration with `$state`.

###  options_deprecated_accessors

    
    
    The `accessors` option has been deprecated. It will have no effect in runes mode

###  options_deprecated_immutable

    
    
    The `immutable` option has been deprecated. It will have no effect in runes mode

###  options_missing_custom_element

    
    
    The `customElement` option is used when generating a custom element. Did you forget the `customElement: true` compile option?

###  options_removed_enable_sourcemap

    
    
    The `enableSourcemap` option has been removed. Source maps are always generated now, and tooling can choose to ignore them

###  options_removed_hydratable

    
    
    The `hydratable` option has been removed. Svelte components are always hydratable now

###  options_removed_loop_guard_timeout

    
    
    The `loopGuardTimeout` option has been removed

###  options_renamed_ssr_dom

    
    
    `generate: "dom"` and `generate: "ssr"` options have been renamed to "client" and "server" respectively

###  perf_avoid_inline_class

    
    
    Avoid 'new class' — instead, declare the class at the top level scope

###  perf_avoid_nested_class

    
    
    Avoid declaring classes below the top level scope

###  reactive_declaration_invalid_placement

    
    
    Reactive declarations only exist at the top level of the instance script

###  reactive_declaration_module_script_dependency

    
    
    Reassignments of module-level declarations will not cause reactive statements to update

###  script_context_deprecated

    
    
    `context="module"` is deprecated, use the `module` attribute instead
    
    
    <script context="module" module>
    	let foo = 'bar';
    </script>

###  script_unknown_attribute

    
    
    Unrecognized attribute — should be one of `generics`, `lang` or `module`. If this exists for a preprocessor, ensure that the preprocessor removes it

###  slot_element_deprecated

    
    
    Using `<slot>` to render parent content is deprecated. Use `{@render ...}` tags instead

See [the migration guide](v5-migration-guide#Snippets-instead-of-slots) for
more info.

###  state_referenced_locally

    
    
    This reference only captures the initial value of `%name%`. Did you mean to reference it inside a %type% instead?

This warning is thrown when the compiler detects the following:

  * A reactive variable is declared
  * ...and later reassigned...
  * ...and referenced in the same scope

This ‘breaks the link’ to the original state declaration. For example, if you
pass the state to a function, the function loses access to the state once it
is reassigned:

Parent

    
    
    <script>
    	import { setContext } from 'svelte';
    
    	let count = $state(0);
    
    	// warning: state_referenced_locally
    	setContext('count', count);
    </script>
    
    <button onclick={() => count++}>
    	increment
    </button>
    
    
    <script lang="ts">
    	import { setContext } from 'svelte';
    
    	let count = $state(0);
    
    	// warning: state_referenced_locally
    	setContext('count', count);
    </script>
    
    <button onclick={() => count++}>
    	increment
    </button>

Child

    
    
    <script>
    	import { getContext } from 'svelte';
    
    	const count = getContext('count');
    </script>
    
    <!-- This will never update -->
    <p>The count is {count}</p>
    
    
    <script lang="ts">
    	import { getContext } from 'svelte';
    
    	const count = getContext('count');
    </script>
    
    <!-- This will never update -->
    <p>The count is {count}</p>

To fix this, reference the variable such that it is lazily evaluated. For the
above example, this can be achieved by wrapping `count` in a function:

Parent

    
    
    <script>
    	import { setContext } from 'svelte';
    
    	let count = $state(0);
    	setContext('count', () => count);
    </script>
    
    <button onclick={() => count++}>
    	increment
    </button>
    
    
    <script lang="ts">
    	import { setContext } from 'svelte';
    
    	let count = $state(0);
    	setContext('count', () => count);
    </script>
    
    <button onclick={() => count++}>
    	increment
    </button>

Child

    
    
    <script>
    	import { getContext } from 'svelte';
    
    	const count = getContext('count');
    </script>
    
    <!-- This will update -->
    <p>The count is {count()}</p>
    
    
    <script lang="ts">
    	import { getContext } from 'svelte';
    
    	const count = getContext('count');
    </script>
    
    <!-- This will update -->
    <p>The count is {count()}</p>

For more info, see [Passing state into functions]($state#Passing-state-into-
functions).

###  store_rune_conflict

    
    
    It looks like you're using the `$%name%` rune, but there is a local binding called `%name%`. Referencing a local variable with a `$` prefix will create a store subscription. Please rename `%name%` to avoid the ambiguity

###  svelte_component_deprecated

    
    
    `<svelte:component>` is deprecated in runes mode — components are dynamic by default

In previous versions of Svelte, the component constructor was fixed when the
component was rendered. In other words, if you wanted `<X>` to re-render when
`X` changed, you would either have to use `<svelte:component this={X}>` or put
the component inside a `{#key X}...{/key}` block.

In Svelte 5 this is no longer true — if `X` changes, `<X>` re-renders.

In some cases `<object.property>` syntax can be used as a replacement; a
lowercased variable with property access is recognized as a component in
Svelte 5.

For complex component resolution logic, an intermediary, capitalized variable
may be necessary. E.g. in places where `@const` can be used:

    
    
    {#each items as item}
    	<svelte:component this={item.condition ? Y : Z} />
    	{@const Component = item.condition ? Y : Z}
    	<Component />
    {/each}

A derived value may be used in other contexts:

    
    
    <script>
    	// ...
    	let condition = $state(false);
    	const Component = $derived(condition ? Y : Z);
    </script>
    
    <svelte:component this={condition ? Y : Z} />
    <Component />

###  svelte_element_invalid_this

    
    
    `this` should be an `{expression}`. Using a string attribute value will cause an error in future versions of Svelte

###  svelte_self_deprecated

    
    
    `<svelte:self>` is deprecated — use self-imports (e.g. `import %name% from './%basename%'`) instead

See [the note in the docs](legacy-svelte-self) for more info.

###  unknown_code

    
    
    `%code%` is not a recognised code
    
    
    `%code%` is not a recognised code (did you mean `%suggestion%`?)

# Context

### On this page

  * [Context](context)
  * Using context with state
  * Type-safe context
  * Replacing global state

Context allows components to access values owned by parent components without
passing them down as props (potentially through many layers of intermediate
components, known as ‘prop-drilling’). The parent component sets context with
`setContext(key, value)`...

Parent

    
    
    <script>
    	import { setContext } from 'svelte';
    
    	setContext('my-context', 'hello from Parent.svelte');
    </script>
    
    
    <script lang="ts">
    	import { setContext } from 'svelte';
    
    	setContext('my-context', 'hello from Parent.svelte');
    </script>

...and the child retrieves it with `getContext`:

Child

    
    
    <script>
    	import { getContext } from 'svelte';
    
    	const message = getContext('my-context');
    </script>
    
    <h1>{message}, inside Child.svelte</h1>
    
    
    <script lang="ts">
    	import { getContext } from 'svelte';
    
    	const message = getContext('my-context');
    </script>
    
    <h1>{message}, inside Child.svelte</h1>

This is particularly useful when `Parent.svelte` is not directly aware of
`Child.svelte`, but instead renders it as part of a `children`
[snippet](snippet)
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE42Q3W6DMAyFX8WyJgESK-
oto6hTX2D3YxcM3IIUQpR40yqUd58CrCXsp7tL7HNsf2dAWXaEKR56yfTBGOOxFWQwfR6Qz8q1XAHjL-
GjUhvzToJd7bU09FO9ctMkG0wxM5VuFeeFLLjtVK8ZnkpNkuGo-w6CTTJ9Z3PwsBAemlbUF934W8iy5DpaZtOUcU02-ZLcaS51jHEkTFm_kY1_wfOO8QnXrb8hBzDEc6pgZ4gFoyz4KgiD7nxfTe8ghqAhIfrJ46cTzVZBbkPlODVJsLCDO6V7ZcJoncyw1yRr0hd1GNn_ZbEM3I9i1bmVxOlWElUvDUNHxpQngt3C4CXzjS1rtvkw22wMrTRtTbC8Lkuabe7jvthPPe3DofYCAAA=)):

    
    
    <Parent>
    	<Child />
    </Parent>

The key (`'my-context'`, in the example above) and the context itself can be
any JavaScript value.

In addition to [`setContext`](svelte#setContext) and
[`getContext`](svelte#getContext), Svelte exposes
[`hasContext`](svelte#hasContext) and
[`getAllContexts`](svelte#getAllContexts) functions.

##  Using context with state

You can store reactive state in context
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE41R0W6DMAz8FSuaBNUQdK8MkKZ-
wh7HHihzu6hgosRMm1D-fUpSVNq12x4iEvvOx_kmQU2PIhfP3DCCJGgHYvxkkYid7NCI_GUS_KUcxhVEMjOelErNB3bsatvG4LW6n0ZsRC4K02qpuKqpZtmrQTNMYJA3QRAs7PTQQxS40eMCt3mX3duxnWb-
lS5h7nTI0A4jMWoo4c44P_Hku-zrOazdy64chWo-
ScfRkRgl8wgHKrLTH1OxHZkHgoHaTraHcopXUFYzPPVfuC_hwQaD1GrskdiNCdQwJljJqlvXfyqVsA5CGg0uRUQifHw56xFtciO75QrP07vo_JXf_tf8yK2ezDKY_ZWt_1y2qqYzv7bI1IW1V_sN19m-07wCAAA=))...

    
    
    <script>
    	import { setContext } from 'svelte';
    	import Child from './Child.svelte';
    
    	let counter = $state({
    		count: 0
    	});
    
    	setContext('counter', counter);
    </script>
    
    <button onclick={() => counter.count += 1}>
    	increment
    </button>
    
    <Child />
    <Child />
    <Child />

...though note that if you _reassign_ `counter` instead of updating it, you
will ‘break the link’ — in other words instead of this...

    
    
    <button onclick={() => counter = { count: 0 }}>
    	reset
    </button>

...you must do this:

    
    
    <button onclick={() => counter.count = 0}>
    	reset
    </button>

Svelte will warn you if you get it wrong.

##  Type-safe context

A useful pattern is to wrap the calls to `setContext` and `getContext` inside
helper functions that let you preserve type safety:

context

    
    
    import { getContext, setContext } from 'svelte';
    
    const key = {};
    
    /** @param {User} user */
    export function setUserContext(user) {
    	setContext(key, user);
    }
    
    export function getUserContext() {
    	return /** @type {User} */ (getContext(key));
    }
    
    
    import { getContext, setContext } from 'svelte';
    
    const key = {};
    
    export function setUserContext(user: User) {
    	setContext(key, user);
    }
    
    export function getUserContext() {
    	return getContext(key) as User;
    }

##  Replacing global state

When you have state shared by many different components, you might be tempted
to put it in its own module and just import it wherever it’s needed:

state.svelte

    
    
    export const myGlobalState = $state({
    	user: {
    		// ...
    	}
    	// ...
    });

In many cases this is perfectly fine, but there is a risk: if you mutate the
state during server-side rendering (which is discouraged, but entirely
possible!)...

App

    
    
    <script>
    	import { myGlobalState } from './state.svelte.js';
    
    	let { data } = $props();
    
    	if (data.user) {
    		myGlobalState.user = data.user;
    	}
    </script>
    
    
    <script lang="ts">
    	import { myGlobalState } from './state.svelte.js';
    
    	let { data } = $props();
    
    	if (data.user) {
    		myGlobalState.user = data.user;
    	}
    </script>

...then the data may be accessible by the _next_ user. Context solves this
problem because it is not shared between requests.

# Custom elements

### On this page

  * [Custom elements](custom-elements)
  * Component lifecycle
  * Component options
  * Caveats and limitations

Svelte components can also be compiled to custom elements (aka web components)
using the `customElement: true` compiler option. You should specify a tag name
for the component using the `<svelte:options>` [element](svelte-options).

    
    
    <svelte:options customElement="my-element" />
    
    <script>
    	let { name = 'world' } = $props();
    </script>
    
    <h1>Hello {name}!</h1>
    <slot />

You can leave out the tag name for any of your inner components which you
don’t want to expose and use them like regular Svelte components. Consumers of
the component can still name it afterwards if needed, using the static
`element` property which contains the custom element constructor and which is
available when the `customElement` compiler option is `true`.

    
    
    import MyElement from './MyElement.svelte';
    
    customElements.define('my-element', MyElement.element);

Once a custom element has been defined, it can be used as a regular DOM
element:

    
    
    document.body.innerHTML = `
    	<my-element>
    		<p>This is some slotted content</p>
    	</my-element>
    `;

Any [props](basic-markup#Component-props) are exposed as properties of the DOM
element (as well as being readable/writable as attributes, where possible).

    
    
    const el = document.querySelector('my-element');
    
    // get the current value of the 'name' prop
    console.log(el.name);
    
    // set a new value, updating the shadow DOM
    el.name = 'everybody';

Note that you need to list out all properties explicitly, i.e. doing `let
props = $props()` without declaring `props` in the component options means
that Svelte can’t know which props to expose as properties on the DOM element.

##  Component lifecycle

Custom elements are created from Svelte components using a wrapper approach.
This means the inner Svelte component has no knowledge that it is a custom
element. The custom element wrapper takes care of handling its lifecycle
appropriately.

When a custom element is created, the Svelte component it wraps is _not_
created right away. It is only created in the next tick after the
`connectedCallback` is invoked. Properties assigned to the custom element
before it is inserted into the DOM are temporarily saved and then set on
component creation, so their values are not lost. The same does not work for
invoking exported functions on the custom element though, they are only
available after the element has mounted. If you need to invoke functions
before component creation, you can work around it by using the `extend`
option.

When a custom element written with Svelte is created or updated, the shadow
DOM will reflect the value in the next tick, not immediately. This way updates
can be batched, and DOM moves which temporarily (but synchronously) detach the
element from the DOM don’t lead to unmounting the inner component.

The inner Svelte component is destroyed in the next tick after the
`disconnectedCallback` is invoked.

##  Component options

When constructing a custom element, you can tailor several aspects by defining
`customElement` as an object within `<svelte:options>` since Svelte 4. This
object may contain the following properties:

  * `tag: string`: an optional `tag` property for the custom element’s name. If set, a custom element with this tag name will be defined with the document’s `customElements` registry upon importing this component.
  * `shadow`: an optional property that can be set to `"none"` to forgo shadow root creation. Note that styles are then no longer encapsulated, and you can’t use slots
  * `props`: an optional property to modify certain details and behaviors of your component’s properties. It offers the following settings:
    * `attribute: string`: To update a custom element’s prop, you have two alternatives: either set the property on the custom element’s reference as illustrated above or use an HTML attribute. For the latter, the default attribute name is the lowercase property name. Modify this by assigning `attribute: "<desired name>"`.
    * `reflect: boolean`: By default, updated prop values do not reflect back to the DOM. To enable this behavior, set `reflect: true`.
    * `type: 'String' | 'Boolean' | 'Number' | 'Array' | 'Object'`: While converting an attribute value to a prop value and reflecting it back, the prop value is assumed to be a `String` by default. This may not always be accurate. For instance, for a number type, define it using `type: "Number"` You don’t need to list all properties, those not listed will use the default settings.
  * `extend`: an optional property which expects a function as its argument. It is passed the custom element class generated by Svelte and expects you to return a custom element class. This comes in handy if you have very specific requirements to the life cycle of the custom element or want to enhance the class to for example use [ElementInternals](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals#examples) for better HTML form integration.

    
    
    <svelte:options
    	customElement={{
    		tag: 'custom-element',
    		shadow: 'none',
    		props: {
    			name: { reflect: true, type: 'Number', attribute: 'element-index' }
    		},
    		extend: (customElementConstructor) => {
    			// Extend the class so we can let it participate in HTML forms
    			return class extends customElementConstructor {
    				static formAssociated = true;
    
    				constructor() {
    					super();
    					this.attachedInternals = this.attachInternals();
    				}
    
    				// Add the function here, not below in the component so that
    				// it's always available, not just when the inner Svelte component
    				// is mounted
    				randomIndex() {
    					this.elementIndex = Math.random();
    				}
    			};
    		}
    	}}
    />
    
    <script>
    	let { elementIndex, attachedInternals } = $props();
    	// ...
    	function check() {
    		attachedInternals.checkValidity();
    	}
    </script>
    
    ...

> While Typescript is supported in the `extend` function, it is subject to
> limitations: you need to set `lang="ts"` on one of the scripts AND you can
> only use [erasable
> syntax](https://www.typescriptlang.org/tsconfig/#erasableSyntaxOnly) in it.
> They are not processed by script preprocessors.

##  Caveats and limitations

Custom elements can be a useful way to package components for consumption in a
non-Svelte app, as they will work with vanilla HTML and JavaScript as well as
[most frameworks](https://custom-elements-everywhere.com/). There are,
however, some important differences to be aware of:

  * Styles are _encapsulated_ , rather than merely _scoped_ (unless you set `shadow: "none"`). This means that any non-component styles (such as you might have in a `global.css` file) will not apply to the custom element, including styles with the `:global(...)` modifier
  * Instead of being extracted out as a separate .css file, styles are inlined into the component as a JavaScript string
  * Custom elements are not generally suitable for server-side rendering, as the shadow DOM is invisible until JavaScript loads
  * In Svelte, slotted content renders _lazily_. In the DOM, it renders _eagerly_. In other words, it will always be created even if the component’s `<slot>` element is inside an `{#if ...}` block. Similarly, including a `<slot>` in an `{#each ...}` block will not cause the slotted content to be rendered multiple times
  * The deprecated `let:` directive has no effect, because custom elements do not have a way to pass data to the parent component that fills the slot
  * Polyfills are required to support older browsers
  * You can use Svelte’s context feature between regular Svelte components within a custom element, but you can’t use them across custom elements. In other words, you can’t use `setContext` on a parent custom element and read that with `getContext` in a child custom element.
  * Don’t declare properties or attributes starting with `on`, as their usage will be interpreted as an event listener. In other words, Svelte treats `<custom-element oneworld={true}></custom-element>` as `customElement.addEventListener('eworld', true)` (and not as `customElement.oneworld = true`)

# Custom properties

### On this page

  * [Custom properties](custom-properties)

You can pass CSS custom properties — both static and dynamic — to components:

    
    
    <Slider
    	bind:value
    	min={0}
    	max={100}
    	--track-color="black"
    	--thumb-color="rgb({r} {g} {b})"
    />

The above code essentially desugars to this:

    
    
    <svelte-css-wrapper style="display: contents; --track-color: black; --thumb-color: rgb({r} {g} {b})">
    	<Slider
    		bind:value
    		min={0}
    		max={100}
    	/>
    </svelte-css-wrapper>

For an SVG element, it would use `<g>` instead:

    
    
    <g style="--track-color: black; --thumb-color: rgb({r} {g} {b})">
    	<Slider
    		bind:value
    		min={0}
    		max={100}
    	/>
    </g>

Inside the component, we can read these custom properties (and provide
fallback values) using [`var(...)`](https://developer.mozilla.org/en-
US/docs/Web/CSS/Using_CSS_custom_properties):

    
    
    <style>
    	.track {
    		background: var(--track-color, #aaa);
    	}
    
    	.thumb {
    		background: var(--thumb-color, blue);
    	}
    </style>

You don’t _have_ to specify the values directly on the component; as long as
the custom properties are defined on a parent element, the component can use
them. It’s common to define custom properties on the `:root` element in a
global stylesheet so that they apply to your entire application.

> While the extra element will not affect layout, it _will_ affect any CSS
> selectors that (for example) use the `>` combinator to target an element
> directly inside the component’s container.

# {#each ...}

### On this page

  * [{#each ...}](each)
  * Keyed each blocks
  * Each blocks without an item
  * Else blocks

    
    
    {#each expression as name}...{/each}
    
    
    {#each expression as name, index}...{/each}

Iterating over values can be done with an each block. The values in question
can be arrays, array-like objects (i.e. anything with a `length` property), or
iterables like `Map` and `Set` — in other words, anything that can be used
with `Array.from`.

    
    
    <h1>Shopping list</h1>
    <ul>
    	{#each items as item}
    		<li>{item.name} x {item.qty}</li>
    	{/each}
    </ul>

An each block can also specify an _index_ , equivalent to the second argument
in an `array.map(...)` callback:

    
    
    {#each items as item, i}
    	<li>{i + 1}: {item.name} x {item.qty}</li>
    {/each}

##  Keyed each blocks

    
    
    {#each expression as name (key)}...{/each}
    
    
    {#each expression as name, index (key)}...{/each}

If a _key_ expression is provided — which must uniquely identify each list
item — Svelte will use it to intelligently update the list when data changes
by inserting, moving and deleting items, rather than adding or removing items
at the end and updating the state in the middle.

The key can be any object, but strings and numbers are recommended since they
allow identity to persist when the objects themselves change.

    
    
    {#each items as item (item.id)}
    	<li>{item.name} x {item.qty}</li>
    {/each}
    
    <!-- or with additional index value -->
    {#each items as item, i (item.id)}
    	<li>{i + 1}: {item.name} x {item.qty}</li>
    {/each}

You can freely use destructuring and rest patterns in each blocks.

    
    
    {#each items as { id, name, qty }, i (id)}
    	<li>{i + 1}: {name} x {qty}</li>
    {/each}
    
    {#each objects as { id, ...rest }}
    	<li><span>{id}</span><MyComponent {...rest} /></li>
    {/each}
    
    {#each items as [id, ...rest]}
    	<li><span>{id}</span><MyComponent values={rest} /></li>
    {/each}

##  Each blocks without an item

    
    
    {#each expression}...{/each}
    
    
    {#each expression, index}...{/each}

In case you just want to render something `n` times, you can omit the `as`
part
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3WR0W7CMAxFf8XKNAk0WsSeUEaRpn3Guoc0MbQiJFHiMlDVf18SOrZJ48259_jaVgZmxBEZZ28thgCNFV6xBdt1GgPj7wOji0t2EqI-
wa_OleGEmpLWiID_6dIaQkMxhm1UdwKpRQhVzWSaVORJNdvWpqbhAYVsYQCNZk8thzWMC_DCHMZk3wPSThNQ088I3mghD9UwSwHwlLE5PMIzVFUFq3G7WUZ2OyUvU3JOuZU332wCXTRmtPy1NgzXZtUFp8WFw9536uWqpbIgPEaDsJBW90cTOHh0KGi2XsBq5-cT6-3nPauxXqHnsHJnCFZ3CvJVkyuCQ0mFF9TZyCQ162WGvteLKfG197Y3iv_pz_fmS68Hxt8iPBPj5HscP8YvCNX7uhYCAAA=)):

    
    
    <div class="chess-board">
    	{#each { length: 8 }, rank}
    		{#each { length: 8 }, file}
    			<div class:black={(rank + file) % 2 === 1}></div>
    		{/each}
    	{/each}
    </div>

##  Else blocks

    
    
    {#each expression as name}...{:else}...{/each}

An each block can also have an `{:else}` clause, which is rendered if the list
is empty.

    
    
    {#each todos as todo}
    	<p>{todo.text}</p>
    {:else}
    	<p>No tasks today!</p>
    {/each}

# Frequently asked questions

### On this page

  * [Frequently asked questions](faq)
  * I’m new to Svelte. Where should I start?
  * Where can I get support?
  * Are there any third-party resources?
  * How can I get VS Code to syntax-highlight my .svelte files?
  * Is there a tool to automatically format my .svelte files?
  * How do I document my components?
  * Does Svelte scale?
  * Is there a UI component library?
  * How do I test Svelte apps?
  * Is there a router?
  * How do I write a mobile app with Svelte?
  * Can I tell Svelte not to remove my unused styles?
  * Is Svelte v2 still available?
  * How do I do hot module reloading?

##  I’m new to Svelte. Where should I start?

We think the best way to get started is playing through the interactive
[tutorial](https://svelte.dev/tutorial). Each step there is mainly focused on
one specific aspect and is easy to follow. You’ll be editing and running real
Svelte components right in your browser.

Five to ten minutes should be enough to get you up and running. An hour and a
half should get you through the entire tutorial.

##  Where can I get support?

If your question is about certain syntax, the [reference
docs](https://svelte.dev/docs/svelte) are a good place to start.

Stack Overflow is a popular forum to ask code-level questions or if you’re
stuck with a specific error. Read through the existing questions tagged with
[Svelte](https://stackoverflow.com/questions/tagged/svelte+or+svelte-3) or
[ask your own](https://stackoverflow.com/questions/ask?tags=svelte)!

There are online forums and chats which are a great place for discussion about
best practices, application architecture or just to get to know fellow Svelte
users. [Our Discord](https://svelte.dev/chat) or [the Reddit
channel](https://www.reddit.com/r/sveltejs/) are examples of that. If you have
an answerable code-level question, Stack Overflow is usually a better fit.

##  Are there any third-party resources?

Svelte Society maintains a [list of books and
videos](https://sveltesociety.dev/resources).

##  How can I get VS Code to syntax-highlight my .svelte files?

There is an [official VS Code extension for
Svelte](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-
vscode).

##  Is there a tool to automatically format my .svelte files?

You can use prettier with the [prettier-plugin-
svelte](https://www.npmjs.com/package/prettier-plugin-svelte) plugin.

##  How do I document my components?

In editors which use the Svelte Language Server you can document Components,
functions and exports using specially formatted comments.

    
    
    <script>
    	/** What should we call the user? */
    	export let name = 'world';
    </script>
    
    <!--
    @component
    Here's some documentation for this component.
    It will show up on hover.
    
    - You can use markdown here.
    - You can also use code blocks here.
    - Usage:
      ```svelte
      <main name="Arethra">
      ```
    -->
    <main>
    	<h1>
    		Hello, {name}
    	</h1>
    </main>

Note: The `@component` is necessary in the HTML comment which describes your
component.

##  Does Svelte scale?

There will be a blog post about this eventually, but in the meantime, check
out [this issue](https://github.com/sveltejs/svelte/issues/2546).

##  Is there a UI component library?

There are several UI component libraries as well as standalone components.
Find them under the [design systems section of the components
page](https://sveltesociety.dev/packages?category=design-system) on the Svelte
Society website.

##  How do I test Svelte apps?

How your application is structured and where logic is defined will determine
the best way to ensure it is properly tested. It is important to note that not
all logic belongs within a component - this includes concerns such as data
transformation, cross-component state management, and logging, among others.
Remember that the Svelte library has its own test suite, so you do not need to
write tests to validate implementation details provided by Svelte.

A Svelte application will typically have three different types of tests: Unit,
Component, and End-to-End (E2E).

_Unit Tests_ : Focus on testing business logic in isolation. Often this is
validating individual functions and edge cases. By minimizing the surface area
of these tests they can be kept lean and fast, and by extracting as much logic
as possible from your Svelte components more of your application can be
covered using them. When creating a new SvelteKit project, you will be asked
whether you would like to setup [Vitest](https://vitest.dev/) for unit
testing. There are a number of other test runners that could be used as well.

_Component Tests_ : Validating that a Svelte component mounts and interacts as
expected throughout its lifecycle requires a tool that provides a Document
Object Model (DOM). Components can be compiled (since Svelte is a compiler and
not a normal library) and mounted to allow asserting against element
structure, listeners, state, and all the other capabilities provided by a
Svelte component. Tools for component testing range from an in-memory
implementation like jsdom paired with a test runner like
[Vitest](https://vitest.dev/) to solutions that leverage an actual browser to
provide a visual testing capability such as
[Playwright](https://playwright.dev/docs/test-components) or
[Cypress](https://www.cypress.io/).

_End-to-End Tests_ : To ensure your users are able to interact with your
application it is necessary to test it as a whole in a manner as close to
production as possible. This is done by writing end-to-end (E2E) tests which
load and interact with a deployed version of your application in order to
simulate how the user will interact with your application. When creating a new
SvelteKit project, you will be asked whether you would like to setup
[Playwright](https://playwright.dev/) for end-to-end testing. There are many
other E2E test libraries available for use as well.

Some resources for getting started with testing:

  * [Svelte docs on testing](testing)
  * [Setup Vitest using the Svelte CLI](https://svelte.dev/docs/cli/vitest)
  * [Svelte Testing Library](https://testing-library.com/docs/svelte-testing-library/example/)
  * [Svelte Component Testing in Cypress](https://docs.cypress.io/guides/component-testing/svelte/overview)
  * [Example using uvu test runner with JSDOM](https://github.com/lukeed/uvu/tree/master/examples/svelte)
  * [Test Svelte components using Vitest & Playwright](https://davipon.hashnode.dev/test-svelte-component-using-vitest-playwright)
  * [Component testing with WebdriverIO](https://webdriver.io/docs/component-testing/svelte)

##  Is there a router?

The official routing library is [SvelteKit](https://svelte.dev/docs/kit).
SvelteKit provides a filesystem router, server-side rendering (SSR), and hot
module reloading (HMR) in one easy-to-use package. It shares similarities with
Next.js for React.

However, you can use any router library. A lot of people use
[page.js](https://github.com/visionmedia/page.js). There’s also
[navaid](https://github.com/lukeed/navaid), which is very similar. And
[universal-router](https://github.com/kriasoft/universal-router), which is
isomorphic with child routes, but without built-in history support.

If you prefer a declarative HTML approach, there’s the isomorphic [svelte-
routing](https://github.com/EmilTholin/svelte-routing) library and a fork of
it called [svelte-navigator](https://github.com/mefechoel/svelte-navigator)
containing some additional functionality.

If you need hash-based routing on the client side, check out the [hash
option](https://svelte.dev/docs/kit/configuration#router) in SvelteKit,
[svelte-spa-router](https://github.com/ItalyPaleAle/svelte-spa-router), or
[abstract-state-router](https://github.com/TehShrike/abstract-state-router/).

[Routify](https://routify.dev) is another filesystem-based router, similar to
SvelteKit’s router. Version 3 supports Svelte’s native SSR.

You can see a [community-maintained list of routers on
sveltesociety.dev](https://sveltesociety.dev/packages?category=routers).

##  How do I write a mobile app with Svelte?

While most mobile apps are written without using JavaScript, if you’d like to
leverage your existing Svelte components and knowledge of Svelte when building
mobile apps, you can turn a [SvelteKit
SPA](https://kit.svelte.dev/docs/single-page-apps) into a mobile app with
[Tauri](https://v2.tauri.app/start/frontend/sveltekit/) or
[Capacitor](https://capacitorjs.com/solution/svelte). Mobile features like the
camera, geolocation, and push notifications are available via plugins for both
platforms.

Svelte Native was an option available for Svelte 4, but note that Svelte 5
does not currently support it. Svelte Native lets you write NativeScript apps
using Svelte components that contain [NativeScript UI
components](https://docs.nativescript.org/ui/) rather than DOM elements, which
may be familiar for users coming from React Native.

##  Can I tell Svelte not to remove my unused styles?

No. Svelte removes the styles from the component and warns you about them in
order to prevent issues that would otherwise arise.

Svelte’s component style scoping works by generating a class unique to the
given component, adding it to the relevant elements in the component that are
under Svelte’s control, and then adding it to each of the selectors in that
component’s styles. When the compiler can’t see what elements a style selector
applies to, there would be two bad options for keeping it:

  * If it keeps the selector and adds the scoping class to it, the selector will likely not match the expected elements in the component, and they definitely won’t if they were created by a child component or `{@html ...}`.
  * If it keeps the selector without adding the scoping class to it, the given style will become a global style, affecting your entire page.

If you need to style something that Svelte can’t identify at compile time, you
will need to explicitly opt into global styles by using `:global(...)`. But
also keep in mind that you can wrap `:global(...)` around only part of a
selector. `.foo :global(.bar) { ... }` will style any `.bar` elements that
appear within the component’s `.foo` elements. As long as there’s some parent
element in the current component to start from, partially global selectors
like this will almost always be able to get you what you want.

##  Is Svelte v2 still available?

New features aren’t being added to it, and bugs will probably only be fixed if
they are extremely nasty or present some sort of security vulnerability.

The documentation is still available [here](https://v2.svelte.dev/guide).

##  How do I do hot module reloading?

We recommend using [SvelteKit](https://svelte.dev/docs/kit), which supports
HMR out of the box and is built on top of [Vite](https://vitejs.dev/) and
[svelte-hmr](https://github.com/sveltejs/svelte-hmr). There are also community
plugins for [rollup](https://github.com/rixo/rollup-plugin-svelte-hot) and
[webpack](https://github.com/sveltejs/svelte-loader).

# Getting started

### On this page

  * [Getting started](getting-started)
  * Alternatives to SvelteKit
  * Editor tooling
  * Getting help

We recommend using [SvelteKit](https://svelte.dev/docs/kit), which lets you
[build almost anything](https://svelte.dev/docs/kit/project-types). It’s the
official application framework from the Svelte team and powered by
[Vite](https://vite.dev/). Create a new project with:

    
    
    npx sv create myapp
    cd myapp
    npm install
    npm run dev

Don’t worry if you don’t know Svelte yet! You can ignore all the nice features
SvelteKit brings on top for now and dive into it later.

##  Alternatives to SvelteKit

You can also use Svelte directly with Vite by running `npm create vite@latest`
and selecting the `svelte` option. With this, `npm run build` will generate
HTML, JS, and CSS files inside the `dist` directory using [vite-plugin-
svelte](https://github.com/sveltejs/vite-plugin-svelte). In most cases, you
will probably need to [choose a routing library](faq#Is-there-a-router) as
well.

> Vite is often used in standalone mode to build [single page apps
> (SPAs)](https://svelte.dev/docs/kit/glossary#SPA), which you can also [build
> with SvelteKit](https://svelte.dev/docs/kit/single-page-apps).

There are also plugins for [Rollup](https://github.com/sveltejs/rollup-plugin-
svelte), [Webpack](https://github.com/sveltejs/svelte-loader) [and a few
others](https://sveltesociety.dev/packages?category=build-plugins), but we
recommend Vite.

##  Editor tooling

The Svelte team maintains a [VS Code
extension](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-
vscode), and there are integrations with various other
[editors](https://sveltesociety.dev/resources#editor-support) and tools as
well.

You can also check your code from the command line using [sv
check](https://github.com/sveltejs/cli).

##  Getting help

Don’t be shy about asking for help in the [Discord
chatroom](https://svelte.dev/chat)! You can also find answers on [Stack
Overflow](https://stackoverflow.com/questions/tagged/svelte).

# Global styles

### On this page

  * [Global styles](global-styles)
  * :global(...)
  * :global

##  :global(...)

To apply styles to a single selector globally, use the `:global(...)`
modifier:

    
    
    <style>
    	:global(body) {
    		/* applies to <body> */
    		margin: 0;
    	}
    
    	div :global(strong) {
    		/* applies to all <strong> elements, in any component,
    		   that are inside <div> elements belonging
    		   to this component */
    		color: goldenrod;
    	}
    
    	p:global(.big.red) {
    		/* applies to all <p> elements belonging to this component
    		   with `class="big red"`, even if it is applied
    		   programmatically (for example by a library) */
    	}
    </style>

If you want to make @keyframes that are accessible globally, you need to
prepend your keyframe names with `-global-`.

The `-global-` part will be removed when compiled, and the keyframe will then
be referenced using just `my-animation-name` elsewhere in your code.

    
    
    <style>
    	@keyframes -global-my-animation-name {
    		/* code goes here */
    	}
    </style>

##  :global

To apply styles to a group of selectors globally, create a `:global {...}`
block:

    
    
    <style>
    	:global {
    		/* applies to every <div> in your application */
    		div { ... }
    
    		/* applies to every <p> in your application */
    		p { ... }
    	}
    
    	.a :global {
    		/* applies to every `.b .c .d` element, in any component,
    		   that is inside an `.a` element in this component */
    		.b .c .d {...}
    	}
    </style>

> The second example above could also be written as an equivalent `.a :global
> .b .c .d` selector, where everything after the `:global` is unscoped, though
> the nested form is preferred.

# {#if ...}

### On this page

  * [{#if ...}](if)

    
    
    {#if expression}...{/if}
    
    
    {#if expression}...{:else if expression}...{/if}
    
    
    {#if expression}...{:else}...{/if}

Content that is conditionally rendered can be wrapped in an if block.

    
    
    {#if answer === 42}
    	<p>what was the question?</p>
    {/if}

Additional conditions can be added with `{:else if expression}`, optionally
ending in an `{:else}` clause.

    
    
    {#if porridge.temperature > 100}
    	<p>too hot!</p>
    {:else if 80 > porridge.temperature}
    	<p>too cold!</p>
    {:else}
    	<p>just right!</p>
    {/if}

(Blocks don’t have to wrap elements, they can also wrap text within elements.)

# Imperative component API

### On this page

  * [Imperative component API](imperative-component-api)
  * mount
  * unmount
  * render
  * hydrate

Every Svelte application starts by imperatively creating a root component. On
the client this component is mounted to a specific element. On the server, you
want to get back a string of HTML instead which you can render. The following
functions help you achieve those tasks.

##  mount

Instantiates a component and mounts it to the given target:

    
    
    import { mount } from 'svelte';
    import App from './App.svelte';
    
    const app = mount(App, {
    	target: document.querySelector('#app'),
    	props: { some: 'property' }
    });

You can mount multiple components per page, and you can also mount from within
your application, for example when creating a tooltip component and attaching
it to the hovered element.

Note that unlike calling `new App(...)` in Svelte 4, things like effects
(including `onMount` callbacks, and action functions) will not run during
`mount`. If you need to force pending effects to run (in the context of a
test, for example) you can do so with `flushSync()`.

##  unmount

Unmounts a component that was previously created with `mount` or `hydrate`.

If `options.outro` is `true`, [transitions](transition) will play before the
component is removed from the DOM:

    
    
    import { mount, unmount } from 'svelte';
    import App from './App.svelte';
    
    const app = mount(App, { target: document.body });
    
    // later
    unmount(app, { outro: true });

Returns a `Promise` that resolves after transitions have completed if
`options.outro` is true, or immediately otherwise.

##  render

Only available on the server and when compiling with the `server` option.
Takes a component and returns an object with `body` and `head` properties on
it, which you can use to populate the HTML when server-rendering your app:

    
    
    import { render } from 'svelte/server';
    import App from './App.svelte';
    
    const result = render(App, {
    	props: { some: 'property' }
    });
    result.body; // HTML for somewhere in this <body> tag
    result.head; // HTML for somewhere in this <head> tag

##  hydrate

Like `mount`, but will reuse up any HTML rendered by Svelte’s SSR output (from
the `render` function) inside the target and make it interactive:

    
    
    import { hydrate } from 'svelte';
    import App from './App.svelte';
    
    const app = hydrate(App, {
    	target: document.querySelector('#app'),
    	props: { some: 'property' }
    });

As with `mount`, effects will not run during `hydrate` — use `flushSync()`
immediately afterwards if you need them to.

# in: and out:

### On this page

  * [in: and out:](in-and-out)

The `in:` and `out:` directives are identical to [`transition:`](transition),
except that the resulting transitions are not bidirectional — an `in`
transition will continue to ‘play’ alongside the `out` transition, rather than
reversing, if the block is outroed while the transition is in progress. If an
out transition is aborted, transitions will restart from scratch.

    
    
    <script>
      import { fade, fly } from 'svelte/transition';
      
      let visible = $state(false);
    </script>
    
    <label>
      <input type="checkbox" bind:checked={visible}>
      visible
    </label>
    
    {#if visible}
    	<div in:fly={{ y: 200 }} out:fade>flies in, fades out</div>
    {/if}

# Svelte

### On this page

  * [Overview](overview)

Svelte is a framework for building user interfaces on the web. It uses a
compiler to turn declarative components written in HTML, CSS and JavaScript...

App

    
    
    <script>
    	function greet() {
    		alert('Welcome to Svelte!');
    	}
    </script>
    
    <button onclick={greet}>click me</button>
    
    <style>
    	button {
    		font-size: 2em;
    	}
    </style>
    
    
    <script lang="ts">
    	function greet() {
    		alert('Welcome to Svelte!');
    	}
    </script>
    
    <button onclick={greet}>click me</button>
    
    <style>
    	button {
    		font-size: 2em;
    	}
    </style>

...into lean, tightly optimized JavaScript.

You can use it to build anything on the web, from standalone components to
ambitious full stack apps (using Svelte’s companion application framework,
[SvelteKit](https://svelte.dev/docs/kit)) and everything in between.

These pages serve as reference documentation. If you’re new to Svelte, we
recommend starting with the [interactive
tutorial](https://svelte.dev/tutorial) and coming back here when you have
questions.

You can also try Svelte online in the
[playground](https://svelte.dev/playground) or, if you need a more fully-
featured environment, on [StackBlitz](https://sveltekit.new).

# {#key ...}

### On this page

  * [{#key ...}](key)

    
    
    {#key expression}...{/key}

Key blocks destroy and recreate their contents when the value of an expression
changes. When used around components, this will cause them to be
reinstantiated and reinitialised:

    
    
    {#key value}
    	<Component />
    {/key}

It’s also useful if you want a transition to play whenever a value changes:

    
    
    {#key value}
    	<div transition:fade>{value}</div>
    {/key}

# $$props and $$restProps

### On this page

  * [$$props and $$restProps](legacy-$$props-and-$$restprops)

In runes mode, getting an object containing all the props that were passed in
is easy, using the [`$props`]($props) rune.

In legacy mode, we use `$$props` and `$$restProps`:

  * `$$props` contains all the props that were passed in, including ones that are not individually declared with the `export` keyword
  * `$$restProps` contains all the props that were passed in _except_ the ones that were individually declared

For example, a `<Button>` component might need to pass along all its props to
its own `<button>` element, except the `variant` prop:

    
    
    <script>
    	export let variant;
    </script>
    
    <button {...$$restProps} class="variant-{variant} {$$props.class ?? ''}">
    	click me
    </button>
    
    <style>
    	.variant-danger {
    		background: red;
    	}
    </style>

In Svelte 3/4 using `$$props` and `$$restProps` creates a modest performance
penalty, so they should only be used when needed.

# $$slots

### On this page

  * [$$slots](legacy-$$slots)

In runes mode, we know which [snippets](snippet) were provided to a component,
as they’re just normal props.

In legacy mode, the way to know if content was provided for a given slot is
with the `$$slots` object, whose keys are the names of the slots passed into
the component by the parent.

Card

    
    
    <div>
    	<slot name="title" />
    	{#if $$slots.description}
    		<!-- This <hr> and slot will render only if `slot="description"` is provided. -->
    		<hr />
    		<slot name="description" />
    	{/if}
    </div>

App

    
    
    <Card>
    	<h1 slot="title">Blog Post Title</h1>
    	<!-- No slot named "description" was provided so the optional slot will not be rendered. -->
    </Card>

# Imperative component API

### On this page

  * [Imperative component API](legacy-component-api)
  * Creating a component
  * $set
  * $on
  * $destroy
  * Component props
  * Server-side component API

In Svelte 3 and 4, the API for interacting with a component is different than
in Svelte 5. Note that this page does _not_ apply to legacy mode components in
a Svelte 5 application.

##  Creating a component

    
    
    const component = new Component(options);

A client-side component — that is, a component compiled with `generate: 'dom'`
(or the `generate` option left unspecified) is a JavaScript class.

    
    
    import App from './App.svelte';
    
    const app = new App({
    	target: document.body,
    	props: {
    		// assuming App.svelte contains something like
    		// `export let answer`:
    		answer: 42
    	}
    });

The following initialisation options can be provided:

option | default | description  
---|---|---  
`target` | **none** | An `HTMLElement` or `ShadowRoot` to render to. This option is required  
`anchor` | `null` | A child of `target` to render the component immediately before  
`props` | `{}` | An object of properties to supply to the component  
`context` | `new Map()` | A `Map` of root-level context key-value pairs to supply to the component  
`hydrate` | `false` | See below  
`intro` | `false` | If `true`, will play transitions on initial render, rather than waiting for subsequent state changes  
  
Existing children of `target` are left where they are.

The `hydrate` option instructs Svelte to upgrade existing DOM (usually from
server-side rendering) rather than creating new elements. It will only work if
the component was compiled with the [`hydratable: true`
option](https://svelte.dev/docs/svelte-compiler#compile). Hydration of
`<head>` elements only works properly if the server-side rendering code was
also compiled with `hydratable: true`, which adds a marker to each element in
the `<head>` so that the component knows which elements it’s responsible for
removing during hydration.

Whereas children of `target` are normally left alone, `hydrate: true` will
cause any children to be removed. For that reason, the `anchor` option cannot
be used alongside `hydrate: true`.

The existing DOM doesn’t need to match the component — Svelte will ‘repair’
the DOM as it goes.

index

    
    
    import App from './App.svelte';
    
    const app = new App({
    	target: document.querySelector('#server-rendered-html'),
    	hydrate: true
    });

> In Svelte 5+, use [`mount`](svelte#mount) instead

##  $set

    
    
    component.$set(props);

Programmatically sets props on an instance. `component.$set({ x: 1 })` is
equivalent to `x = 1` inside the component’s `<script>` block.

Calling this method schedules an update for the next microtask — the DOM is
_not_ updated synchronously.

    
    
    component.$set({ answer: 42 });

> In Svelte 5+, use `$state` instead to create a component props and update
> that
>  
>  
>     let props = $state({ answer: 42 });
>     const component = mount(Component, { props });
>     // ...
>     props.answer = 24;

##  $on

    
    
    component.$on(ev, callback);

Causes the `callback` function to be called whenever the component dispatches
an `event`.

A function is returned that will remove the event listener when called.

    
    
    const off = component.$on('selected', (event) => {
    	console.log(event.detail.selection);
    });
    
    off();

> In Svelte 5+, pass callback props instead

##  $destroy

    
    
    component.$destroy();

Removes a component from the DOM and triggers any `onDestroy` handlers.

> In Svelte 5+, use [`unmount`](svelte#unmount) instead

##  Component props

    
    
    component.prop;
    
    
    component.prop = value;

If a component is compiled with `accessors: true`, each instance will have
getters and setters corresponding to each of the component’s props. Setting a
value will cause a _synchronous_ update, rather than the default async update
caused by `component.$set(...)`.

By default, `accessors` is `false`, unless you’re compiling as a custom
element.

    
    
    console.log(component.count);
    component.count += 1;

> In Svelte 5+, this concept is obsolete. If you want to make properties
> accessible from the outside, `export` them

##  Server-side component API

    
    
    const result = Component.render(...)

Unlike client-side components, server-side components don’t have a lifespan
after you render them — their whole job is to create some HTML and CSS. For
that reason, the API is somewhat different.

A server-side component exposes a `render` method that can be called with
optional props. It returns an object with `head`, `html`, and `css`
properties, where `head` contains the contents of any `<svelte:head>` elements
encountered.

You can import a Svelte component directly into Node using `svelte/register`.

    
    
    require('svelte/register');
    
    const App = require('./App.svelte').default;
    
    const { head, html, css } = App.render({
    	answer: 42
    });

The `.render()` method accepts the following parameters:

parameter | default | description  
---|---|---  
`props` | `{}` | An object of properties to supply to the component  
`options` | `{}` | An object of options  
  
The `options` object takes in the following options:

option | default | description  
---|---|---  
`context` | `new Map()` | A `Map` of root-level context key-value pairs to supply to the component  
      
    
    const { head, html, css } = App.render(
    	// props
    	{ answer: 42 },
    	// options
    	{
    		context: new Map([['context-key', 'context-value']])
    	}
    );

> In Svelte 5+, use [`render`](svelte-server#render) instead

# export let

### On this page

  * [export let](legacy-export-let)
  * Component exports
  * Renaming props

In runes mode, [component props](basic-markup#Component-props) are declared
with the [`$props`]($props) rune, allowing parent components to pass in data.

In legacy mode, props are marked with the `export` keyword, and can have a
default value:

    
    
    <script>
    	export let foo;
    	export let bar = 'default value';
    
    	// Values that are passed in as props
    	// are immediately available
    	console.log({ foo });
    </script>

The default value is used if it would otherwise be `undefined` when the
component is created.

> Unlike in runes mode, if the parent component changes a prop from a defined
> value to `undefined`, it does not revert to the initial value.

Props without default values are considered _required_ , and Svelte will print
a warning during development if no value is provided, which you can squelch by
specifying `undefined` as the default value:

    
    
    export let foo = undefined;

##  Component exports

An exported `const`, `class` or `function` declaration is _not_ considered a
prop — instead, it becomes part of the component’s API:

Greeter

    
    
    <script>
    	export function greet(name) {
    		alert(`hello ${name}!`);
    	}
    </script>
    
    
    <script lang="ts">
    	export function greet(name) {
    		alert(`hello ${name}!`);
    	}
    </script>

App

    
    
    <script>
    	import Greeter from './Greeter.svelte';
    
    	let greeter;
    </script>
    
    <Greeter bind:this={greeter} />
    
    <button on:click={() => greeter.greet('world')}>
    	greet
    </button>
    
    
    <script lang="ts">
    	import Greeter from './Greeter.svelte';
    
    	let greeter;
    </script>
    
    <Greeter bind:this={greeter} />
    
    <button on:click={() => greeter.greet('world')}>
    	greet
    </button>

##  Renaming props

The `export` keyword can appear separately from the declaration. This is
useful for renaming props, for example in the case of a reserved word:

App

    
    
    <script>
    	/** @type {string} */
    	let className;
    
    	// creates a `class` property, even
    	// though it is a reserved word
    	export { className as class };
    </script>
    
    
    <script lang="ts">
    	let className: string;
    
    	// creates a `class` property, even
    	// though it is a reserved word
    	export { className as class };
    </script>

# Reactive let/var declarations

### On this page

  * [Reactive let/var declarations](legacy-let)

In runes mode, reactive state is explicitly declared with the [`$state`
rune]($state).

In legacy mode, variables declared at the top level of a component are
automatically considered _reactive_. Reassigning or mutating these variables
(`count += 1` or `object.x = y`) will cause the UI to update.

    
    
    <script>
    	let count = 0;
    </script>
    
    <button on:click={() => count += 1}>
    	clicks: {count}
    </button>

Because Svelte’s legacy mode reactivity is based on _assignments_ , using
array methods like `.push()` and `.splice()` won’t automatically trigger
updates. A subsequent assignment is required to ‘tell’ the compiler to update
the UI:

    
    
    <script>
    	let numbers = [1, 2, 3, 4];
    
    	function addNumber() {
    		// this method call does not trigger an update
    		numbers.push(numbers.length + 1);
    
    		// this assignment will update anything
    		// that depends on `numbers`
    		numbers = numbers;
    	}
    </script>

# on:

### On this page

  * [on:](legacy-on)
  * Component events

In runes mode, event handlers are just like any other attribute or prop.

In legacy mode, we use the `on:` directive:

App

    
    
    <script>
    	let count = 0;
    
    	/** @param {MouseEvent} event */
    	function handleClick(event) {
    		count += 1;
    	}
    </script>
    
    <button on:click={handleClick}>
    	count: {count}
    </button>
    
    
    <script lang="ts">
    	let count = 0;
    
    	function handleClick(event: MouseEvent) {
    		count += 1;
    	}
    </script>
    
    <button on:click={handleClick}>
    	count: {count}
    </button>

Handlers can be declared inline with no performance penalty:

    
    
    <button on:click={() => (count += 1)}>
    	count: {count}
    </button>

Add _modifiers_ to element event handlers with the `|` character.

    
    
    <form on:submit|preventDefault={handleSubmit}>
    	<!-- the `submit` event's default is prevented,
    	     so the page won't reload -->
    </form>

The following modifiers are available:

  * `preventDefault` — calls `event.preventDefault()` before running the handler
  * `stopPropagation` — calls `event.stopPropagation()`, preventing the event reaching the next element
  * `stopImmediatePropagation` \- calls `event.stopImmediatePropagation()`, preventing other listeners of the same event from being fired.
  * `passive` — improves scrolling performance on touch/wheel events (Svelte will add it automatically where it’s safe to do so)
  * `nonpassive` — explicitly set `passive: false`
  * `capture` — fires the handler during the _capture_ phase instead of the _bubbling_ phase
  * `once` — remove the handler after the first time it runs
  * `self` — only trigger handler if `event.target` is the element itself
  * `trusted` — only trigger handler if `event.isTrusted` is `true`. I.e. if the event is triggered by a user action.

Modifiers can be chained together, e.g. `on:click|once|capture={...}`.

If the `on:` directive is used without a value, the component will _forward_
the event, meaning that a consumer of the component can listen for it.

    
    
    <button on:click>
    	The component itself will emit the click event
    </button>

It’s possible to have multiple event listeners for the same event:

App

    
    
    <script>
    	let count = 0;
    
    	function increment() {
    		count += 1;
    	}
    
    	/** @param {MouseEvent} event */
    	function log(event) {
    		console.log(event);
    	}
    </script>
    
    <button on:click={increment} on:click={log}>
    	clicks: {count}
    </button>
    
    
    <script lang="ts">
    	let count = 0;
    
    	function increment() {
    		count += 1;
    	}
    
    	function log(event: MouseEvent) {
    		console.log(event);
    	}
    </script>
    
    <button on:click={increment} on:click={log}>
    	clicks: {count}
    </button>

##  Component events

Components can dispatch events by creating a _dispatcher_ when they are
initialised:

Stepper

    
    
    <script>
    	import { createEventDispatcher } from 'svelte';
    	const dispatch = createEventDispatcher();
    </script>
    
    <button on:click={() => dispatch('decrement')}>decrement</button>
    <button on:click={() => dispatch('increment')}>increment</button>
    
    
    <script lang="ts">
    	import { createEventDispatcher } from 'svelte';
    	const dispatch = createEventDispatcher();
    </script>
    
    <button on:click={() => dispatch('decrement')}>decrement</button>
    <button on:click={() => dispatch('increment')}>increment</button>

`dispatch` creates a [`CustomEvent`](https://developer.mozilla.org/en-
US/docs/Web/API/CustomEvent). If a second argument is provided, it becomes the
`detail` property of the event object.

A consumer of this component can listen for the dispatched events:

    
    
    <script>
    	import Stepper from './Stepper.svelte';
    
    	let n = 0;
    </script>
    
    <Stepper
    	on:decrement={() => n -= 1}
    	on:increment={() => n += 1}
    />
    
    <p>n: {n}</p>

Component events do not bubble — a parent component can only listen for events
on its immediate children.

Other than `once`, modifiers are not valid on component event handlers.

> If you’re planning an eventual migration to Svelte 5, use callback props
> instead. This will make upgrading easier as `createEventDispatcher` is
> deprecated:
>
> Stepper
>  
>  
>     <script>
>       export let decrement;
>       export let increment;
>     </script>
>  
>     <button on:click={decrement}>decrement</button>
>     <button on:click={increment}>increment</button>
>  
>  
>     <script lang="ts">
>       export let decrement;
>       export let increment;
>     </script>
>  
>     <button on:click={decrement}>decrement</button>
>     <button on:click={increment}>increment</button>

# Overview

### On this page

  * [Overview](legacy-overview)

Svelte 5 introduced some significant changes to Svelte’s API, including
[runes](what-are-runes), [snippets](snippet) and event attributes. As a
result, some Svelte 3/4 features are deprecated (though supported for now,
unless otherwise specified) and will eventually be removed. We recommend that
you incrementally [migrate your existing code](v5-migration-guide).

The following pages document these features for

  * people still using Svelte 3/4
  * people using Svelte 5, but with components that haven’t yet been migrated

Since Svelte 3/4 syntax still works in Svelte 5, we will distinguish between
_legacy mode_ and _runes mode_. Once a component is in runes mode (which you
can opt into by using runes, or by explicitly setting the `runes: true`
compiler option), legacy mode features are no longer available.

If you’re exclusively interested in the Svelte 3/4 syntax, you can browse its
documentation at [v4.svelte.dev](https://v4.svelte.dev).

# Reactive $: statements

### On this page

  * [Reactive $: statements](legacy-reactive-assignments)
  * Understanding dependencies
  * Browser-only code

In runes mode, reactions to state updates are handled with the
[`$derived`]($derived) and [`$effect`]($effect) runes.

In legacy mode, any top-level statement (i.e. not inside a block or a
function) can be made reactive by prefixing it with a `$:`
[label](https://developer.mozilla.org/en-
US/docs/Web/JavaScript/Reference/Statements/label). These statements run after
other code in the `<script>` and before the component markup is rendered, then
whenever the values that they depend on change.

    
    
    <script>
    	let a = 1;
    	let b = 2;
    
    	// this is a 'reactive statement', and it will re-run
    	// when `a`, `b` or `sum` change
    	$: console.log(`${a} + ${b} = ${sum}`);
    
    	// this is a 'reactive assignment' — `sum` will be
    	// recalculated when `a` or `b` change. It is
    	// not necessary to declare `sum` separately
    	$: sum = a + b;
    </script>

Statements are ordered _topologically_ by their dependencies and their
assignments: since the `console.log` statement depends on `sum`, `sum` is
calculated first even though it appears later in the source.

Multiple statements can be combined by putting them in a block:

    
    
    $: {
    	// recalculate `total` when `items` changes
    	total = 0;
    
    	for (const item of items) {
    		total += item.value;
    	}
    }

The left-hand side of a reactive assignments can be an identifier, or it can
be a destructuring assignment:

    
    
    $: ({ larry, moe, curly } = stooges);

##  Understanding dependencies

The dependencies of a `$:` statement are determined at compile time — they are
whichever variables are referenced (but not assigned to) inside the statement.

In other words, a statement like this will _not_ re-run when `count` changes,
because the compiler cannot ‘see’ the dependency:

    
    
    let count = 0;
    let double = () => count * 2;
    
    $: doubled = double();

Similarly, topological ordering will fail if dependencies are referenced
indirectly: `z` will never update, because `y` is not considered ‘dirty’ when
the update occurs. Moving `$: z = y` below `$: setY(x)` will fix it:

    
    
    <script>
    	let x = 0;
    	let y = 0;
    
    	$: z = y;
    	$: setY(x);
    
    	function setY(value) {
    		y = value;
    	}
    </script>

##  Browser-only code

Reactive statements run during server-side rendering as well as in the
browser. This means that any code that should only run in the browser must be
wrapped in an `if` block:

    
    
    $: if (browser) {
    	document.title = title;
    }

# <slot>

### On this page

  * [<slot>](legacy-slots)
  * Named slots
  * Fallback content
  * Passing data to slotted content

In Svelte 5, content can be passed to components in the form of
[snippets](snippet) and rendered using [render tags](@render).

In legacy mode, content inside component tags is considered _slotted content_
, which can be rendered by the component using a `<slot>` element:

App

    
    
    <script>
    	import Modal from './Modal.svelte';
    </script>
    
    <Modal>This is some slotted content</Modal>
    
    
    <script lang="ts">
    	import Modal from './Modal.svelte';
    </script>
    
    <Modal>This is some slotted content</Modal>

Modal

    
    
    <div class="modal">
    	<slot></slot>
    </div>

> If you want to render a regular `<slot>` element, you can use
> `<svelte:element this={'slot'} />`.

##  Named slots

A component can have _named_ slots in addition to the default slot. On the
parent side, add a `slot="..."` attribute to an element, component or
[`<svelte:fragment>`](legacy-svelte-fragment) directly inside the component
tags.

App

    
    
    <script>
    	import Modal from './Modal.svelte';
    
    	let open = true;
    </script>
    
    {#if open}
    	<Modal>
    		This is some slotted content
    
    		<div slot="buttons">
    			<button on:click={() => open = false}>
    				close
    			</button>
    		</div>
    	</Modal>
    {/if}
    
    
    <script lang="ts">
    	import Modal from './Modal.svelte';
    
    	let open = true;
    </script>
    
    {#if open}
    	<Modal>
    		This is some slotted content
    
    		<div slot="buttons">
    			<button on:click={() => open = false}>
    				close
    			</button>
    		</div>
    	</Modal>
    {/if}

On the child side, add a corresponding `<slot name="...">` element:

Modal

    
    
    <div class="modal">
    	<slot></slot>
    	<hr>
    	<slot name="buttons"></slot>
    </div>

##  Fallback content

If no slotted content is provided, a component can define fallback content by
putting it inside the `<slot>` element:

    
    
    <slot>
    	This will be rendered if no slotted content is provided
    </slot>

##  Passing data to slotted content

Slots can be rendered zero or more times and can pass values _back_ to the
parent using props. The parent exposes the values to the slot template using
the `let:` directive.

FancyList

    
    
    <ul>
    	{#each items as data}
    		<li class="fancy">
    			<!-- 'item' here... -->
    			<slot item={process(data)} />
    		</li>
    	{/each}
    </ul>

App

    
    
    <!-- ...corresponds to 'item' here: -->
    <FancyList {items} let:item={processed}>
    	<div>{processed.text}</div>
    </FancyList>

The usual shorthand rules apply — `let:item` is equivalent to
`let:item={item}`, and `<slot {item}>` is equivalent to `<slot item={item}>`.

Named slots can also expose values. The `let:` directive goes on the element
with the `slot` attribute.

FancyList

    
    
    <ul>
    	{#each items as item}
    		<li class="fancy">
    			<slot name="item" item={process(data)} />
    		</li>
    	{/each}
    </ul>
    
    <slot name="footer" />

App

    
    
    <FancyList {items}>
    	<div slot="item" let:item>{item.text}</div>
    	<p slot="footer">Copyright (c) 2019 Svelte Industries</p>
    </FancyList>

# <svelte:component>

### On this page

  * [<svelte:component>](legacy-svelte-component)

In runes mode, `<MyComponent>` will re-render if the value of `MyComponent`
changes. See the [Svelte 5 migration guide](v5-migration-
guide#svelte:component-is-no-longer-necessary) for an example.

In legacy mode, it won’t — we must use `<svelte:component>`, which destroys
and recreates the component instance when the value of its `this` expression
changes:

    
    
    <svelte:component this={MyComponent} />

If `this` is falsy, no component is rendered.

# <svelte:fragment>

### On this page

  * [<svelte:fragment>](legacy-svelte-fragment)

The `<svelte:fragment>` element allows you to place content in a [named
slot](legacy-slots) without wrapping it in a container DOM element. This keeps
the flow layout of your document intact.

Widget

    
    
    <div>
    	<slot name="header">No header was provided</slot>
    	<p>Some content between header and footer</p>
    	<slot name="footer" />
    </div>

App

    
    
    <script>
    	import Widget from './Widget.svelte';
    </script>
    
    <Widget>
    	<h1 slot="header">Hello</h1>
    	<svelte:fragment slot="footer">
    		<p>All rights reserved.</p>
    		<p>Copyright (c) 2019 Svelte Industries</p>
    	</svelte:fragment>
    </Widget>
    
    
    <script lang="ts">
    	import Widget from './Widget.svelte';
    </script>
    
    <Widget>
    	<h1 slot="header">Hello</h1>
    	<svelte:fragment slot="footer">
    		<p>All rights reserved.</p>
    		<p>Copyright (c) 2019 Svelte Industries</p>
    	</svelte:fragment>
    </Widget>

> In Svelte 5+, this concept is obsolete, as snippets don’t create a wrapping
> element

# <svelte:self>

### On this page

  * [<svelte:self>](legacy-svelte-self)

The `<svelte:self>` element allows a component to include itself, recursively.

It cannot appear at the top level of your markup; it must be inside an if or
each block or passed to a component’s slot to prevent an infinite loop.

    
    
    <script>
    	export let count;
    </script>
    
    {#if count > 0}
    	<p>counting down... {count}</p>
    	<svelte:self count={count - 1} />
    {:else}
    	<p>lift-off!</p>
    {/if}

> This concept is obsolete, as components can import themselves:
>
> App
>  
>  
>     <script>
>       import Self from './App.svelte'
>       export let count;
>     </script>
>  
>     {#if count > 0}
>       <p>counting down... {count}</p>
>       <Self count={count - 1} />
>     {:else}
>       <p>lift-off!</p>
>     {/if}
>  
>  
>     <script lang="ts">
>       import Self from './App.svelte'
>       export let count;
>     </script>
>  
>     {#if count > 0}
>       <p>counting down... {count}</p>
>       <Self count={count - 1} />
>     {:else}
>       <p>lift-off!</p>
>     {/if}

# Lifecycle hooks

### On this page

  * [Lifecycle hooks](lifecycle-hooks)
  * onMount
  * onDestroy
  * tick
  * Deprecated: beforeUpdate / afterUpdate

In Svelte 5, the component lifecycle consists of only two parts: Its creation
and its destruction. Everything in-between — when certain state is updated —
is not related to the component as a whole; only the parts that need to react
to the state change are notified. This is because under the hood the smallest
unit of change is actually not a component, it’s the (render) effects that the
component sets up upon component initialization. Consequently, there’s no such
thing as a “before update”/"after update” hook.

##  onMount

The `onMount` function schedules a callback to run as soon as the component
has been mounted to the DOM. It must be called during the component’s
initialisation (but doesn’t need to live _inside_ the component; it can be
called from an external module).

`onMount` does not run inside a component that is rendered on the server.

    
    
    <script>
    	import { onMount } from 'svelte';
    
    	onMount(() => {
    		console.log('the component has mounted');
    	});
    </script>

If a function is returned from `onMount`, it will be called when the component
is unmounted.

    
    
    <script>
    	import { onMount } from 'svelte';
    
    	onMount(() => {
    		const interval = setInterval(() => {
    			console.log('beep');
    		}, 1000);
    
    		return () => clearInterval(interval);
    	});
    </script>

> This behaviour will only work when the function passed to `onMount`
> _synchronously_ returns a value. `async` functions always return a
> `Promise`, and as such cannot _synchronously_ return a function.

##  onDestroy

Schedules a callback to run immediately before the component is unmounted.

Out of `onMount`, `beforeUpdate`, `afterUpdate` and `onDestroy`, this is the
only one that runs inside a server-side component.

    
    
    <script>
    	import { onDestroy } from 'svelte';
    
    	onDestroy(() => {
    		console.log('the component is being destroyed');
    	});
    </script>

##  tick

While there’s no “after update” hook, you can use `tick` to ensure that the UI
is updated before continuing. `tick` returns a promise that resolves once any
pending state changes have been applied, or in the next microtask if there are
none.

    
    
    <script>
    	import { tick } from 'svelte';
    
    	$effect.pre(() => {
    		console.log('the component is about to update');
    		tick().then(() => {
    				console.log('the component just updated');
    		});
    	});
    </script>

##  Deprecated: beforeUpdate / afterUpdate

Svelte 4 contained hooks that ran before and after the component as a whole
was updated. For backwards compatibility, these hooks were shimmed in Svelte 5
but not available inside components that use runes.

    
    
    <script>
    	import { beforeUpdate, afterUpdate } from 'svelte';
    
    	beforeUpdate(() => {
    		console.log('the component is about to update');
    	});
    
    	afterUpdate(() => {
    		console.log('the component just updated');
    	});
    </script>

Instead of `beforeUpdate` use `$effect.pre` and instead of `afterUpdate` use
`$effect` instead - these runes offer more granular control and only react to
the changes you’re actually interested in.

###  Chat window example

To implement a chat window that autoscrolls to the bottom when new messages
appear (but only if you were _already_ scrolled to the bottom), we need to
measure the DOM before we update it.

In Svelte 4, we do this with `beforeUpdate`, but this is a flawed approach —
it fires before _every_ update, whether it’s relevant or not. In the example
below, we need to introduce checks like `updatingMessages` to make sure we
don’t mess with the scroll position when someone toggles dark mode.

With runes, we can use `$effect.pre`, which behaves the same as `$effect` but
runs before the DOM is updated. As long as we explicitly reference `messages`
inside the effect body, it will run whenever `messages` changes, but _not_
when `theme` changes.

`beforeUpdate`, and its equally troublesome counterpart `afterUpdate`, are
therefore deprecated in Svelte 5.

  * [Before](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE31WXa_bNgz9K6yL1QmWOLlrC-w6H8MeBgwY9tY9NfdBtmlbiywZkpyPBfnvo2zLcZK28AWuRPGI5OGhkEuQc4EmiL9eAskqDOLg97oOZoE9125jDigs0t6oRqfOsjap5rXd7uTO8qpW2sIFEsyVxn_qjFmcAcstar-xPN3DFXKtKgi768IVgQku0ELj3Lgs_kZjWIEGNpAzYXDlHWyJFZI1zJjeh4O5uvl_DY8oUkVeVoFuJKYls-_CGYS25Aboj0EtWNqel0wWoBoLTGZgmdgDS9zW4Uz4NsrswPHoyutN4xInkylstnBxdmIhh8m7xzqmoNE2Wq46n1RJQzEbq4g-JQSl7e-HDx-GdaTy3KD9E3lRWvj5Zu9QX1QN20dj7zyHz8s-1S6lW7Cpz3RnXTcm04hIlfdFuO8p2mQ5-3a06cqjrn559bF_2NHOnRZ5I1PLlXQNyQT-hedMHeUEDyjtdMxsa4n2eIbNhlTwhyRthaOKOmYtniwF6pwt0wXa6MBEg0OibZec27gz_dk3UrZ6hB2LLYoiv521Yd8Gt-foTrfhiCDP0lC9VUUhcDLU49Xe_9943cNvEArHfAjxeBTovvXiNpFynfEDpIIZs9kFbg52QbeNHWZzebz32s7xHco3nJAJl1nshmhz8dYOQJDyZetnbb2gTWe-vEeWlrfpZMavr56ldb29eNt6UXvgwgFbp_WC0tl2RK25rGk6lYz3nUI2lzvBXGHhPZPGWmKUXFNBKqdaW259wl_aHbiqoVIZdpE60Nax6IOujT0LbFFxIVTCxCRR2XloUcYNvSbnGHKBp763jHoj59xiZWJI0Wm0P_m3MSS985xkasn-cFq20xTDy3J5KFcjgUTD69BHdcHIjz431z28IqlxGcPSfdFnrGDZn6gD6lyo45zyHAD-btczf-98nhQxHEvKfeUtOVkSejD3q-9X7JbzjGtsdUxlKdFU8qGsT78uaw848syWMXz85Waq2Gnem4mAn3prweq4q6Y3JEpnqMmnPoFRgmd3ySW0LLRqSKlwYHriCvJvUs2yjMaaoA-XzTXLeGMe45zmhv_XAno3Mj0xF7USuqNvnE9H343QHlq-eAgxpbTPNR9yzUkgLjwSR0NK4wKoxy-jDg-9vy8sUSToakzW-9fX13Em9Q8T6Z26uZhBN36XUYo5q7ggLXBZoub2Ofv7g6GCZfTxe034NCjiudXj7Omla0eTfo7QBPOcYxbE7qG-vl3_B1G-_i_JCAAA)
  * [After](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE31WXa-jNhD9K7PsdknUQJLurtRLPqo-VKrU1327uQ8GBnBjbGSb5KZR_nvHgMlXtyIS9njO-MyZGZRzUHCBJkhez4FkNQZJ8HvTBLPAnhq3MQcUFmlvVKszZ1mbTPPGbndyZ3ndKG3hDJZne7hAoVUNYY8JV-RBPgIt2AprhA18MpZZnIQ50_twuvLHNRrDSjRXj9fwiCJTBLIKdCsxq5j9EM4gtBU3QD8GjWBZd14xWYJqLTCZg2ViDyx1W4cz4dv0hsiB49FRHkyfsCgws3GjcTKZwmYLZ2feWc9o1W8zJQ2Fb62i5JUQRNRHgs-fx3WsisKg_RN5WVn4-WrvUd9VA9tH4-AcwbfFQIpkLWByvWzqSe2sk3kyjUlOec_XPU-3TRaz_75tuvKoi19e3OvipSpamVmupJM2F_gXnnJ1lBM8oLQjHceys8R7PMFms4HwD2lRhzeEe-EsvluSrHe2TJdo4wMTLY48XKwPzm0KGm2r5ajFtRYU4TWOY7-ddWHfxhDP0QkQhnf5PWRnVVkKnIx8fZsOb5dR16nwG4TCCRdCMphWQ7z1_DoOcp3zA2SCGbPZBa5jd0G_TRxmc36Me-mG6A7l60XIlMs8ce2-OXtrDyBItdz6qVjPadObzx-RZdV1nJjx64tXad1sz962njceOHfAzmk9JzrbXqg1lw3NkZL7vgE257t-uMDcO6attSSokpmgFqVMO2U93e_dDlzOUKsc-3t6zNZp6K9cG3sS2KGSUqiUiUmq8tNYoJwbmvpTAoXA96GyjCojI26xNglk6DpwOPm7NdRYp4ia0JL94bTqRiGB5WJxqFY37RGPoz3c6i4jP3rcUA7wmhqNywQW7om_YQ2L4UQdUBdCHSPiOQJ8bFcxHzeK0jKBY0XcV95SkCWlD9t-9eOM3TLKucauiyktJdpaPqT19ddF4wFHntsqgS-_XE01e48GMwnw02AtWZP02QyGVOkcNfk072CU4PkduZSWpVYt9SkcmJ64hPwHpWF5ziVls3wIFmmW89Y83vMeGf5PBxjcyPSkXNy10J18t3x6-a6CDtBq6SGklNKeazFyLahB3PVIGo2UbhOgGi9vKjzW_j6xVFFD17difXx5ebll0vwvkcGpn4sZ9MN3vqFYsJoL6gUuK9TcPrO_PxgzWMRfflSEr2NHPJf6lj1957rRpH8CNMG84JgHidUtXt4u_wK21LXERAgAAA==)

    
    
    <script>
    	import { beforeUpdate, afterUpdate, tick } from 'svelte';
    
    	let updatingMessages = false;
    	let theme = $state('dark');
    	let messages = $state([]);
    
    	let viewport;
    
    	beforeUpdate(() => {
    	$effect.pre(() => {
    		if (!updatingMessages) return;
    		messages;
    		const autoscroll = viewport && viewport.offsetHeight + viewport.scrollTop > viewport.scrollHeight - 50;
    
    		if (autoscroll) {
    			tick().then(() => {
    				viewport.scrollTo(0, viewport.scrollHeight);
    			});
    		}
    
    		updatingMessages = false;
    	});
    
    	function handleKeydown(event) {
    		if (event.key === 'Enter') {
    			const text = event.target.value;
    			if (!text) return;
    
    			updatingMessages = true;
    			messages = [...messages, text];
    			event.target.value = '';
    		}
    	}
    
    	function toggle() {
    		theme = theme === 'dark' ? 'light' : 'dark';
    	}
    </script>
    
    <div class:dark={theme === 'dark'}>
    	<div bind:this={viewport}>
    		{#each messages as message}
    			<p>{message}</p>
    		{/each}
    	</div>
    
    	<input onkeydown={handleKeydown} />
    
    	<button onclick={toggle}> Toggle dark mode </button>
    </div>

# Nested <style> elements

### On this page

  * [Nested <style> elements](nested-style-elements)

There can only be one top-level `<style>` tag per component.

However, it is possible to have a `<style>` tag nested inside other elements
or logic blocks.

In that case, the `<style>` tag will be inserted as-is into the DOM; no
scoping or processing will be done on the `<style>` tag.

    
    
    <div>
    	<style>
    		/* this style tag will be inserted as-is */
    		div {
    			/* this will apply to all `<div>` elements in the DOM */
    			color: red;
    		}
    	</style>
    </div>

# Overview

### On this page

  * [Overview](overview)

Svelte is a framework for building user interfaces on the web. It uses a
compiler to turn declarative components written in HTML, CSS and JavaScript...

App

    
    
    <script>
    	function greet() {
    		alert('Welcome to Svelte!');
    	}
    </script>
    
    <button onclick={greet}>click me</button>
    
    <style>
    	button {
    		font-size: 2em;
    	}
    </style>
    
    
    <script lang="ts">
    	function greet() {
    		alert('Welcome to Svelte!');
    	}
    </script>
    
    <button onclick={greet}>click me</button>
    
    <style>
    	button {
    		font-size: 2em;
    	}
    </style>

...into lean, tightly optimized JavaScript.

You can use it to build anything on the web, from standalone components to
ambitious full stack apps (using Svelte’s companion application framework,
[SvelteKit](https://svelte.dev/docs/kit)) and everything in between.

These pages serve as reference documentation. If you’re new to Svelte, we
recommend starting with the [interactive
tutorial](https://svelte.dev/tutorial) and coming back here when you have
questions.

You can also try Svelte online in the
[playground](https://svelte.dev/playground) or, if you need a more fully-
featured environment, on [StackBlitz](https://sveltekit.new).

# Runtime errors

### On this page

  * [Runtime errors](runtime-errors)
  * Client errors
  * Server errors
  * Shared errors

##  Client errors

###  bind_invalid_checkbox_value

    
    
    Using `bind:value` together with a checkbox input is not allowed. Use `bind:checked` instead

###  bind_invalid_export

    
    
    Component %component% has an export named `%key%` that a consumer component is trying to access using `bind:%key%`, which is disallowed. Instead, use `bind:this` (e.g. `<%name% bind:this={component} />`) and then access the property on the bound component instance (e.g. `component.%key%`)

###  bind_not_bindable

    
    
    A component is attempting to bind to a non-bindable property `%key%` belonging to %component% (i.e. `<%name% bind:%key%={...}>`). To mark a property as bindable: `let { %key% = $bindable() } = $props()`

###  component_api_changed

    
    
    Calling `%method%` on a component instance (of %component%) is no longer valid in Svelte 5

See the [migration guide](v5-migration-guide#Components-are-no-longer-classes)
for more information.

###  component_api_invalid_new

    
    
    Attempted to instantiate %component% with `new %name%`, which is no longer valid in Svelte 5. If this component is not under your control, set the `compatibility.componentApi` compiler option to `4` to keep it working.

See the [migration guide](v5-migration-guide#Components-are-no-longer-classes)
for more information.

###  derived_references_self

    
    
    A derived value cannot reference itself recursively

###  each_key_duplicate

    
    
    Keyed each block has duplicate key at indexes %a% and %b%
    
    
    Keyed each block has duplicate key `%value%` at indexes %a% and %b%

###  effect_in_teardown

    
    
    `%rune%` cannot be used inside an effect cleanup function

###  effect_in_unowned_derived

    
    
    Effect cannot be created inside a `$derived` value that was not itself created inside an effect

###  effect_orphan

    
    
    `%rune%` can only be used inside an effect (e.g. during component initialisation)

###  effect_update_depth_exceeded

    
    
    Maximum update depth exceeded. This can happen when a reactive block or effect repeatedly sets a new value. Svelte limits the number of nested updates to prevent infinite loops

###  hydration_failed

    
    
    Failed to hydrate the application

###  invalid_snippet

    
    
    Could not `{@render}` snippet due to the expression being `null` or `undefined`. Consider using optional chaining `{@render snippet?.()}`

###  lifecycle_legacy_only

    
    
    `%name%(...)` cannot be used in runes mode

###  props_invalid_value

    
    
    Cannot do `bind:%key%={undefined}` when `%key%` has a fallback value

###  props_rest_readonly

    
    
    Rest element properties of `$props()` such as `%property%` are readonly

###  rune_outside_svelte

    
    
    The `%rune%` rune is only available inside `.svelte` and `.svelte.js/ts` files

###  state_descriptors_fixed

    
    
    Property descriptors defined on `$state` objects must contain `value` and always be `enumerable`, `configurable` and `writable`.

###  state_prototype_fixed

    
    
    Cannot set prototype of `$state` object

###  state_unsafe_mutation

    
    
    Updating state inside a derived or a template expression is forbidden. If the value should not be reactive, declare it without `$state`

This error occurs when state is updated while evaluating a `$derived`. You
might encounter it while trying to ‘derive’ two pieces of state in one go:

    
    
    <script>
    	let count = $state(0);
    
    	let even = $state(true);
    
    	let odd = $derived.by(() => {
    		even = count % 2 === 0;
    		return !even;
    	});
    </script>
    
    <button onclick={() => count++}>{count}</button>
    
    <p>{count} is even: {even}</p>
    <p>{count} is odd: {odd}</p>

This is forbidden because it introduces instability: if `<p>{count} is even:
{even}</p>` is updated before `odd` is recalculated, `even` will be stale. In
most cases the solution is to make everything derived:

    
    
    let even = $derived(count % 2 === 0);
    let odd = $derived(!even);

If side-effects are unavoidable, use [`$effect`]($effect) instead.

##  Server errors

###  lifecycle_function_unavailable

    
    
    `%name%(...)` is not available on the server

Certain methods such as `mount` cannot be invoked while running in a server
context. Avoid calling them eagerly, i.e. not during render.

##  Shared errors

###  invalid_default_snippet

    
    
    Cannot use `{@render children(...)}` if the parent component uses `let:` directives. Consider using a named snippet instead

This error would be thrown in a setup like this:

Parent

    
    
    <List {items} let:entry>
    	<span>{entry}</span>
    </List>

List

    
    
    <script>
    	let { items, children } = $props();
    </script>
    
    <ul>
    	{#each items as item}
    		<li>{@render children(item)}</li>
    	{/each}
    </ul>
    
    
    <script lang="ts">
    	let { items, children } = $props();
    </script>
    
    <ul>
    	{#each items as item}
    		<li>{@render children(item)}</li>
    	{/each}
    </ul>

Here, `List.svelte` is using `{@render children(item)` which means it expects
`Parent.svelte` to use snippets. Instead, `Parent.svelte` uses the deprecated
`let:` directive. This combination of APIs is incompatible, hence the error.

###  invalid_snippet_arguments

    
    
    A snippet function was passed invalid arguments. Snippets should only be instantiated via `{@render ...}`

###  lifecycle_outside_component

    
    
    `%name%(...)` can only be used during component initialisation

Certain lifecycle methods can only be used during component initialisation. To
fix this, make sure you’re invoking the method inside the _top level of the
instance script_ of your component.

    
    
    <script>
    	import { onMount } from 'svelte';
    
    	function handleClick() {
    		// This is wrong
    		onMount(() => {})
    	}
    
    	// This is correct
    	onMount(() => {})
    </script>
    
    <button onclick={handleClick}>click me</button>

###  snippet_without_render_tag

    
    
    Attempted to render a snippet without a `{@render}` block. This would cause the snippet code to be stringified instead of its content being rendered to the DOM. To fix this, change `{snippet}` to `{@render snippet()}`.

A component throwing this error will look something like this (`children` is
not being rendered):

    
    
    <script>
    	let { children } = $props();
    </script>
    
    {children}

...or like this (a parent component is passing a snippet where a non-snippet
value is expected):

Parent

    
    
    <ChildComponent>
      {#snippet label()}
    	<span>Hi!</span>
      {/snippet}
    </ChildComponent>

Child

    
    
    <script>
      let { label } = $props();
    </script>
    
    <!-- This component doesn't expect a snippet, but the parent provided one -->
    <p>{label}</p>
    
    
    <script lang="ts">
      let { label } = $props();
    </script>
    
    <!-- This component doesn't expect a snippet, but the parent provided one -->
    <p>{label}</p>

###  store_invalid_shape

    
    
    `%name%` is not a store with a `subscribe` method

###  svelte_element_invalid_this_value

    
    
    The `this` prop on `<svelte:element>` must be a string, if defined

# Runtime warnings

### On this page

  * [Runtime warnings](runtime-warnings)
  * Client warnings
  * Shared warnings

##  Client warnings

###  assignment_value_stale

    
    
    Assignment to `%property%` property (%location%) will evaluate to the right-hand side, not the value of `%property%` following the assignment. This may result in unexpected behaviour.

Given a case like this...

    
    
    <script>
    	let object = $state({ array: null });
    
    	function add() {
    		(object.array ??= []).push(object.array.length);
    	}
    </script>
    
    <button onclick={add}>add</button>
    <p>items: {JSON.stringify(object.items)}</p>

...the array being pushed to when the button is first clicked is the `[]` on
the right-hand side of the assignment, but the resulting value of
`object.array` is an empty state proxy. As a result, the pushed value will be
discarded.

You can fix this by separating it into two statements:

    
    
    function add() {
    	object.array ??= [];
    	object.array.push(object.array.length);
    }

###  binding_property_non_reactive

    
    
    `%binding%` is binding to a non-reactive property
    
    
    `%binding%` (%location%) is binding to a non-reactive property

###  console_log_state

    
    
    Your `console.%method%` contained `$state` proxies. Consider using `$inspect(...)` or `$state.snapshot(...)` instead

When logging a [proxy](https://developer.mozilla.org/en-
US/docs/Web/JavaScript/Reference/Global_Objects/Proxy), browser devtools will
log the proxy itself rather than the value it represents. In the case of
Svelte, the ‘target’ of a `$state` proxy might not resemble its current value,
which can be confusing.

The easiest way to log a value as it changes over time is to use the
[`$inspect`]($inspect) rune. Alternatively, to log things on a one-off basis
(for example, inside an event handler) you can use
[`$state.snapshot`]($state#$state.snapshot) to take a snapshot of the current
value.

###  event_handler_invalid

    
    
    %handler% should be a function. Did you mean to %suggestion%?

###  hydration_attribute_changed

    
    
    The `%attribute%` attribute on `%html%` changed its value between server and client renders. The client value, `%value%`, will be ignored in favour of the server value

Certain attributes like `src` on an `<img>` element will not be repaired
during hydration, i.e. the server value will be kept. That’s because updating
these attributes can cause the image to be refetched (or in the case of an
`<iframe>`, for the frame to be reloaded), even if they resolve to the same
resource.

To fix this, either silence the warning with a [`svelte-ignore`](basic-
markup#Comments) comment, or ensure that the value stays the same between
server and client. If you really need the value to change on hydration, you
can force an update like this:

    
    
    <script>
    	let { src } = $props();
    
    	if (typeof window !== 'undefined') {
    		// stash the value...
    		const initial = src;
    
    		// unset it...
    		src = undefined;
    
    		$effect(() => {
    			// ...and reset after we've mounted
    			src = initial;
    		});
    	}
    </script>
    
    <img {src} />

###  hydration_html_changed

    
    
    The value of an `{@html ...}` block changed between server and client renders. The client value will be ignored in favour of the server value
    
    
    The value of an `{@html ...}` block %location% changed between server and client renders. The client value will be ignored in favour of the server value

If the `{@html ...}` value changes between the server and the client, it will
not be repaired during hydration, i.e. the server value will be kept. That’s
because change detection during hydration is expensive and usually
unnecessary.

To fix this, either silence the warning with a [`svelte-ignore`](basic-
markup#Comments) comment, or ensure that the value stays the same between
server and client. If you really need the value to change on hydration, you
can force an update like this:

    
    
    <script>
    	let { markup } = $props();
    
    	if (typeof window !== 'undefined') {
    		// stash the value...
    		const initial = markup;
    
    		// unset it...
    		markup = undefined;
    
    		$effect(() => {
    			// ...and reset after we've mounted
    			markup = initial;
    		});
    	}
    </script>
    
    {@html markup}

###  hydration_mismatch

    
    
    Hydration failed because the initial UI does not match what was rendered on the server
    
    
    Hydration failed because the initial UI does not match what was rendered on the server. The error occurred near %location%

This warning is thrown when Svelte encounters an error while hydrating the
HTML from the server. During hydration, Svelte walks the DOM, expecting a
certain structure. If that structure is different (for example because the
HTML was repaired by the DOM because of invalid HTML), then Svelte will run
into issues, resulting in this warning.

During development, this error is often preceeded by a `console.error`
detailing the offending HTML, which needs fixing.

###  invalid_raw_snippet_render

    
    
    The `render` function passed to `createRawSnippet` should return HTML for a single element

###  legacy_recursive_reactive_block

    
    
    Detected a migrated `$:` reactive block in `%filename%` that both accesses and updates the same reactive value. This may cause recursive updates when converted to an `$effect`.

###  lifecycle_double_unmount

    
    
    Tried to unmount a component that was not mounted

###  ownership_invalid_binding

    
    
    %parent% passed property `%prop%` to %child% with `bind:`, but its parent component %owner% did not declare `%prop%` as a binding. Consider creating a binding between %owner% and %parent% (e.g. `bind:%prop%={...}` instead of `%prop%={...}`)

Consider three components `GrandParent`, `Parent` and `Child`. If you do
`<GrandParent bind:value>`, inside `GrandParent` pass on the variable via
`<Parent {value} />` (note the missing `bind:`) and then do `<Child
bind:value>` inside `Parent`, this warning is thrown.

To fix it, `bind:` to the value instead of just passing a property (i.e. in
this example do `<Parent bind:value />`).

###  ownership_invalid_mutation

    
    
    Mutating unbound props (`%name%`, at %location%) is strongly discouraged. Consider using `bind:%prop%={...}` in %parent% (or using a callback) instead

Consider the following code:

App

    
    
    <script>
    	import Child from './Child.svelte';
    	let person = $state({ name: 'Florida', surname: 'Man' });
    </script>
    
    <Child {person} />
    
    
    <script lang="ts">
    	import Child from './Child.svelte';
    	let person = $state({ name: 'Florida', surname: 'Man' });
    </script>
    
    <Child {person} />

Child

    
    
    <script>
    	let { person } = $props();
    </script>
    
    <input bind:value={person.name}>
    <input bind:value={person.surname}>
    
    
    <script lang="ts">
    	let { person } = $props();
    </script>
    
    <input bind:value={person.name}>
    <input bind:value={person.surname}>

`Child` is mutating `person` which is owned by `App` without being explicitly
“allowed” to do so. This is strongly discouraged since it can create code that
is hard to reason about at scale (“who mutated this value?”), hence the
warning.

To fix it, either create callback props to communicate changes, or mark
`person` as [`$bindable`]($bindable).

###  select_multiple_invalid_value

    
    
    The `value` property of a `<select multiple>` element should be an array, but it received a non-array value. The selection will be kept as is.

When using `<select multiple value={...}>`, Svelte will mark all selected
`<option>` elements as selected by iterating over the array passed to `value`.
If `value` is not an array, Svelte will emit this warning and keep the
selected options as they are.

To silence the warning, ensure that `value`:

  * is an array for an explicit selection
  * is `null` or `undefined` to keep the selection as is

###  state_proxy_equality_mismatch

    
    
    Reactive `$state(...)` proxies and the values they proxy have different identities. Because of this, comparisons with `%operator%` will produce unexpected results

`$state(...)` creates a [proxy](https://developer.mozilla.org/en-
US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) of the value it is
passed. The proxy and the value have different identities, meaning equality
checks will always return `false`:

    
    
    <script>
    	let value = { foo: 'bar' };
    	let proxy = $state(value);
    
    	value === proxy; // always false
    </script>

To resolve this, ensure you’re comparing values where both values were created
with `$state(...)`, or neither were. Note that `$state.raw(...)` will _not_
create a state proxy.

###  transition_slide_display

    
    
    The `slide` transition does not work correctly for elements with `display: %value%`

The [slide](svelte-transition#slide) transition works by animating the
`height` of the element, which requires a `display` style like `block`, `flex`
or `grid`. It does not work for:

  * `display: inline` (which is the default for elements like `<span>`), and its variants like `inline-block`, `inline-flex` and `inline-grid`
  * `display: table` and `table-[name]`, which are the defaults for elements like `<table>` and `<tr>`
  * `display: contents`

##  Shared warnings

###  dynamic_void_element_content

    
    
    `<svelte:element this="%tag%">` is a void element — it cannot have content

Elements such as `<input>` cannot have content, any children passed to these
elements will be ignored.

###  state_snapshot_uncloneable

    
    
    Value cannot be cloned with `$state.snapshot` — the original value was returned
    
    
    The following properties cannot be cloned with `$state.snapshot` — the return value contains the originals:
    
    %properties%

`$state.snapshot` tries to clone the given value in order to return a
reference that no longer changes. Certain objects may not be cloneable, in
which case the original value is returned. In the following example,
`property` is cloned, but `window` is not, because DOM elements are
uncloneable:

    
    
    const object = $state({ property: 'this is cloneable', window })
    const snapshot = $state.snapshot(object);

# Scoped styles

### On this page

  * [Scoped styles](scoped-styles)
  * Specificity
  * Scoped keyframes

Svelte components can include a `<style>` element containing CSS that belongs
to the component. This CSS is _scoped_ by default, meaning that styles will
not apply to any elements on the page outside the component in question.

This works by adding a class to affected elements, which is based on a hash of
the component styles (e.g. `svelte-123xyz`).

    
    
    <style>
    	p {
    		/* this will only affect <p> elements in this component */
    		color: burlywood;
    	}
    </style>

##  Specificity

Each scoped selector receives a
[specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity)
increase of 0-1-0, as a result of the scoping class (e.g. `.svelte-123xyz`)
being added to the selector. This means that (for example) a `p` selector
defined in a component will take precedence over a `p` selector defined in a
global stylesheet, even if the global stylesheet is loaded later.

In some cases, the scoping class must be added to a selector multiple times,
but after the first occurrence it is added with `:where(.svelte-xyz123)` in
order to not increase specificity further.

##  Scoped keyframes

If a component defines `@keyframes`, the name is scoped to the component using
the same hashing approach. Any `animation` rules in the component will be
similarly adjusted:

    
    
    <style>
    	.bouncy {
    		animation: bounce 10s;
    	}
    
    	/* these keyframes are only accessible inside this component */
    	@keyframes bounce {
    		/* ... */
    	}
    </style>

# {#snippet ...}

### On this page

  * [{#snippet ...}](snippet)
  * Snippet scope
  * Passing snippets to components
  * Typing snippets
  * Exporting snippets
  * Programmatic snippets
  * Snippets and slots

    
    
    {#snippet name()}...{/snippet}
    
    
    {#snippet name(param1, param2, paramN)}...{/snippet}

Snippets, and [render tags](@render), are a way to create reusable chunks of
markup inside your components. Instead of writing duplicative code like
[this](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE5VUYW-
kIBD9K8Tmsm2yXXRzvQ-s3eR-R-0HqqOQKhAZb9sz_vdDkV1t000vRmHewMx7w2AflbIGG7GnPlK8gYhFv42JthG-m9Gwf6BGcLbVXZuPSGrzVho8ZirDGpDIhldgySN5GpEMez9kaNuckY1ANJZRamRuu2ZnhEZt6a84pvs43mzD4pMsUDDi8DMkQFYCGdkvsJwblFq5uCik9bmJ4JZwUkv1eoknWigX2eGNN6aGXa6bjV8ybP-X7sM36T58SVcrIIV2xVIaA41xeD5kKqWXuqpUJEefOqVuOkL9DfBchGrzWfu0vb-
RpTd3o-zBR045Ga3HfuE5BmJpKauuhbPtENlUF2sqR9jqpsPSxWsMrlngyj3VJiyYjJXb1-lMa7IWC-
iSk2M5Zzh-SJjShe-
siq5kpZRPs55BbSGU5YPyte4vVV_VfFXxVb10dSLf17pS2lM5HnpPxw4Zpv6x-F57p0jI3OKlVnhv5V9wPQrNYQQ9D_f6aGHlC89fq1Z3qmDkJCTCweOGF4VUFSPJvD_DhreVdA0eu8ehJJ5x91dBaBkpWm3ureCFPt3uzRv56d4kdp-2euG38XZ6dsnd3ZmPG9yRBCrzRUvi-
MccOdwz3qE-fOZ7AwAhlrtTUx3c76vRhSwlFBHDtoPhefgHX3dM0PkEAAA=)...

    
    
    {#each images as image}
    	{#if image.href}
    		<a href={image.href}>
    			<figure>
    				<img src={image.src} alt={image.caption} width={image.width} height={image.height} />
    				<figcaption>{image.caption}</figcaption>
    			</figure>
    		</a>
    	{:else}
    		<figure>
    			<img src={image.src} alt={image.caption} width={image.width} height={image.height} />
    			<figcaption>{image.caption}</figcaption>
    		</figure>
    	{/if}
    {/each}

...you can write
[this](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE5VUYW-
bMBD9KxbRlERKY4jWfSA02n5H6QcXDmwVbMs-
lnaI_z6D7TTt1moTAnPvzvfenQ_GpBEd2CS_HxPJekjy5IfWyS7BFz0b9id0CM62ajDVjBS2MkLjqZQldoBE9KwFS-7I_YyUOPqlRGuqnKw5orY5pVpUduj3mitUln5LU3pI0_UuBp9FjTwnDr9AHETLMSeHK6xiGoWSLi9yYT034cwSRjohn17zcQPNFTs8s153sK9Uv_Yh0-5_5d7-o9zbD-
UqCaRWrllSYZQxLw_HUhb0ta-y4NnJUxfUvc7QuLJSaO0a3oh2MLBZat8u-wsPnXzKQvTtVVF34xK5d69ThFmHEQ4SpzeVRediTG8rjD5vBSeN3E5JyHh6R1DQK9-iml5kjzQUN_lSgVU8DhYLx7wwjSvRkMDvTjiwF4zM1kXZ7DlF1eN3A7IG85e-zRrYEjjm0FkI4Cc7Ripm0pHOChexhcWXzreeZyRMU6Mk3ljxC9w4QH-
cQZ_b3T5pjHxk1VNr1CDrnJy5QDh6XLO6FrLNSRb2l9gz0wo3S6m7HErSgLsPGMHkpDZK31jOanXeHPQz-
eruLHUP0z6yTbpbrn223V70uMXNSpQSZjpL0y8hcxxpNqA6_ql3BQAxlxvfpQ_uT9GrWjQC6iRHM8D0MP0GQsIi92QEAAA=):

    
    
    {#snippet figure(image)}
    	<figure>
    		<img src={image.src} alt={image.caption} width={image.width} height={image.height} />
    		<figcaption>{image.caption}</figcaption>
    	</figure>
    {/snippet}
    
    {#each images as image}
    	{#if image.href}
    		<a href={image.href}>
    			{@render figure(image)}
    		</a>
    	{:else}
    		{@render figure(image)}
    	{/if}
    {/each}

Like function declarations, snippets can have an arbitrary number of
parameters, which can have default values, and you can destructure each
parameter. You cannot use rest parameters, however.

##  Snippet scope

Snippets can be declared anywhere inside your component. They can reference
values declared outside themselves, for example in the `<script>` tag or in
`{#each ...}` blocks
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE12P0QrCMAxFfyWrwhSEvc8p-h1OcG5RC10bmkyQ0n-3HQPBx3vCPUmCemiDrOpLULYbUdXqTKR2Sj6UA7_RCKbMbvJ9Jg33XpMcW9uKQYEAIzJ3T4QD3LSUDE-
PnYA4YET4uOkGMc3W5B3xZrtvbVP9HDas2GqiZHqhMW6Tr9jGbG_oOCMImcUCwrIpFk1FqRyqpRpn0cmjHdAvnrIzuscyq_4nd3dPPD01ukE_NA6qFj9hvMYvGjJADw8BAAA=))...

    
    
    <script>
    	let { message = `it's great to see you!` } = $props();
    </script>
    
    {#snippet hello(name)}
    	<p>hello {name}! {message}!</p>
    {/snippet}
    
    {@render hello('alice')}
    {@render hello('bob')}

...and they are ‘visible’ to everything in the same lexical scope (i.e.
siblings, and children of those siblings):

    
    
    <div>
    	{#snippet x()}
    		{#snippet y()}...{/snippet}
    
    		<!-- this is fine -->
    		{@render y()}
    	{/snippet}
    
    	<!-- this will error, as `y` is not in scope -->
    	{@render y()}
    </div>
    
    <!-- this will also error, as `x` is not in scope -->
    {@render x()}

Snippets can reference themselves and each other
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE2WPTQqDMBCFrxLiRqH1Zysi7TlqF1YnENBJSGJLCYGeo5tesUeosfYH3c2bee_jjaWMd6BpfrAU6x5oTvdS0g01V-mFPkNnYNRaDKrxGxto5FKCIaeu1kYwFkauwsoUWtZYPh_3W5FMY4U2mb3egL9kIwY0rbhgiO-
sDTgjSEqSTvIDs-
jiOP7i_MHuFGAL6p9BtiSbOTl0GtzCuihqE87cqtyam6WRGz_vRcsZh5bmRg3gju4Fptq_kzQBAAA=)):

    
    
    {#snippet blastoff()}
    	<span>🚀</span>
    {/snippet}
    
    {#snippet countdown(n)}
    	{#if n > 0}
    		<span>{n}...</span>
    		{@render countdown(n - 1)}
    	{:else}
    		{@render blastoff()}
    	{/if}
    {/snippet}
    
    {@render countdown(10)}

##  Passing snippets to components

###  Explicit props

Within the template, snippets are values just like any other. As such, they
can be passed to components as props
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3VS247aMBD9lZGpBGwDASRegonaPvQL2qdlH5zYEKvBNvbQLbL875VzAcKyj3PmzJnLGU8UOwqSkd8KJdaCk4TsZS0cyV49wYuJuQiQpGd-N2bu_ooaI1YwJ57hpVYoFDqSEepKKw3mO7VDeTTaIvxiRS1gb_URxvO0ibrS8WanIrHUyiHs7Vmigy28RmyHHmKvDMbMmFq4cQInvGSwTsBYWYoMVhCSB2rBFFPsyl0uruTlR3JZCWvlTXl1Yy_mawiR_rbZKZrellJ-5JQ0RiBUgnFhJ9OGR7HKmwVoilXeIye8DOJGfYCgRlZ3iE876TBsZPX7hPdteO75PC4QaIo8vwNPePmANQ2fMeEFHrLD7rR1jTNkW986E8C3KwfwVr8HSHOSEBT_kGRozyIkn_zQveXDL3rIfPJHtUDwzShJd_Qk3gQCbOGLsdq4yfTRJopRuin3I7nv6kL7ARRjmLdBDG3uv1mhuLA3V2mKtqNEf_oCn8p9aN-
WYqH5peP4kWBl1UwJzAEPT9U7K--
0fRrrWnPTXpCm1_EVdXjpNmlA8G1hPPyM1fKgMqjFHjctXGjLhZ05w0qpDhksGrybuNEHtJnCalZWsuaTlfq6nPaaBSv_HKw-K57BjzOiVj9ZKQYKzQjZodYFqydYTRN4gPhVzTDO2xnma3HsVWjaLjT8nbfwHy7Q5f2dBAAA)):

    
    
    <script>
    	import Table from './Table.svelte';
    
    	const fruits = [
    		{ name: 'apples', qty: 5, price: 2 },
    		{ name: 'bananas', qty: 10, price: 1 },
    		{ name: 'cherries', qty: 20, price: 0.5 }
    	];
    </script>
    
    {#snippet header()}
    	<th>fruit</th>
    	<th>qty</th>
    	<th>price</th>
    	<th>total</th>
    {/snippet}
    
    {#snippet row(d)}
    	<td>{d.name}</td>
    	<td>{d.qty}</td>
    	<td>{d.price}</td>
    	<td>{d.qty * d.price}</td>
    {/snippet}
    
    <Table data={fruits} {header} {row} />

Think about it like passing content instead of data to a component. The
concept is similar to slots in web components.

###  Implicit props

As an authoring convenience, snippets declared directly _inside_ a component
implicitly become props _on_ the component
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3VSTa_aMBD8Kyu_SkAbCA-
JSzBR20N_QXt6vIMTO8SqsY29tI2s_PcqTiB8vaPHs7MzuxuIZgdBMvJLo0QlOElIJZXwJHsLBBvb_XUASc7Mb9Yu_B-
hsMMK5sUzvDQahUZPMkJ96aTFfKd3KA_WOISfrFACKmcOMFmk8TWUTjY73RFLoz1C5U4SPWzhrcN2GKDrlcGEWauEnyRwxCaDdQLWyVJksII2uaMWTDPNLtzX5YX8-kgua-
GcHJVXI3u5WEPb0d83O03TMZSmfRzOkG1Db7mNacOL19JagVALxoWbztq-H8U6j0SaYp2P2BGbOyQ2v8PQIFMXLKRDk177pq0zf6d8bMrzwBdd0pamyPMb-
IjNEzS2f86Gz_Dwf-2F9nvNSUJQ_EOSoTuJNvngqK5v4Pas7n4-OCwlEEJcQTIMO-nSQwtb-
GSdsX46e9gbRoP9yGQ11I0rEuycunu6PHx1QnPhxm3SFN15MOlYEFJZtf0dUywMbwZOeBGsrKNLYB54-1R9WNqVdki7usim6VmQphf7mnpshiQRhNAXdoOfMyX3OgMlKtz0cGEcF27uLSul3mewjPjgOOoDukxjPS9rqfh0pb-8zs6aBSt_7505aZ7B9xOi0T9YKW4UooVsr0zB1BTrWQJ3EL-
oWcZ572GxFoezCk37QLe3897-B2i2U62uBAAA)):

    
    
    <!-- this is semantically the same as the above -->
    <Table data={fruits}>
    	{#snippet header()}
    		<th>fruit</th>
    		<th>qty</th>
    		<th>price</th>
    		<th>total</th>
    	{/snippet}
    
    	{#snippet row(d)}
    		<td>{d.name}</td>
    		<td>{d.qty}</td>
    		<td>{d.price}</td>
    		<td>{d.qty * d.price}</td>
    	{/snippet}
    </Table>

###  Implicit children snippet

Any content inside the component tags that is _not_ a snippet declaration
implicitly becomes part of the `children` snippet
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3WOQQrCMBBFrzIMggql3ddY1Du4si5sOmIwnYRkFKX07lKqglqX8_7_w2uRDw1hjlsWI5ZqTPBoLEXMdy3K3fdZDzB5Ndfep_FKVnpWHSKNce1YiCVijirqYLwUJQOYxrsgsLmIOIZjcA1M02w4n-PpomSVvTclqyEutDX6DA2pZ7_ABIVugrmEC3XJH92P55_G39GodCmWBFrQJ2PrQAwdLGHig_NxNv9xrQa1dhWIawrv1Wzeqawa8953D-8QOmaEAQAA)):

App

    
    
    <Button>click me</Button>

Button

    
    
    <script>
    	let { children } = $props();
    </script>
    
    <!-- result will be <button>click me</button> -->
    <button>{@render children()}</button>
    
    
    <script lang="ts">
    	let { children } = $props();
    </script>
    
    <!-- result will be <button>click me</button> -->
    <button>{@render children()}</button>

> Note that you cannot have a prop called `children` if you also have content
> inside the component — for this reason, you should avoid having props with
> that name

###  Optional snippet props

You can declare snippet props as being optional. You can either use optional
chaining to not render anything if the snippet isn’t set...

    
    
    <script>
    	let { children } = $props();
    </script>
    
    {@render children?.()}

...or use an `#if` block to render fallback content:

    
    
    <script>
    	let { children } = $props();
    </script>
    
    {#if children}
    	{@render children()}
    {:else}
    	fallback content
    {/if}

##  Typing snippets

Snippets implement the `Snippet` interface imported from `'svelte'`:

    
    
    <script lang="ts">
    	import type { Snippet } from 'svelte';
    
    	interface Props {
    		data: any[];
    		children: Snippet;
    		row: Snippet<[any]>;
    	}
    
    	let { data, children, row }: Props = $props();
    </script>

With this change, red squigglies will appear if you try and use the component
without providing a `data` prop and a `row` snippet. Notice that the type
argument provided to `Snippet` is a tuple, since snippets can have multiple
parameters.

We can tighten things up further by declaring a generic, so that `data` and
`row` refer to the same type:

    
    
    <script lang="ts" generics="T">
    	import type { Snippet } from 'svelte';
    
    	let {
    		data,
    		children,
    		row
    	}: {
    		data: T[];
    		children: Snippet;
    		row: Snippet<[T]>;
    	} = $props();
    </script>

##  Exporting snippets

Snippets declared at the top level of a `.svelte` file can be exported from a
`<script module>` for use in other components, provided they don’t reference
any declarations in a non-module `<script>` (whether directly or indirectly,
via other snippets)
([demo](https://svelte.dev/playground/untitled#H4sIAAAAAAAAE3WPwY7CMAxEf8UyB1hRgdhjl13Bga8gHFJipEqtGyUGFUX5dxJUtEB3b9bYM_MckHVLWOKut50TMuC5tpbEY4GnuiGP5T6gXG0-ykLSB8vW2oW_UCNZq7Snv_Rjx0Kc4kpc-6OrrfwoVlK3uQ4CaGMgwsl1LUwXy0f54J9-KV4vf20cNo7YkMu22aqAz4-oOLUI9YKluDPF4h_at-
hX5PFyzA1tZ84N3fGpf8YfUU6GvDumLqDKmEqCjjCHUEX4hqDTWCU5PJ6Or38c4g1cPu9tnAEAAA==)):

    
    
    <script module>
    	export { add };
    </script>
    
    {#snippet add(a, b)}
    	{a} + {b} = {a + b}
    {/snippet}

> This requires Svelte 5.5.0 or newer

##  Programmatic snippets

Snippets can be created programmatically with the
[`createRawSnippet`](svelte#createRawSnippet) API. This is intended for
advanced use cases.

##  Snippets and slots

In Svelte 4, content can be passed to components using [slots](legacy-slots).
Snippets are more powerful and flexible, and as such slots are deprecated in
Svelte 5.

# Stores

### On this page

  * [Stores](stores)
  * When to use stores
  * svelte/store
  * Store contract

A _store_ is an object that allows reactive access to a value via a simple
_store contract_. The [`svelte/store` module](https://svelte.dev/docs/svelte-
store) contains minimal store implementations which fulfil this contract.

Any time you have a reference to a store, you can access its value inside a
component by prefixing it with the `$` character. This causes Svelte to
declare the prefixed variable, subscribe to the store at component
initialisation and unsubscribe when appropriate.

Assignments to `$`-prefixed variables require that the variable be a writable
store, and will result in a call to the store’s `.set` method.

Note that the store must be declared at the top level of the component — not
inside an `if` block or a function, for example.

Local variables (that do not represent store values) must _not_ have a `$`
prefix.

    
    
    <script>
    	import { writable } from 'svelte/store';
    
    	const count = writable(0);
    	console.log($count); // logs 0
    
    	count.set(1);
    	console.log($count); // logs 1
    
    	$count = 2;
    	console.log($count); // logs 2
    </script>

##  When to use stores

Prior to Svelte 5, stores were the go-to solution for creating cross-component
reactive states or extracting logic. With runes, these use cases have greatly
diminished.

  * when extracting logic, it’s better to take advantage of runes’ universal reactivity: You can use runes outside the top level of components and even place them into JavaScript or TypeScript files (using a `.svelte.js` or `.svelte.ts` file ending)
  * when creating shared state, you can create a `$state` object containing the values you need and then manipulate said state

state.svelte

    
    
    export const userState = $state({
    	name: 'name',
    	/* ... */
    });

App

    
    
    <script>
    	import { userState } from './state.svelte.js';
    </script>
    
    <p>User name: {userState.name}</p>
    <button onclick={() => {
    	userState.name = 'new name';
    }}>
    	change name
    </button>
    
    
    <script lang="ts">
    	import { userState } from './state.svelte.js';
    </script>
    
    <p>User name: {userState.name}</p>
    <button onclick={() => {
    	userState.name = 'new name';
    }}>
    	change name
    </button>

Stores are still a good solution when you have complex asynchronous data
streams or it’s important to have more manual control over updating values or
listening to changes. If you’re familiar with RxJs and want to reuse that
knowledge, the `$` also comes in handy for you.

##  svelte/store

The `svelte/store` module contains a minimal store implementation which fulfil
the store contract. It provides methods for creating stores that you can
update from the outside, stores you can only update from the inside, and for
combining and deriving stores.

###  writable

Function that creates a store which has values that can be set from ‘outside’
components. It gets created as an object with additional `set` and `update`
methods.

`set` is a method that takes one argument which is the value to be set. The
store value gets set to the value of the argument if the store value is not
already equal to it.

`update` is a method that takes one argument which is a callback. The callback
takes the existing store value as its argument and returns the new value to be
set to the store.

store

    
    
    import { writable } from 'svelte/store';
    
    const count = writable(0);
    
    count.subscribe((value) => {
    	console.log(value);
    }); // logs '0'
    
    count.set(1); // logs '1'
    
    count.update((n) => n + 1); // logs '2'

If a function is passed as the second argument, it will be called when the
number of subscribers goes from zero to one (but not from one to two, etc).
That function will be passed a `set` function which changes the value of the
store, and an `update` function which works like the `update` method on the
store, taking a callback to calculate the store’s new value from its old
value. It must return a `stop` function that is called when the subscriber
count goes from one to zero.

store

    
    
    import { writable } from 'svelte/store';
    
    const count = writable(0, () => {
    	console.log('got a subscriber');
    	return () => console.log('no more subscribers');
    });
    
    count.set(1); // does nothing
    
    const unsubscribe = count.subscribe((value) => {
    	console.log(value);
    }); // logs 'got a subscriber', then '1'
    
    unsubscribe(); // logs 'no more subscribers'

Note that the value of a `writable` is lost when it is destroyed, for example
when the page is refreshed. However, you can write your own logic to sync the
value to for example the `localStorage`.

###  readable

Creates a store whose value cannot be set from ‘outside’, the first argument
is the store’s initial value, and the second argument to `readable` is the
same as the second argument to `writable`.

    
    
    import { readable } from 'svelte/store';
    
    const time = readable(new Date(), (set) => {
    	set(new Date());
    
    	const interval = setInterval(() => {
    		set(new Date());
    	}, 1000);
    
    	return () => clearInterval(interval);
    });
    
    const ticktock = readable('tick', (set, update) => {
    	const interval = setInterval(() => {
    		update((sound) => (sound === 'tick' ? 'tock' : 'tick'));
    	}, 1000);
    
    	return () => clearInterval(interval);
    });

###  derived

Derives a store from one or more other stores. The callback runs initially
when the first subscriber subscribes and then whenever the store dependencies
change.

In the simplest version, `derived` takes a single store, and the callback
returns a derived value.

    
    
    import { derived } from 'svelte/store';
    
    const doubled = derived(a, ($a) => $a * 2);

The callback can set a value asynchronously by accepting a second argument,
`set`, and an optional third argument, `update`, calling either or both of
them when appropriate.

In this case, you can also pass a third argument to `derived` — the initial
value of the derived store before `set` or `update` is first called. If no
initial value is specified, the store’s initial value will be `undefined`.

    
    
    import { derived } from 'svelte/store';
    
    const delayed = derived(
    	a,
    	($a, set) => {
    		setTimeout(() => set($a), 1000);
    	},
    	2000
    );
    
    const delayedIncrement = derived(a, ($a, set, update) => {
    	set($a);
    	setTimeout(() => update((x) => x + 1), 1000);
    	// every time $a produces a value, this produces two
    	// values, $a immediately and then $a + 1 a second later
    });

If you return a function from the callback, it will be called when a) the
callback runs again, or b) the last subscriber unsubscribes.

    
    
    import { derived } from 'svelte/store';
    
    const tick = derived(
    	frequency,
    	($frequency, set) => {
    		const interval = setInterval(() => {
    			set(Date.now());
    		}, 1000 / $frequency);
    
    		return () => {
    			clearInterval(interval);
    		};
    	},
    	2000
    );

In both cases, an array of arguments can be passed as the first argument
instead of a single store.

    
    
    import { derived } from 'svelte/store';
    
    const summed = derived([a, b], ([$a, $b]) => $a + $b);
    
    const delayed = derived([a, b], ([$a, $b], set) => {
    	setTimeout(() => set($a + $b), 1000);
    });

###  readonly

This simple helper function makes a store readonly. You can still subscribe to
the changes from the original one using this new readable store.

    
    
    import { readonly, writable } from 'svelte/store';
    
    const writableStore = writable(1);
    const readableStore = readonly(writableStore);
    
    readableStore.subscribe(console.log);
    
    writableStore.set(2); // console: 2
    readableStore.set(2); // ERROR

###  get

Generally, you should read the value of a store by subscribing to it and using
the value as it changes over time. Occasionally, you may need to retrieve the
value of a store to which you’re not subscribed. `get` allows you to do so.

> This works by creating a subscription, reading the value, then
> unsubscribing. It’s therefore not recommended in hot code paths.
    
    
    import { get } from 'svelte/store';
    
    const value = get(store);

##  Store contract

    
    
    store = { subscribe: (subscription: (value: any) => void) => (() => void), set?: (value: any) => void }

You can create your own stores without relying on
[`svelte/store`](https://svelte.dev/docs/svelte-store), by implementing the
_store contract_ :

  1. A store must contain a `.subscribe` method, which must accept as its argument a subscription function. This subscription function must be immediately and synchronously called with the store’s current value upon calling `.subscribe`. All of a store’s active subscription functions must later be synchronously called whenever the store’s value changes.
  2. The `.subscribe` method must return an unsubscribe function. Calling an unsubscribe function must stop its subscription, and its corresponding subscription function must not be called again by the store.
  3. A store may _optionally_ contain a `.set` method, which must accept as its argument a new value for the store, and which synchronously calls all of the store’s active subscription functions. Such a store is called a _writable store_.

For interoperability with RxJS Observables, the `.subscribe` method is also
allowed to return an object with an `.unsubscribe` method, rather than return
the unsubscription function directly. Note however that unless `.subscribe`
synchronously calls the subscription (which is not required by the Observable
spec), Svelte will see the value of the store as `undefined` until it does.

# style:

### On this page

  * [style:](style)

The `style:` directive provides a shorthand for setting multiple styles on an
element.

    
    
    <!-- These are equivalent -->
    <div style:color="red">...</div>
    <div style="color: red;">...</div>

The value can contain arbitrary expressions:

    
    
    <div style:color={myColor}>...</div>

The shorthand form is allowed:

    
    
    <div style:color>...</div>

Multiple styles can be set on a single element:

    
    
    <div style:color style:width="12rem" style:background-color={darkMode ? 'black' : 'white'}>...</div>

To mark a style as important, use the `|important` modifier:

    
    
    <div style:color|important="red">...</div>

When `style:` directives are combined with `style` attributes, the directives
will take precedence:

    
    
    <div style="color: blue;" style:color="red">This will be red</div>

# svelte/action

### On this page

  * [svelte/action](svelte-action)
  * Action
  * ActionReturn

##  Action

Actions are functions that are called when an element is created. You can use
this interface to type such actions. The following example defines an action
that only works on `<div>` elements and optionally accepts a parameter which
it has a default value for:

    
    
    export const myAction: Action<HTMLDivElement, { someProperty: boolean } | undefined> = (node, param = { someProperty: true }) => {
    	// ...
    }

`Action<HTMLDivElement>` and `Action<HTMLDivElement, undefined>` both signal
that the action accepts no parameters.

You can return an object with methods `update` and `destroy` from the function
and type which additional attributes and events it has. See interface
`ActionReturn` for more details.

    
    
    interface Action<
    	Element = HTMLElement,
    	Parameter = undefined,
    	Attributes extends Record<string, any> = Record<
    		never,
    		any
    	>
    > {…}
    
    
    <Node extends Element>(
    	...args: undefined extends Parameter
    		? [node: Node, parameter?: Parameter]
    		: [node: Node, parameter: Parameter]
    ): void | ActionReturn<Parameter, Attributes>;

##  ActionReturn

Actions can return an object containing the two properties defined in this
interface. Both are optional.

  * update: An action can have a parameter. This method will be called whenever that parameter changes, immediately after Svelte has applied updates to the markup. `ActionReturn` and `ActionReturn<undefined>` both mean that the action accepts no parameters.
  * destroy: Method that is called after the element is unmounted

Additionally, you can specify which additional attributes and events the
action enables on the applied element. This applies to TypeScript typings only
and has no effect at runtime.

Example usage:

    
    
    interface Attributes {
    	newprop?: string;
    	'on:event': (e: CustomEvent<boolean>) => void;
    }
    
    export function myAction(node: HTMLElement, parameter: Parameter): ActionReturn<Parameter, Attributes> {
    	// ...
    	return {
    		update: (updatedParameter) => {...},
    		destroy: () => {...}
    	};
    }
    
    
    interface ActionReturn<
    	Parameter = undefined,
    	Attributes extends Record<string, any> = Record<
    		never,
    		any
    	>
    > {…}
    
    
    update?: (parameter: Parameter) => void;
    
    
    destroy?: () => void;

# svelte/animate

### On this page

  * [svelte/animate](svelte-animate)
  * flip
  * AnimationConfig
  * FlipParams

    
    
    import { flip } from 'svelte/animate';

##  flip

The flip function calculates the start and end position of an element and
animates between them, translating the x and y values. `flip` stands for
[First, Last, Invert, Play](https://aerotwist.com/blog/flip-your-animations/).

    
    
    function flip(
    	node: Element,
    	{
    		from,
    		to
    	}: {
    		from: DOMRect;
    		to: DOMRect;
    	},
    	params?: FlipParams
    ): AnimationConfig;

##  AnimationConfig

    
    
    interface AnimationConfig {…}
    
    
    delay?: number;
    
    
    duration?: number;
    
    
    easing?: (t: number) => number;
    
    
    css?: (t: number, u: number) => string;
    
    
    tick?: (t: number, u: number) => void;

##  FlipParams

    
    
    interface FlipParams {…}
    
    
    delay?: number;
    
    
    duration?: number | ((len: number) => number);
    
    
    easing?: (t: number) => number;

# svelte/attachments

### On this page

  * [svelte/attachments](svelte-attachments)
  * createAttachmentKey
  * fromAction
  * Attachment

    
    
    import { createAttachmentKey, fromAction } from 'svelte/attachments';

##  createAttachmentKey

> Available since 5.29

Creates an object key that will be recognised as an attachment when the object
is spread onto an element, as a programmatic alternative to using `{@attach
...}`. This can be useful for library authors, though is generally not needed
when building an app.

    
    
    <script>
    	import { createAttachmentKey } from 'svelte/attachments';
    
    	const props = {
    		class: 'cool',
    		onclick: () => alert('clicked'),
    		[createAttachmentKey()]: (node) => {
    			node.textContent = 'attached!';
    		}
    	};
    </script>
    
    <button {...props}>click me</button>
    
    
    function createAttachmentKey(): symbol;

##  fromAction

Converts an [action](use) into an [attachment](@attach) keeping the same
behavior. It’s useful if you want to start using attachments on components but
you have actions provided by a library.

Note that the second argument, if provided, must be a function that _returns_
the argument to the action function, not the argument itself.

    
    
    <!-- with an action -->
    <div use:foo={bar}>...</div>
    
    <!-- with an attachment -->
    <div {@attach fromAction(foo, () => bar)}>...</div>
    
    
    function fromAction<
    	E extends EventTarget,
    	T extends unknown
    >(
    	action:
    		| Action<E, T>
    		| ((element: E, arg: T) => void | ActionReturn<T>),
    	fn: () => T
    ): Attachment<E>;
    
    
    function fromAction<E extends EventTarget>(
    	action:
    		| Action<E, void>
    		| ((element: E) => void | ActionReturn<void>)
    ): Attachment<E>;

##  Attachment

An [attachment](@attach) is a function that runs when an element is mounted to
the DOM, and optionally returns a function that is called when the element is
later removed.

It can be attached to an element with an `{@attach ...}` tag, or by spreading
an object containing a property created with [`createAttachmentKey`](svelte-
attachments#createAttachmentKey).

    
    
    interface Attachment<T extends EventTarget = Element> {…}
    
    
    (element: T): void | (() => void);

# <svelte:body>

### On this page

  * [<svelte:body>](svelte-body)

    
    
    <svelte:body onevent={handler} />

Similarly to `<svelte:window>`, this element allows you to add listeners to
events on `document.body`, such as `mouseenter` and `mouseleave`, which don’t
fire on `window`. It also lets you use [actions](use) on the `<body>` element.

As with `<svelte:window>` and `<svelte:document>`, this element may only
appear at the top level of your component and must never be inside a block or
element.

    
    
    <svelte:body onmouseenter={handleMouseenter} onmouseleave={handleMouseleave} use:someAction />

# <svelte:boundary>

### On this page

  * [<svelte:boundary>](svelte-boundary)
  * Properties

    
    
    <svelte:boundary onerror={handler}>...</svelte:boundary>

> This feature was added in 5.3.0

Boundaries allow you to guard against errors in part of your app from breaking
the app as a whole, and to recover from those errors.

If an error occurs while rendering or updating the children of a
`<svelte:boundary>`, or running any [`$effect`]($effect) functions contained
therein, the contents will be removed.

Errors occurring outside the rendering process (for example, in event handlers
or after a `setTimeout` or async work) are _not_ caught by error boundaries.

##  Properties

For the boundary to do anything, one or both of `failed` and `onerror` must be
provided.

###  failed

If a `failed` snippet is provided, it will be rendered with the error that was
thrown, and a `reset` function that recreates the contents
([demo](https://svelte.dev/playground/hello-
world#H4sIAAAAAAAAE3VRy26DMBD8lS2tFCIh6JkAUlWp39Cq9EBg06CAbdlLArL87zWGKk8ORnhmd3ZnrD1WtOjFXqKO2BDGW96xqpBD5gXerm5QefG39mgQY9EIWHxueRMinLosti0UPsJLzggZKTeilLWgLGc51a3gkuCjKQ7DO7cXZotgJ3kLqzC6hmex1SZnSXTWYHcrj8LJjWTk0PHoZ8VqIdCOKayPykcpuQxAokJaG1dGybYj4gw4K5u6PKTasSbjXKgnIDlA8VvUdo-
pzonraBY2bsH7HAl78mKSHZpgIcuHjq9jXSpZSLixRlveKYQUXhQVhL6GPobXAAb7BbNeyvNUs4qfRg3OnELLj5hqH9eQZqCnoBwR9lYcQxuVXeBzc8kMF8yXY4yNJ5oGiUzP_aaf_waTRGJib5_Ad3P_vbCuaYxzeNpbU0eUMPAOKh7Yw1YErgtoXyuYlPLzc10_xo_5A91zkQL_AgAA)):

    
    
    <svelte:boundary>
    	<FlakyComponent />
    
    	{#snippet failed(error, reset)}
    		<button onclick={reset}>oops! try again</button>
    	{/snippet}
    </svelte:boundary>

> As with [snippets passed to components](snippet#Passing-snippets-to-
> components), the `failed` snippet can be passed explicitly as a property...
>  
>  
>     <svelte:boundary {failed}>...</svelte:boundary>
>
> ...or implicitly by declaring it directly inside the boundary, as in the
> example above.

###  onerror

If an `onerror` function is provided, it will be called with the same two
`error` and `reset` arguments. This is useful for tracking the error with an
error reporting service...

    
    
    <svelte:boundary onerror={(e) => report(e)}>
    	...
    </svelte:boundary>

...or using `error` and `reset` outside the boundary itself:

    
    
    <script>
    	let error = $state(null);
    	let reset = $state(() => {});
    
    	function onerror(e, r) {
    		error = e;
    		reset = r;
    	}
    </script>
    
    <svelte:boundary {onerror}>
    	<FlakyComponent />
    </svelte:boundary>
    
    {#if error}
    	<button onclick={() => {
    		error = null;
    		reset();
    	}}>
    		oops! try again
    	</button>
    {/if}

If an error occurs inside the `onerror` function (or if you rethrow the
error), it will be handled by a parent boundary if such exists.

# svelte/compiler

### On this page

  * [svelte/compiler](svelte-compiler)
  * VERSION
  * compile
  * compileModule
  * migrate
  * parse
  * preprocess
  * walk
  * AST
  * CompileError
  * CompileOptions
  * CompileResult
  * MarkupPreprocessor
  * ModuleCompileOptions
  * Preprocessor
  * PreprocessorGroup
  * Processed
  * Warning

    
    
    import {
    	VERSION,
    	compile,
    	compileModule,
    	migrate,
    	parse,
    	preprocess,
    	walk
    } from 'svelte/compiler';

##  VERSION

The current version, as set in package.json.

    
    
    const VERSION: string;

##  compile

`compile` converts your `.svelte` source code into a JavaScript module that
exports a component

    
    
    function compile(
    	source: string,
    	options: CompileOptions
    ): CompileResult;

##  compileModule

`compileModule` takes your JavaScript source code containing runes, and turns
it into a JavaScript module.

    
    
    function compileModule(
    	source: string,
    	options: ModuleCompileOptions
    ): CompileResult;

##  migrate

Does a best-effort migration of Svelte code towards using runes, event
attributes and render tags. May throw an error if the code is too complex to
migrate automatically.

    
    
    function migrate(
    	source: string,
    	{
    		filename,
    		use_ts
    	}?:
    		| {
    				filename?: string;
    				use_ts?: boolean;
    		  }
    		| undefined
    ): {
    	code: string;
    };

##  parse

The parse function parses a component, returning only its abstract syntax
tree.

The `modern` option (`false` by default in Svelte 5) makes the parser return a
modern AST instead of the legacy AST. `modern` will become `true` by default
in Svelte 6, and the option will be removed in Svelte 7.

    
    
    function parse(
    	source: string,
    	options: {
    		filename?: string;
    		modern: true;
    		loose?: boolean;
    	}
    ): AST.Root;
    
    
    function parse(
    	source: string,
    	options?:
    		| {
    				filename?: string;
    				modern?: false;
    				loose?: boolean;
    		  }
    		| undefined
    ): Record<string, any>;

##  preprocess

The preprocess function provides convenient hooks for arbitrarily transforming
component source code. For example, it can be used to convert a `<style
lang="sass">` block into vanilla CSS.

    
    
    function preprocess(
    	source: string,
    	preprocessor: PreprocessorGroup | PreprocessorGroup[],
    	options?:
    		| {
    				filename?: string;
    		  }
    		| undefined
    ): Promise<Processed>;

##  walk

> Replace this with `import { walk } from 'estree-walker'`
    
    
    function walk(): never;

##  AST

    
    
    namespace AST {
    	export interface BaseNode {
    		type: string;
    		start: number;
    		end: number;
    	}
    
    	export interface Fragment {
    		type: 'Fragment';
    		nodes: Array<
    			Text | Tag | ElementLike | Block | Comment
    		>;
    	}
    
    	export interface Root extends BaseNode {
    		type: 'Root';
    		/**
    		 * Inline options provided by `<svelte:options>` — these override options passed to `compile(...)`
    		 */
    		options: SvelteOptions | null;
    		fragment: Fragment;
    		/** The parsed `<style>` element, if exists */
    		css: AST.CSS.StyleSheet | null;
    		/** The parsed `<script>` element, if exists */
    		instance: Script | null;
    		/** The parsed `<script module>` element, if exists */
    		module: Script | null;
    	}
    
    	export interface SvelteOptions {
    		// start/end info (needed for warnings and for our Prettier plugin)
    		start: number;
    		end: number;
    		// options
    		runes?: boolean;
    		immutable?: boolean;
    		accessors?: boolean;
    		preserveWhitespace?: boolean;
    		namespace?: Namespace;
    		css?: 'injected';
    		customElement?: {
    			tag?: string;
    			shadow?: 'open' | 'none';
    			props?: Record<
    				string,
    				{
    					attribute?: string;
    					reflect?: boolean;
    					type?:
    						| 'Array'
    						| 'Boolean'
    						| 'Number'
    						| 'Object'
    						| 'String';
    				}
    			>;
    			/**
    			 * Is of type
    			 * ```ts
    			 * (ceClass: new () => HTMLElement) => new () => HTMLElement
    			 * ```
    			 */
    			extend?: ArrowFunctionExpression | Identifier;
    		};
    		attributes: Attribute[];
    	}
    
    	/** Static text */
    	export interface Text extends BaseNode {
    		type: 'Text';
    		/** Text with decoded HTML entities */
    		data: string;
    		/** The original text, with undecoded HTML entities */
    		raw: string;
    	}
    
    	/** A (possibly reactive) template expression — `{...}` */
    	export interface ExpressionTag extends BaseNode {
    		type: 'ExpressionTag';
    		expression: Expression;
    	}
    
    	/** A (possibly reactive) HTML template expression — `{@html ...}` */
    	export interface HtmlTag extends BaseNode {
    		type: 'HtmlTag';
    		expression: Expression;
    	}
    
    	/** An HTML comment */
    	// TODO rename to disambiguate
    	export interface Comment extends BaseNode {
    		type: 'Comment';
    		/** the contents of the comment */
    		data: string;
    	}
    
    	/** A `{@const ...}` tag */
    	export interface ConstTag extends BaseNode {
    		type: 'ConstTag';
    		declaration: VariableDeclaration & {
    			declarations: [
    				VariableDeclarator & {
    					id: Pattern;
    					init: Expression;
    				}
    			];
    		};
    	}
    
    	/** A `{@debug ...}` tag */
    	export interface DebugTag extends BaseNode {
    		type: 'DebugTag';
    		identifiers: Identifier[];
    	}
    
    	/** A `{@render foo(...)} tag */
    	export interface RenderTag extends BaseNode {
    		type: 'RenderTag';
    		expression:
    			| SimpleCallExpression
    			| (ChainExpression & {
    					expression: SimpleCallExpression;
    			  });
    	}
    
    	/** A `{@attach foo(...)} tag */
    	export interface AttachTag extends BaseNode {
    		type: 'AttachTag';
    		expression: Expression;
    	}
    
    	/** An `animate:` directive */
    	export interface AnimateDirective extends BaseNode {
    		type: 'AnimateDirective';
    		/** The 'x' in `animate:x` */
    		name: string;
    		/** The y in `animate:x={y}` */
    		expression: null | Expression;
    	}
    
    	/** A `bind:` directive */
    	export interface BindDirective extends BaseNode {
    		type: 'BindDirective';
    		/** The 'x' in `bind:x` */
    		name: string;
    		/** The y in `bind:x={y}` */
    		expression:
    			| Identifier
    			| MemberExpression
    			| SequenceExpression;
    	}
    
    	/** A `class:` directive */
    	export interface ClassDirective extends BaseNode {
    		type: 'ClassDirective';
    		/** The 'x' in `class:x` */
    		name: 'class';
    		/** The 'y' in `class:x={y}`, or the `x` in `class:x` */
    		expression: Expression;
    	}
    
    	/** A `let:` directive */
    	export interface LetDirective extends BaseNode {
    		type: 'LetDirective';
    		/** The 'x' in `let:x` */
    		name: string;
    		/** The 'y' in `let:x={y}` */
    		expression:
    			| null
    			| Identifier
    			| ArrayExpression
    			| ObjectExpression;
    	}
    
    	/** An `on:` directive */
    	export interface OnDirective extends BaseNode {
    		type: 'OnDirective';
    		/** The 'x' in `on:x` */
    		name: string;
    		/** The 'y' in `on:x={y}` */
    		expression: null | Expression;
    		modifiers: string[];
    	}
    
    	/** A `style:` directive */
    	export interface StyleDirective extends BaseNode {
    		type: 'StyleDirective';
    		/** The 'x' in `style:x` */
    		name: string;
    		/** The 'y' in `style:x={y}` */
    		value:
    			| true
    			| ExpressionTag
    			| Array<ExpressionTag | Text>;
    		modifiers: Array<'important'>;
    	}
    
    	// TODO have separate in/out/transition directives
    	/** A `transition:`, `in:` or `out:` directive */
    	export interface TransitionDirective extends BaseNode {
    		type: 'TransitionDirective';
    		/** The 'x' in `transition:x` */
    		name: string;
    		/** The 'y' in `transition:x={y}` */
    		expression: null | Expression;
    		modifiers: Array<'local' | 'global'>;
    		/** True if this is a `transition:` or `in:` directive */
    		intro: boolean;
    		/** True if this is a `transition:` or `out:` directive */
    		outro: boolean;
    	}
    
    	/** A `use:` directive */
    	export interface UseDirective extends BaseNode {
    		type: 'UseDirective';
    		/** The 'x' in `use:x` */
    		name: string;
    		/** The 'y' in `use:x={y}` */
    		expression: null | Expression;
    	}
    
    	interface BaseElement extends BaseNode {
    		name: string;
    		attributes: Array<
    			Attribute | SpreadAttribute | Directive | AttachTag
    		>;
    		fragment: Fragment;
    	}
    
    	export interface Component extends BaseElement {
    		type: 'Component';
    	}
    
    	export interface TitleElement extends BaseElement {
    		type: 'TitleElement';
    		name: 'title';
    	}
    
    	export interface SlotElement extends BaseElement {
    		type: 'SlotElement';
    		name: 'slot';
    	}
    
    	export interface RegularElement extends BaseElement {
    		type: 'RegularElement';
    	}
    
    	export interface SvelteBody extends BaseElement {
    		type: 'SvelteBody';
    		name: 'svelte:body';
    	}
    
    	export interface SvelteComponent extends BaseElement {
    		type: 'SvelteComponent';
    		name: 'svelte:component';
    		expression: Expression;
    	}
    
    	export interface SvelteDocument extends BaseElement {
    		type: 'SvelteDocument';
    		name: 'svelte:document';
    	}
    
    	export interface SvelteElement extends BaseElement {
    		type: 'SvelteElement';
    		name: 'svelte:element';
    		tag: Expression;
    	}
    
    	export interface SvelteFragment extends BaseElement {
    		type: 'SvelteFragment';
    		name: 'svelte:fragment';
    	}
    
    	export interface SvelteBoundary extends BaseElement {
    		type: 'SvelteBoundary';
    		name: 'svelte:boundary';
    	}
    
    	export interface SvelteHead extends BaseElement {
    		type: 'SvelteHead';
    		name: 'svelte:head';
    	}
    
    	/** This is only an intermediate representation while parsing, it doesn't exist in the final AST */
    	export interface SvelteOptionsRaw extends BaseElement {
    		type: 'SvelteOptions';
    		name: 'svelte:options';
    	}
    
    	export interface SvelteSelf extends BaseElement {
    		type: 'SvelteSelf';
    		name: 'svelte:self';
    	}
    
    	export interface SvelteWindow extends BaseElement {
    		type: 'SvelteWindow';
    		name: 'svelte:window';
    	}
    
    	/** An `{#each ...}` block */
    	export interface EachBlock extends BaseNode {
    		type: 'EachBlock';
    		expression: Expression;
    		/** The `entry` in `{#each item as entry}`. `null` if `as` part is omitted */
    		context: Pattern | null;
    		body: Fragment;
    		fallback?: Fragment;
    		index?: string;
    		key?: Expression;
    	}
    
    	/** An `{#if ...}` block */
    	export interface IfBlock extends BaseNode {
    		type: 'IfBlock';
    		elseif: boolean;
    		test: Expression;
    		consequent: Fragment;
    		alternate: Fragment | null;
    	}
    
    	/** An `{#await ...}` block */
    	export interface AwaitBlock extends BaseNode {
    		type: 'AwaitBlock';
    		expression: Expression;
    		// TODO can/should we move these inside the ThenBlock and CatchBlock?
    		/** The resolved value inside the `then` block */
    		value: Pattern | null;
    		/** The rejection reason inside the `catch` block */
    		error: Pattern | null;
    		pending: Fragment | null;
    		then: Fragment | null;
    		catch: Fragment | null;
    	}
    
    	export interface KeyBlock extends BaseNode {
    		type: 'KeyBlock';
    		expression: Expression;
    		fragment: Fragment;
    	}
    
    	export interface SnippetBlock extends BaseNode {
    		type: 'SnippetBlock';
    		expression: Identifier;
    		parameters: Pattern[];
    		typeParams?: string;
    		body: Fragment;
    	}
    
    	export interface Attribute extends BaseNode {
    		type: 'Attribute';
    		name: string;
    		/**
    		 * Quoted/string values are represented by an array, even if they contain a single expression like `"{x}"`
    		 */
    		value:
    			| true
    			| ExpressionTag
    			| Array<Text | ExpressionTag>;
    	}
    
    	export interface SpreadAttribute extends BaseNode {
    		type: 'SpreadAttribute';
    		expression: Expression;
    	}
    
    	export interface Script extends BaseNode {
    		type: 'Script';
    		context: 'default' | 'module';
    		content: Program;
    		attributes: Attribute[];
    	}
    
    	export type AttributeLike =
    		| Attribute
    		| SpreadAttribute
    		| Directive;
    
    	export type Directive =
    		| AST.AnimateDirective
    		| AST.BindDirective
    		| AST.ClassDirective
    		| AST.LetDirective
    		| AST.OnDirective
    		| AST.StyleDirective
    		| AST.TransitionDirective
    		| AST.UseDirective;
    
    	export type Block =
    		| AST.EachBlock
    		| AST.IfBlock
    		| AST.AwaitBlock
    		| AST.KeyBlock
    		| AST.SnippetBlock;
    
    	export type ElementLike =
    		| AST.Component
    		| AST.TitleElement
    		| AST.SlotElement
    		| AST.RegularElement
    		| AST.SvelteBody
    		| AST.SvelteBoundary
    		| AST.SvelteComponent
    		| AST.SvelteDocument
    		| AST.SvelteElement
    		| AST.SvelteFragment
    		| AST.SvelteHead
    		| AST.SvelteOptionsRaw
    		| AST.SvelteSelf
    		| AST.SvelteWindow
    		| AST.SvelteBoundary;
    
    	export type Tag =
    		| AST.AttachTag
    		| AST.ConstTag
    		| AST.DebugTag
    		| AST.ExpressionTag
    		| AST.HtmlTag
    		| AST.RenderTag;
    
    	export type TemplateNode =
    		| AST.Root
    		| AST.Text
    		| Tag
    		| ElementLike
    		| AST.Attribute
    		| AST.SpreadAttribute
    		| Directive
    		| AST.AttachTag
    		| AST.Comment
    		| Block;
    
    	export type SvelteNode =
    		| Node
    		| TemplateNode
    		| AST.Fragment
    		| _CSS.Node;
    
    	export type { _CSS as CSS };
    }

##  CompileError

    
    
    interface CompileError extends ICompileDiagnostic {}

##  CompileOptions

    
    
    interface CompileOptions extends ModuleCompileOptions {…}
    
    
    name?: string;

Sets the name of the resulting JavaScript class (though the compiler will
rename it if it would otherwise conflict with other variables in scope). If
unspecified, will be inferred from `filename`

    
    
    customElement?: boolean;

  * default `false`

If `true`, tells the compiler to generate a custom element constructor instead
of a regular Svelte component.

    
    
    accessors?: boolean;

  * default `false`
  * deprecated This will have no effect in runes mode

If `true`, getters and setters will be created for the component’s props. If
`false`, they will only be created for readonly exported values (i.e. those
declared with `const`, `class` and `function`). If compiling with
`customElement: true` this option defaults to `true`.

    
    
    namespace?: Namespace;

  * default `'html'`

The namespace of the element; e.g., `"html"`, `"svg"`, `"mathml"`.

    
    
    immutable?: boolean;

  * default `false`
  * deprecated This will have no effect in runes mode

If `true`, tells the compiler that you promise not to mutate any objects. This
allows it to be less conservative about checking whether values have changed.

    
    
    css?: 'injected' | 'external';

  * `'injected'`: styles will be included in the `head` when using `render(...)`, and injected into the document (if not already present) when the component mounts. For components compiled as custom elements, styles are injected to the shadow root.
  * `'external'`: the CSS will only be returned in the `css` field of the compilation result. Most Svelte bundler plugins will set this to `'external'` and use the CSS that is statically generated for better performance, as it will result in smaller JavaScript bundles and the output can be served as cacheable `.css` files. This is always `'injected'` when compiling with `customElement` mode.

    
    
    cssHash?: CssHashGetter;

  * default `undefined`

A function that takes a `{ hash, css, name, filename }` argument and returns
the string that is used as a classname for scoped CSS. It defaults to
returning `svelte-${hash(css)}`.

    
    
    preserveComments?: boolean;

  * default `false`

If `true`, your HTML comments will be preserved in the output. By default,
they are stripped out.

    
    
    preserveWhitespace?: boolean;

  * default `false`

If `true`, whitespace inside and between elements is kept as you typed it,
rather than removed or collapsed to a single space where possible.

    
    
    fragments?: 'html' | 'tree';

  * default `'html'`
  * available since v5.33

Which strategy to use when cloning DOM fragments:

  * `html` populates a `<template>` with `innerHTML` and clones it. This is faster, but cannot be used if your app’s [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) includes [`require-trusted-types-for 'script'`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/require-trusted-types-for)
  * `tree` creates the fragment one element at a time and _then_ clones it. This is slower, but works everywhere

    
    
    runes?: boolean | undefined;

  * default `undefined`

Set to `true` to force the compiler into runes mode, even if there are no
indications of runes usage. Set to `false` to force the compiler into ignoring
runes, even if there are indications of runes usage. Set to `undefined` (the
default) to infer runes mode from the component code. Is always `true` for
JS/TS modules compiled with Svelte. Will be `true` by default in Svelte 6.
Note that setting this to `true` in your `svelte.config.js` will force runes
mode for your entire project, including components in `node_modules`, which is
likely not what you want. If you’re using Vite, consider using
[dynamicCompileOptions](https://github.com/sveltejs/vite-plugin-
svelte/blob/main/docs/config.md#dynamiccompileoptions) instead.

    
    
    discloseVersion?: boolean;

  * default `true`

If `true`, exposes the Svelte major version in the browser by adding it to a
`Set` stored in the global `window.__svelte.v`.

    
    
    compatibility?: {…}

  * deprecated Use these only as a temporary solution before migrating your code

    
    
    componentApi?: 4 | 5;

  * default `5`

Applies a transformation so that the default export of Svelte files can still
be instantiated the same way as in Svelte 4 — as a class when compiling for
the browser (as though using `createClassComponent(MyComponent, {...})` from
`svelte/legacy`) or as an object with a `.render(...)` method when compiling
for the server

    
    
    sourcemap?: object | string;

  * default `null`

An initial sourcemap that will be merged into the final output sourcemap. This
is usually the preprocessor sourcemap.

    
    
    outputFilename?: string;

  * default `null`

Used for your JavaScript sourcemap.

    
    
    cssOutputFilename?: string;

  * default `null`

Used for your CSS sourcemap.

    
    
    hmr?: boolean;

  * default `false`

If `true`, compiles components with hot reloading support.

    
    
    modernAst?: boolean;

  * default `false`

If `true`, returns the modern version of the AST. Will become `true` by
default in Svelte 6, and the option will be removed in Svelte 7.

##  CompileResult

The return value of `compile` from `svelte/compiler`

    
    
    interface CompileResult {…}
    
    
    js: {…}

The compiled JavaScript

    
    
    code: string;

The generated code

    
    
    map: SourceMap;

A source map

    
    
    css: null | {
    	/** The generated code */
    	code: string;
    	/** A source map */
    	map: SourceMap;
    	/** Whether or not the CSS includes global rules */
    	hasGlobal: boolean;
    };

The compiled CSS

    
    
    warnings: Warning[];

An array of warning objects that were generated during compilation. Each
warning has several properties:

  * `code` is a string identifying the category of warning
  * `message` describes the issue in human-readable terms
  * `start` and `end`, if the warning relates to a specific location, are objects with `line`, `column` and `character` properties

    
    
    metadata: {…}

Metadata about the compiled component

    
    
    runes: boolean;

Whether the file was compiled in runes mode, either because of an explicit
option or inferred from usage. For `compileModule`, this is always `true`

    
    
    ast: any;

The AST

##  MarkupPreprocessor

A markup preprocessor that takes a string of code and returns a processed
version.

    
    
    type MarkupPreprocessor = (options: {
    	/**
    	 * The whole Svelte file content
    	 */
    	content: string;
    	/**
    	 * The filename of the Svelte file
    	 */
    	filename?: string;
    }) => Processed | void | Promise<Processed | void>;

##  ModuleCompileOptions

    
    
    interface ModuleCompileOptions {…}
    
    
    dev?: boolean;

  * default `false`

If `true`, causes extra code to be added that will perform runtime checks and
provide debugging information during development.

    
    
    generate?: 'client' | 'server' | false;

  * default `'client'`

If `"client"`, Svelte emits code designed to run in the browser. If
`"server"`, Svelte emits code suitable for server-side rendering. If `false`,
nothing is generated. Useful for tooling that is only interested in warnings.

    
    
    filename?: string;

Used for debugging hints and sourcemaps. Your bundler plugin will set it
automatically.

    
    
    rootDir?: string;

  * default `process.cwd() on node-like environments, undefined elsewhere`

Used for ensuring filenames don’t leak filesystem information. Your bundler
plugin will set it automatically.

    
    
    warningFilter?: (warning: Warning) => boolean;

A function that gets a `Warning` as an argument and returns a boolean. Use
this to filter out warnings. Return `true` to keep the warning, `false` to
discard it.

##  Preprocessor

A script/style preprocessor that takes a string of code and returns a
processed version.

    
    
    type Preprocessor = (options: {
    	/**
    	 * The script/style tag content
    	 */
    	content: string;
    	/**
    	 * The attributes on the script/style tag
    	 */
    	attributes: Record<string, string | boolean>;
    	/**
    	 * The whole Svelte file content
    	 */
    	markup: string;
    	/**
    	 * The filename of the Svelte file
    	 */
    	filename?: string;
    }) => Processed | void | Promise<Processed | void>;

##  PreprocessorGroup

A preprocessor group is a set of preprocessors that are applied to a Svelte
file.

    
    
    interface PreprocessorGroup {…}
    
    
    name?: string;

Name of the preprocessor. Will be a required option in the next major version

    
    
    markup?: MarkupPreprocessor;
    
    
    style?: Preprocessor;
    
    
    script?: Preprocessor;

##  Processed

The result of a preprocessor run. If the preprocessor does not return a
result, it is assumed that the code is unchanged.

    
    
    interface Processed {…}
    
    
    code: string;

The new code

    
    
    map?: string | object;

A source map mapping back to the original code

    
    
    dependencies?: string[];

A list of additional files to watch for changes

    
    
    attributes?: Record<string, string | boolean>;

Only for script/style preprocessors: The updated attributes to set on the tag.
If undefined, attributes stay unchanged.

    
    
    toString?: () => string;

##  Warning

    
    
    interface Warning extends ICompileDiagnostic {}

# <svelte:document>

### On this page

  * [<svelte:document>](svelte-document)

    
    
    <svelte:document onevent={handler} />
    
    
    <svelte:document bind:prop={value} />

Similarly to `<svelte:window>`, this element allows you to add listeners to
events on `document`, such as `visibilitychange`, which don’t fire on
`window`. It also lets you use [actions](use) on `document`.

As with `<svelte:window>`, this element may only appear the top level of your
component and must never be inside a block or element.

    
    
    <svelte:document onvisibilitychange={handleVisibilityChange} use:someAction />

You can also bind to the following properties:

  * `activeElement`
  * `fullscreenElement`
  * `pointerLockElement`
  * `visibilityState`

All are readonly.

# svelte/easing

### On this page

  * [svelte/easing](svelte-easing)
  * backIn
  * backInOut
  * backOut
  * bounceIn
  * bounceInOut
  * bounceOut
  * circIn
  * circInOut
  * circOut
  * cubicIn
  * cubicInOut
  * cubicOut
  * elasticIn
  * elasticInOut
  * elasticOut
  * expoIn
  * expoInOut
  * expoOut
  * linear
  * quadIn
  * quadInOut
  * quadOut
  * quartIn
  * quartInOut
  * quartOut
  * quintIn
  * quintInOut
  * quintOut
  * sineIn
  * sineInOut
  * sineOut

    
    
    import {
    	backIn,
    	backInOut,
    	backOut,
    	bounceIn,
    	bounceInOut,
    	bounceOut,
    	circIn,
    	circInOut,
    	circOut,
    	cubicIn,
    	cubicInOut,
    	cubicOut,
    	elasticIn,
    	elasticInOut,
    	elasticOut,
    	expoIn,
    	expoInOut,
    	expoOut,
    	linear,
    	quadIn,
    	quadInOut,
    	quadOut,
    	quartIn,
    	quartInOut,
    	quartOut,
    	quintIn,
    	quintInOut,
    	quintOut,
    	sineIn,
    	sineInOut,
    	sineOut
    } from 'svelte/easing';

##  backIn

    
    
    function backIn(t: number): number;

##  backInOut

    
    
    function backInOut(t: number): number;

##  backOut

    
    
    function backOut(t: number): number;

##  bounceIn

    
    
    function bounceIn(t: number): number;

##  bounceInOut

    
    
    function bounceInOut(t: number): number;

##  bounceOut

    
    
    function bounceOut(t: number): number;

##  circIn

    
    
    function circIn(t: number): number;

##  circInOut

    
    
    function circInOut(t: number): number;

##  circOut

    
    
    function circOut(t: number): number;

##  cubicIn

    
    
    function cubicIn(t: number): number;

##  cubicInOut

    
    
    function cubicInOut(t: number): number;

##  cubicOut

    
    
    function cubicOut(t: number): number;

##  elasticIn

    
    
    function elasticIn(t: number): number;

##  elasticInOut

    
    
    function elasticInOut(t: number): number;

##  elasticOut

    
    
    function elasticOut(t: number): number;

##  expoIn

    
    
    function expoIn(t: number): number;

##  expoInOut

    
    
    function expoInOut(t: number): number;

##  expoOut

    
    
    function expoOut(t: number): number;

##  linear

    
    
    function linear(t: number): number;

##  quadIn

    
    
    function quadIn(t: number): number;

##  quadInOut

    
    
    function quadInOut(t: number): number;

##  quadOut

    
    
    function quadOut(t: number): number;

##  quartIn

    
    
    function quartIn(t: number): number;

##  quartInOut

    
    
    function quartInOut(t: number): number;

##  quartOut

    
    
    function quartOut(t: number): number;

##  quintIn

    
    
    function quintIn(t: number): number;

##  quintInOut

    
    
    function quintInOut(t: number): number;

##  quintOut

    
    
    function quintOut(t: number): number;

##  sineIn

    
    
    function sineIn(t: number): number;

##  sineInOut

    
    
    function sineInOut(t: number): number;

##  sineOut

    
    
    function sineOut(t: number): number;

# <svelte:element>

### On this page

  * [<svelte:element>](svelte-element)

    
    
    <svelte:element this={expression} />

The `<svelte:element>` element lets you render an element that is unknown at
author time, for example because it comes from a CMS. Any properties and event
listeners present will be applied to the element.

The only supported binding is `bind:this`, since Svelte’s built-in bindings do
not work with generic elements.

If `this` has a nullish value, the element and its children will not be
rendered.

If `this` is the name of a [void element](https://developer.mozilla.org/en-
US/docs/Glossary/Void_element) (e.g., `br`) and `<svelte:element>` has child
elements, a runtime error will be thrown in development mode:

    
    
    <script>
    	let tag = $state('hr');
    </script>
    
    <svelte:element this={tag}>
    	This text cannot appear inside an hr element
    </svelte:element>

Svelte tries its best to infer the correct namespace from the element’s
surroundings, but it’s not always possible. You can make it explicit with an
`xmlns` attribute:

    
    
    <svelte:element this={tag} xmlns="http://www.w3.org/2000/svg" />

`this` needs to be a valid DOM element tag, things like `#text` or
`svelte:head` will not work.

# svelte/events

### On this page

  * [svelte/events](svelte-events)
  * on

    
    
    import { on } from 'svelte/events';

##  on

Attaches an event handler to the window and returns a function that removes
the handler. Using this rather than `addEventListener` will preserve the
correct order relative to handlers added declaratively (with attributes like
`onclick`), which use event delegation for performance reasons

    
    
    function on<Type extends keyof WindowEventMap>(
    	window: Window,
    	type: Type,
    	handler: (
    		this: Window,
    		event: WindowEventMap[Type]
    	) => any,
    	options?: AddEventListenerOptions | undefined
    ): () => void;
    
    
    function on<Type extends keyof DocumentEventMap>(
    	document: Document,
    	type: Type,
    	handler: (
    		this: Document,
    		event: DocumentEventMap[Type]
    	) => any,
    	options?: AddEventListenerOptions | undefined
    ): () => void;
    
    
    function on<
    	Element extends HTMLElement,
    	Type extends keyof HTMLElementEventMap
    >(
    	element: Element,
    	type: Type,
    	handler: (
    		this: Element,
    		event: HTMLElementEventMap[Type]
    	) => any,
    	options?: AddEventListenerOptions | undefined
    ): () => void;
    
    
    function on<
    	Element extends MediaQueryList,
    	Type extends keyof MediaQueryListEventMap
    >(
    	element: Element,
    	type: Type,
    	handler: (
    		this: Element,
    		event: MediaQueryListEventMap[Type]
    	) => any,
    	options?: AddEventListenerOptions | undefined
    ): () => void;
    
    
    function on(
    	element: EventTarget,
    	type: string,
    	handler: EventListener,
    	options?: AddEventListenerOptions | undefined
    ): () => void;

# .svelte files

### On this page

  * [.svelte files](svelte-files)
  * <script>
  * <script module>
  * <style>

Components are the building blocks of Svelte applications. They are written
into `.svelte` files, using a superset of HTML.

All three sections — script, styles and markup — are optional.

MyComponent

    
    
    <script module>
    	// module-level logic goes here
    	// (you will rarely use this)
    </script>
    
    <script>
    	// instance-level logic goes here
    </script>
    
    <!-- markup (zero or more items) goes here -->
    
    <style>
    	/* styles go here */
    </style>
    
    
    <script module>
    	// module-level logic goes here
    	// (you will rarely use this)
    </script>
    
    <script lang="ts">
    	// instance-level logic goes here
    </script>
    
    <!-- markup (zero or more items) goes here -->
    
    <style>
    	/* styles go here */
    </style>

##  <script>

A `<script>` block contains JavaScript (or TypeScript, when adding the
`lang="ts"` attribute) that runs when a component instance is created.
Variables declared (or imported) at the top level can be referenced in the
component’s markup.

In addition to normal JavaScript, you can use _runes_ to declare [component
props]($props) and add reactivity to your component. Runes are covered in the
next section.

##  <script module>

A `<script>` tag with a `module` attribute runs once when the module first
evaluates, rather than for each component instance. Variables declared in this
block can be referenced elsewhere in the component, but not vice versa.

    
    
    <script module>
    	let total = 0;
    </script>
    
    <script>
    	total += 1;
    	console.log(`instantiated ${total} times`);
    </script>

You can `export` bindings from this block, and they will become exports of the
compiled module. You cannot `export default`, since the default export is the
component itself.

> If you are using TypeScript and import such exports from a `module` block
> into a `.ts` file, make sure to have your editor setup so that TypeScript
> knows about them. This is the case for our VS Code extension and the
> IntelliJ plugin, but in other cases you might need to setup our [TypeScript
> editor plugin](https://www.npmjs.com/package/typescript-svelte-plugin).

> Legacy mode
>
> In Svelte 4, this script tag was created using `<script context="module">`

##  <style>

CSS inside a `<style>` block will be scoped to that component.

    
    
    <style>
    	p {
    		/* this will only affect <p> elements in this component */
    		color: burlywood;
    	}
    </style>

For more information, head to the section on [styling](scoped-styles).

# <svelte:head>

### On this page

  * [<svelte:head>](svelte-head)

    
    
    <svelte:head>...</svelte:head>

This element makes it possible to insert elements into `document.head`. During
server-side rendering, `head` content is exposed separately to the main `body`
content.

As with `<svelte:window>`, `<svelte:document>` and `<svelte:body>`, this
element may only appear at the top level of your component and must never be
inside a block or element.

    
    
    <svelte:head>
    	<title>Hello world!</title>
    	<meta name="description" content="This is where the description goes for SEO" />
    </svelte:head>

# .svelte.js and .svelte.ts files

### On this page

  * [.svelte.js and .svelte.ts files](svelte-js-files)

Besides `.svelte` files, Svelte also operates on `.svelte.js` and `.svelte.ts`
files.

These behave like any other `.js` or `.ts` module, except that you can use
runes. This is useful for creating reusable reactive logic, or sharing
reactive state across your app (though note that you [cannot export reassigned
state]($state#Passing-state-across-modules)).

> Legacy mode
>
> This is a concept that didn’t exist prior to Svelte 5

# svelte/legacy

### On this page

  * [svelte/legacy](svelte-legacy)
  * asClassComponent
  * createBubbler
  * createClassComponent
  * handlers
  * nonpassive
  * once
  * passive
  * preventDefault
  * run
  * self
  * stopImmediatePropagation
  * stopPropagation
  * trusted
  * LegacyComponentType

This module provides various functions for use during the migration, since
some features can’t be replaced one to one with new features. All imports are
marked as deprecated and should be migrated away from over time.

    
    
    import {
    	asClassComponent,
    	createBubbler,
    	createClassComponent,
    	run,
    	self,
    	stopImmediatePropagation,
    	stopPropagation,
    	trusted
    } from 'svelte/legacy';

##  asClassComponent

> Use this only as a temporary solution to migrate your imperative component
> code to Svelte 5.

Takes the component function and returns a Svelte 4 compatible component
constructor.

    
    
    function asClassComponent<
    	Props extends Record<string, any>,
    	Exports extends Record<string, any>,
    	Events extends Record<string, any>,
    	Slots extends Record<string, any>
    >(
    	component:
    		| SvelteComponent<Props, Events, Slots>
    		| Component<Props>
    ): ComponentType<
    	SvelteComponent<Props, Events, Slots> & Exports
    >;

##  createBubbler

> Use this only as a temporary solution to migrate your automatically
> delegated events in Svelte 5.

Function to create a `bubble` function that mimic the behavior of `on:click`
without handler available in svelte 4.

    
    
    function createBubbler(): (
    	type: string
    ) => (event: Event) => boolean;

##  createClassComponent

> Use this only as a temporary solution to migrate your imperative component
> code to Svelte 5.

Takes the same options as a Svelte 4 component and the component function and
returns a Svelte 4 compatible component.

    
    
    function createClassComponent<
    	Props extends Record<string, any>,
    	Exports extends Record<string, any>,
    	Events extends Record<string, any>,
    	Slots extends Record<string, any>
    >(
    	options: ComponentConstructorOptions<Props> & {
    		component:
    			| ComponentType<SvelteComponent<Props, Events, Slots>>
    			| Component<Props>;
    	}
    ): SvelteComponent<Props, Events, Slots> & Exports;

##  handlers

Function to mimic the multiple listeners available in svelte 4

    
    
    function handlers(
    	...handlers: EventListener[]
    ): EventListener;

##  nonpassive

Substitute for the `nonpassive` event modifier, implemented as an action

    
    
    function nonpassive(
    	node: HTMLElement,
    	[event, handler]: [
    		event: string,
    		handler: () => EventListener
    	]
    ): void;

##  once

Substitute for the `once` event modifier

    
    
    function once(
    	fn: (event: Event, ...args: Array<unknown>) => void
    ): (event: Event, ...args: unknown[]) => void;

##  passive

Substitute for the `passive` event modifier, implemented as an action

    
    
    function passive(
    	node: HTMLElement,
    	[event, handler]: [
    		event: string,
    		handler: () => EventListener
    	]
    ): void;

##  preventDefault

Substitute for the `preventDefault` event modifier

    
    
    function preventDefault(
    	fn: (event: Event, ...args: Array<unknown>) => void
    ): (event: Event, ...args: unknown[]) => void;

##  run

> Use this only as a temporary solution to migrate your component code to
> Svelte 5.

Runs the given function once immediately on the server, and works like
`$effect.pre` on the client.

    
    
    function run(fn: () => void | (() => void)): void;

##  self

Substitute for the `self` event modifier

    
    
    function self(
    	fn: (event: Event, ...args: Array<unknown>) => void
    ): (event: Event, ...args: unknown[]) => void;

##  stopImmediatePropagation

Substitute for the `stopImmediatePropagation` event modifier

    
    
    function stopImmediatePropagation(
    	fn: (event: Event, ...args: Array<unknown>) => void
    ): (event: Event, ...args: unknown[]) => void;

##  stopPropagation

Substitute for the `stopPropagation` event modifier

    
    
    function stopPropagation(
    	fn: (event: Event, ...args: Array<unknown>) => void
    ): (event: Event, ...args: unknown[]) => void;

##  trusted

Substitute for the `trusted` event modifier

    
    
    function trusted(
    	fn: (event: Event, ...args: Array<unknown>) => void
    ): (event: Event, ...args: unknown[]) => void;

##  LegacyComponentType

Support using the component as both a class and function during the transition
period

    
    
    type LegacyComponentType = {
    	new (o: ComponentConstructorOptions): SvelteComponent;
    	(
    		...args: Parameters<Component<Record<string, any>>>
    	): ReturnType<
    		Component<Record<string, any>, Record<string, any>>
    	>;
    };

# svelte/motion

### On this page

  * [svelte/motion](svelte-motion)
  * Spring
  * Tween
  * prefersReducedMotion
  * spring
  * tweened
  * Spring
  * Tweened

    
    
    import {
    	Spring,
    	Tween,
    	prefersReducedMotion,
    	spring,
    	tweened
    } from 'svelte/motion';

##  Spring

> Available since 5.8.0

A wrapper for a value that behaves in a spring-like fashion. Changes to
`spring.target` will cause `spring.current` to move towards it over time,
taking account of the `spring.stiffness` and `spring.damping` parameters.

    
    
    <script>
    	import { Spring } from 'svelte/motion';
    
    	const spring = new Spring(0);
    </script>
    
    <input type="range" bind:value={spring.target} />
    <input type="range" bind:value={spring.current} disabled />
    
    
    class Spring<T> {…}
    
    
    constructor(value: T, options?: SpringOpts);
    
    
    static of<U>(fn: () => U, options?: SpringOpts): Spring<U>;

Create a spring whose value is bound to the return value of `fn`. This must be
called inside an effect root (for example, during component initialisation).

    
    
    <script>
    	import { Spring } from 'svelte/motion';
    
    	let { number } = $props();
    
    	const spring = Spring.of(() => number);
    </script>
    
    
    set(value: T, options?: SpringUpdateOpts): Promise<void>;

Sets `spring.target` to `value` and returns a `Promise` that resolves if and
when `spring.current` catches up to it.

If `options.instant` is `true`, `spring.current` immediately matches
`spring.target`.

If `options.preserveMomentum` is provided, the spring will continue on its
current trajectory for the specified number of milliseconds. This is useful
for things like ‘fling’ gestures.

    
    
    damping: number;
    
    
    precision: number;
    
    
    stiffness: number;
    
    
    target: T;

The end value of the spring. This property only exists on the `Spring` class,
not the legacy `spring` store.

    
    
    get current(): T;

The current value of the spring. This property only exists on the `Spring`
class, not the legacy `spring` store.

##  Tween

> Available since 5.8.0

A wrapper for a value that tweens smoothly to its target value. Changes to
`tween.target` will cause `tween.current` to move towards it over time, taking
account of the `delay`, `duration` and `easing` options.

    
    
    <script>
    	import { Tween } from 'svelte/motion';
    
    	const tween = new Tween(0);
    </script>
    
    <input type="range" bind:value={tween.target} />
    <input type="range" bind:value={tween.current} disabled />
    
    
    class Tween<T> {…}
    
    
    static of<U>(fn: () => U, options?: TweenedOptions<U> | undefined): Tween<U>;

Create a tween whose value is bound to the return value of `fn`. This must be
called inside an effect root (for example, during component initialisation).

    
    
    <script>
    	import { Tween } from 'svelte/motion';
    
    	let { number } = $props();
    
    	const tween = Tween.of(() => number);
    </script>
    
    
    constructor(value: T, options?: TweenedOptions<T>);
    
    
    set(value: T, options?: TweenedOptions<T> | undefined): Promise<void>;

Sets `tween.target` to `value` and returns a `Promise` that resolves if and
when `tween.current` catches up to it.

If `options` are provided, they will override the tween’s defaults.

    
    
    get current(): T;
    
    
    set target(v: T);
    
    
    get target(): T;

##  prefersReducedMotion

> Available since 5.7.0

A [media query](svelte-reactivity#MediaQuery) that matches if the user
[prefers reduced motion](https://developer.mozilla.org/en-
US/docs/Web/CSS/@media/prefers-reduced-motion).

    
    
    <script>
    	import { prefersReducedMotion } from 'svelte/motion';
    	import { fly } from 'svelte/transition';
    
    	let visible = $state(false);
    </script>
    
    <button onclick={() => visible = !visible}>
    	toggle
    </button>
    
    {#if visible}
    	<p transition:fly={{ y: prefersReducedMotion.current ? 0 : 200 }}>
    		flies in, unless the user prefers reduced motion
    	</p>
    {/if}
    
    
    const prefersReducedMotion: MediaQuery;

##  spring

> Use [`Spring`](svelte-motion#Spring) instead

The spring function in Svelte creates a store whose value is animated, with a
motion that simulates the behavior of a spring. This means when the value
changes, instead of transitioning at a steady rate, it “bounces” like a spring
would, depending on the physics parameters provided. This adds a level of
realism to the transitions and can enhance the user experience.

    
    
    function spring<T = any>(
    	value?: T | undefined,
    	opts?: SpringOpts | undefined
    ): Spring<T>;

##  tweened

> Use [`Tween`](svelte-motion#Tween) instead

A tweened store in Svelte is a special type of store that provides smooth
transitions between state values over time.

    
    
    function tweened<T>(
    	value?: T | undefined,
    	defaults?: TweenedOptions<T> | undefined
    ): Tweened<T>;

##  Spring

    
    
    interface Spring<T> extends Readable<T> {…}
    
    
    set(new_value: T, opts?: SpringUpdateOpts): Promise<void>;
    
    
    update: (fn: Updater<T>, opts?: SpringUpdateOpts) => Promise<void>;

  * deprecated Only exists on the legacy `spring` store, not the `Spring` class

    
    
    subscribe(fn: (value: T) => void): Unsubscriber;

  * deprecated Only exists on the legacy `spring` store, not the `Spring` class

    
    
    precision: number;
    
    
    damping: number;
    
    
    stiffness: number;

##  Tweened

    
    
    interface Tweened<T> extends Readable<T> {…}
    
    
    set(value: T, opts?: TweenedOptions<T>): Promise<void>;
    
    
    update(updater: Updater<T>, opts?: TweenedOptions<T>): Promise<void>;

# <svelte:options>

### On this page

  * [<svelte:options>](svelte-options)

    
    
    <svelte:options option={value} />

The `<svelte:options>` element provides a place to specify per-component
compiler options, which are detailed in the [compiler section](svelte-
compiler#compile). The possible options are:

  * `runes={true}` — forces a component into _runes mode_ (see the [Legacy APIs](legacy-overview) section)
  * `runes={false}` — forces a component into _legacy mode_
  * `namespace="..."` — the namespace where this component will be used, can be “html” (the default), “svg” or “mathml”
  * `customElement={...}` — the [options](custom-elements#Component-options) to use when compiling this component as a custom element. If a string is passed, it is used as the `tag` option
  * `css="injected"` — the component will inject its styles inline: During server side rendering, it’s injected as a `<style>` tag in the `head`, during client side rendering, it’s loaded via JavaScript

> Legacy mode
>
> Deprecated options Svelte 4 also included the following options. They are
> deprecated in Svelte 5 and non-functional in runes mode.
>
>   * `immutable={true}` — you never use mutable data, so the compiler can do
> simple referential equality checks to determine if values have changed
>   * `immutable={false}` — the default. Svelte will be more conservative
> about whether or not mutable objects have changed
>   * `accessors={true}` — adds getters and setters for the component’s props
>   * `accessors={false}` — the default
>

    
    
    <svelte:options customElement="my-custom-element" />

# svelte/reactivity/window

### On this page

  * [svelte/reactivity/window](svelte-reactivity-window)
  * devicePixelRatio
  * innerHeight
  * innerWidth
  * online
  * outerHeight
  * outerWidth
  * screenLeft
  * screenTop
  * scrollX
  * scrollY

This module exports reactive versions of various `window` values, each of
which has a reactive `current` property that you can reference in reactive
contexts (templates, [deriveds]($derived) and [effects]($effect)) without
using [`<svelte:window>`](svelte-window) bindings or manually creating your
own event listeners.

    
    
    <script>
    	import { innerWidth, innerHeight } from 'svelte/reactivity/window';
    </script>
    
    <p>{innerWidth.current}x{innerHeight.current}</p>
    
    
    import {
    	devicePixelRatio,
    	innerHeight,
    	innerWidth,
    	online,
    	outerHeight,
    	outerWidth,
    	screenLeft,
    	screenTop,
    	scrollX,
    	scrollY
    } from 'svelte/reactivity/window';

##  devicePixelRatio

> Available since 5.11.0

`devicePixelRatio.current` is a reactive view of `window.devicePixelRatio`. On
the server it is `undefined`. Note that behaviour differs between browsers —
on Chrome it will respond to the current zoom level, on Firefox and Safari it
won’t.

    
    
    const devicePixelRatio: {
    	get current(): number | undefined;
    };

##  innerHeight

> Available since 5.11.0

`innerHeight.current` is a reactive view of `window.innerHeight`. On the
server it is `undefined`.

    
    
    const innerHeight: ReactiveValue<number | undefined>;

##  innerWidth

> Available since 5.11.0

`innerWidth.current` is a reactive view of `window.innerWidth`. On the server
it is `undefined`.

    
    
    const innerWidth: ReactiveValue<number | undefined>;

##  online

> Available since 5.11.0

`online.current` is a reactive view of `navigator.onLine`. On the server it is
`undefined`.

    
    
    const online: ReactiveValue<boolean | undefined>;

##  outerHeight

> Available since 5.11.0

`outerHeight.current` is a reactive view of `window.outerHeight`. On the
server it is `undefined`.

    
    
    const outerHeight: ReactiveValue<number | undefined>;

##  outerWidth

> Available since 5.11.0

`outerWidth.current` is a reactive view of `window.outerWidth`. On the server
it is `undefined`.

    
    
    const outerWidth: ReactiveValue<number | undefined>;

##  screenLeft

> Available since 5.11.0

`screenLeft.current` is a reactive view of `window.screenLeft`. It is updated
inside a `requestAnimationFrame` callback. On the server it is `undefined`.

    
    
    const screenLeft: ReactiveValue<number | undefined>;

##  screenTop

> Available since 5.11.0

`screenTop.current` is a reactive view of `window.screenTop`. It is updated
inside a `requestAnimationFrame` callback. On the server it is `undefined`.

    
    
    const screenTop: ReactiveValue<number | undefined>;

##  scrollX

> Available since 5.11.0

`scrollX.current` is a reactive view of `window.scrollX`. On the server it is
`undefined`.

    
    
    const scrollX: ReactiveValue<number | undefined>;

##  scrollY

> Available since 5.11.0

`scrollY.current` is a reactive view of `window.scrollY`. On the server it is
`undefined`.

    
    
    const scrollY: ReactiveValue<number | undefined>;

# svelte/reactivity

### On this page

  * [svelte/reactivity](svelte-reactivity)
  * MediaQuery
  * SvelteDate
  * SvelteMap
  * SvelteSet
  * SvelteURL
  * SvelteURLSearchParams
  * createSubscriber

Svelte provides reactive versions of various built-ins like
[`Map`](https://developer.mozilla.org/en-
US/docs/Web/JavaScript/Reference/Global_Objects/Map),
[`Set`](https://developer.mozilla.org/en-
US/docs/Web/JavaScript/Reference/Global_Objects/Set) and
[`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) that can be used
just like their native counterparts, as well as a handful of additional
utilities for handling reactivity.

    
    
    import {
    	MediaQuery,
    	SvelteDate,
    	SvelteMap,
    	SvelteSet,
    	SvelteURL,
    	SvelteURLSearchParams,
    	createSubscriber
    } from 'svelte/reactivity';

##  MediaQuery

> Available since 5.7.0

Creates a media query and provides a `current` property that reflects whether
or not it matches.

Use it carefully — during server-side rendering, there is no way to know what
the correct value should be, potentially causing content to change upon
hydration. If you can use the media query in CSS to achieve the same effect,
do that.

    
    
    <script>
    	import { MediaQuery } from 'svelte/reactivity';
    
    	const large = new MediaQuery('min-width: 800px');
    </script>
    
    <h1>{large.current ? 'large screen' : 'small screen'}</h1>
    
    
    class MediaQuery extends ReactiveValue<boolean> {…}
    
    
    constructor(query: string, fallback?: boolean | undefined);

  * `query` A media query string
  * `fallback` Fallback value for the server

##  SvelteDate

A reactive version of the built-in [`Date`](https://developer.mozilla.org/en-
US/docs/Web/JavaScript/Reference/Global_Objects/Date) object. Reading the date
(whether with methods like `date.getTime()` or `date.toString()`, or via
things like [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-
US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat)) in an
[effect]($effect) or [derived]($derived) will cause it to be re-evaluated when
the value of the date changes.

    
    
    <script>
    	import { SvelteDate } from 'svelte/reactivity';
    
    	const date = new SvelteDate();
    
    	const formatter = new Intl.DateTimeFormat(undefined, {
    	  hour: 'numeric',
    	  minute: 'numeric',
    	  second: 'numeric'
    	});
    
    	$effect(() => {
    		const interval = setInterval(() => {
    			date.setTime(Date.now());
    		}, 1000);
    
    		return () => {
    			clearInterval(interval);
    		};
    	});
    </script>
    
    <p>The time is {formatter.format(date)}</p>
    
    
    class SvelteDate extends Date {…}
    
    
    constructor(...params: any[]);

##  SvelteMap

A reactive version of the built-in [`Map`](https://developer.mozilla.org/en-
US/docs/Web/JavaScript/Reference/Global_Objects/Map) object. Reading contents
of the map (by iterating, or by reading `map.size` or calling `map.get(...)`
or `map.has(...)` as in the [tic-tac-toe
example](https://svelte.dev/playground/0b0ff4aa49c9443f9b47fe5203c78293)
below) in an [effect]($effect) or [derived]($derived) will cause it to be re-
evaluated as necessary when the map is updated.

Note that values in a reactive map are _not_ made [deeply
reactive]($state#Deep-state).

    
    
    <script>
    	import { SvelteMap } from 'svelte/reactivity';
    	import { result } from './game.js';
    
    	let board = new SvelteMap();
    	let player = $state('x');
    	let winner = $derived(result(board));
    
    	function reset() {
    		player = 'x';
    		board.clear();
    	}
    </script>
    
    <div class="board">
    	{#each Array(9), i}
    		<button
    			disabled={board.has(i) || winner}
    			onclick={() => {
    				board.set(i, player);
    				player = player === 'x' ? 'o' : 'x';
    			}}
    		>{board.get(i)}</button>
    	{/each}
    </div>
    
    {#if winner}
    	<p>{winner} wins!</p>
    	<button onclick={reset}>reset</button>
    {:else}
    	<p>{player} is next</p>
    {/if}
    
    
    class SvelteMap<K, V> extends Map<K, V> {…}
    
    
    constructor(value?: Iterable<readonly [K, V]> | null | undefined);
    
    
    set(key: K, value: V): this;

##  SvelteSet

A reactive version of the built-in [`Set`](https://developer.mozilla.org/en-
US/docs/Web/JavaScript/Reference/Global_Objects/Set) object. Reading contents
of the set (by iterating, or by reading `set.size` or calling `set.has(...)`
as in the
[example](https://svelte.dev/playground/53438b51194b4882bcc18cddf9f96f15)
below) in an [effect]($effect) or [derived]($derived) will cause it to be re-
evaluated as necessary when the set is updated.

Note that values in a reactive set are _not_ made [deeply
reactive]($state#Deep-state).

    
    
    <script>
    	import { SvelteSet } from 'svelte/reactivity';
    	let monkeys = new SvelteSet();
    
    	function toggle(monkey) {
    		if (monkeys.has(monkey)) {
    			monkeys.delete(monkey);
    		} else {
    			monkeys.add(monkey);
    		}
    	}
    </script>
    
    {#each ['🙈', '🙉', '🙊'] as monkey}
    	<button onclick={() => toggle(monkey)}>{monkey}</button>
    {/each}
    
    <button onclick={() => monkeys.clear()}>clear</button>
    
    {#if monkeys.has('🙈')}<p>see no evil</p>{/if}
    {#if monkeys.has('🙉')}<p>hear no evil</p>{/if}
    {#if monkeys.has('🙊')}<p>speak no evil</p>{/if}
    
    
    class SvelteSet<T> extends Set<T> {…}
    
    
    constructor(value?: Iterable<T> | null | undefined);
    
    
    add(value: T): this;

##  SvelteURL

A reactive version of the built-in [`URL`](https://developer.mozilla.org/en-
US/docs/Web/API/URL) object. Reading properties of the URL (such as `url.href`
or `url.pathname`) in an [effect]($effect) or [derived]($derived) will cause
it to be re-evaluated as necessary when the URL changes.

The `searchParams` property is an instance of [SvelteURLSearchParams](svelte-
reactivity#SvelteURLSearchParams).

[Example](https://svelte.dev/playground/5a694758901b448c83dc40dc31c71f2a):

    
    
    <script>
    	import { SvelteURL } from 'svelte/reactivity';
    
    	const url = new SvelteURL('https://example.com/path');
    </script>
    
    <!-- changes to these... -->
    <input bind:value={url.protocol} />
    <input bind:value={url.hostname} />
    <input bind:value={url.pathname} />
    
    <hr />
    
    <!-- will update `href` and vice versa -->
    <input bind:value={url.href} size="65" />
    
    
    class SvelteURL extends URL {…}
    
    
    get searchParams(): SvelteURLSearchParams;

##  SvelteURLSearchParams

A reactive version of the built-in
[`URLSearchParams`](https://developer.mozilla.org/en-
US/docs/Web/API/URLSearchParams) object. Reading its contents (by iterating,
or by calling `params.get(...)` or `params.getAll(...)` as in the
[example](https://svelte.dev/playground/b3926c86c5384bab9f2cf993bc08c1c8)
below) in an [effect]($effect) or [derived]($derived) will cause it to be re-
evaluated as necessary when the params are updated.

    
    
    <script>
    	import { SvelteURLSearchParams } from 'svelte/reactivity';
    
    	const params = new SvelteURLSearchParams('message=hello');
    
    	let key = $state('key');
    	let value = $state('value');
    </script>
    
    <input bind:value={key} />
    <input bind:value={value} />
    <button onclick={() => params.append(key, value)}>append</button>
    
    <p>?{params.toString()}</p>
    
    {#each params as [key, value]}
    	<p>{key}: {value}</p>
    {/each}
    
    
    class SvelteURLSearchParams extends URLSearchParams {…}
    
    
    [REPLACE](params: URLSearchParams): void;

##  createSubscriber

> Available since 5.7.0

Returns a `subscribe` function that, if called in an effect (including
expressions in the template), calls its `start` callback with an `update`
function. Whenever `update` is called, the effect re-runs.

If `start` returns a function, it will be called when the effect is destroyed.

If `subscribe` is called in multiple effects, `start` will only be called once
as long as the effects are active, and the returned teardown function will
only be called when all effects are destroyed.

It’s best understood with an example. Here’s an implementation of
[`MediaQuery`](svelte-reactivity#MediaQuery):

    
    
    import { createSubscriber } from 'svelte/reactivity';
    import { on } from 'svelte/events';
    
    export class MediaQuery {
    	#query;
    	#subscribe;
    
    	constructor(query) {
    		this.#query = window.matchMedia(`(${query})`);
    
    		this.#subscribe = createSubscriber((update) => {
    			// when the `change` event occurs, re-run any effects that read `this.current`
    			const off = on(this.#query, 'change', update);
    
    			// stop listening when all the effects are destroyed
    			return () => off();
    		});
    	}
    
    	get current() {
    		this.#subscribe();
    
    		// Return the current state of the query, whether or not we're in an effect
    		return this.#query.matches;
    	}
    }
    
    
    function createSubscriber(
    	start: (update: () => void) => (() => void) | void
    ): () => void;

# svelte/server

### On this page

  * [svelte/server](svelte-server)
  * render

    
    
    import { render } from 'svelte/server';

##  render

Only available on the server and when compiling with the `server` option.
Takes a component and returns an object with `body` and `head` properties on
it, which you can use to populate the HTML when server-rendering your app.

    
    
    function render<
    	Comp extends SvelteComponent<any> | Component<any>,
    	Props extends ComponentProps<Comp> = ComponentProps<Comp>
    >(
    	...args: {} extends Props
    		? [
    				component: Comp extends SvelteComponent<any>
    					? ComponentType<Comp>
    					: Comp,
    				options?: {
    					props?: Omit<Props, '$$slots' | '$$events'>;
    					context?: Map<any, any>;
    					idPrefix?: string;
    				}
    			]
    		: [
    				component: Comp extends SvelteComponent<any>
    					? ComponentType<Comp>
    					: Comp,
    				options: {
    					props: Omit<Props, '$$slots' | '$$events'>;
    					context?: Map<any, any>;
    					idPrefix?: string;
    				}
    			]
    ): RenderOutput;

# svelte/store

### On this page

  * [svelte/store](svelte-store)
  * derived
  * fromStore
  * get
  * readable
  * readonly
  * toStore
  * writable
  * Readable
  * StartStopNotifier
  * Subscriber
  * Unsubscriber
  * Updater
  * Writable

    
    
    import {
    	derived,
    	fromStore,
    	get,
    	readable,
    	readonly,
    	toStore,
    	writable
    } from 'svelte/store';

##  derived

Derived value store by synchronizing one or more readable stores and applying
an aggregation function over its input values.

    
    
    function derived<S extends Stores, T>(
    	stores: S,
    	fn: (
    		values: StoresValues<S>,
    		set: (value: T) => void,
    		update: (fn: Updater<T>) => void
    	) => Unsubscriber | void,
    	initial_value?: T | undefined
    ): Readable<T>;
    
    
    function derived<S extends Stores, T>(
    	stores: S,
    	fn: (values: StoresValues<S>) => T,
    	initial_value?: T | undefined
    ): Readable<T>;

##  fromStore

    
    
    function fromStore<V>(store: Writable<V>): {
    	current: V;
    };
    
    
    function fromStore<V>(store: Readable<V>): {
    	readonly current: V;
    };

##  get

Get the current value from a store by subscribing and immediately
unsubscribing.

    
    
    function get<T>(store: Readable<T>): T;

##  readable

Creates a `Readable` store that allows reading by subscription.

    
    
    function readable<T>(
    	value?: T | undefined,
    	start?: StartStopNotifier<T> | undefined
    ): Readable<T>;

##  readonly

Takes a store and returns a new one derived from the old one that is readable.

    
    
    function readonly<T>(store: Readable<T>): Readable<T>;

##  toStore

    
    
    function toStore<V>(
    	get: () => V,
    	set: (v: V) => void
    ): Writable<V>;
    
    
    function toStore<V>(get: () => V): Readable<V>;

##  writable

Create a `Writable` store that allows both updating and reading by
subscription.

    
    
    function writable<T>(
    	value?: T | undefined,
    	start?: StartStopNotifier<T> | undefined
    ): Writable<T>;

##  Readable

Readable interface for subscribing.

    
    
    interface Readable<T> {…}
    
    
    subscribe(this: void, run: Subscriber<T>, invalidate?: () => void): Unsubscriber;

  * `run` subscription callback
  * `invalidate` cleanup callback

Subscribe on value changes.

##  StartStopNotifier

Start and stop notification callbacks. This function is called when the first
subscriber subscribes.

    
    
    type StartStopNotifier<T> = (
    	set: (value: T) => void,
    	update: (fn: Updater<T>) => void
    ) => void | (() => void);

##  Subscriber

Callback to inform of a value updates.

    
    
    type Subscriber<T> = (value: T) => void;

##  Unsubscriber

Unsubscribes from value updates.

    
    
    type Unsubscriber = () => void;

##  Updater

Callback to update a value.

    
    
    type Updater<T> = (value: T) => T;

##  Writable

Writable interface for both updating and subscribing.

    
    
    interface Writable<T> extends Readable<T> {…}
    
    
    set(this: void, value: T): void;

  * `value` to set

Set value and inform subscribers.

    
    
    update(this: void, updater: Updater<T>): void;

  * `updater` callback

Update value using callback and inform subscribers.

# svelte/transition

### On this page

  * [svelte/transition](svelte-transition)
  * blur
  * crossfade
  * draw
  * fade
  * fly
  * scale
  * slide
  * BlurParams
  * CrossfadeParams
  * DrawParams
  * EasingFunction
  * FadeParams
  * FlyParams
  * ScaleParams
  * SlideParams
  * TransitionConfig

    
    
    import {
    	blur,
    	crossfade,
    	draw,
    	fade,
    	fly,
    	scale,
    	slide
    } from 'svelte/transition';

##  blur

Animates a `blur` filter alongside an element’s opacity.

    
    
    function blur(
    	node: Element,
    	{
    		delay,
    		duration,
    		easing,
    		amount,
    		opacity
    	}?: BlurParams | undefined
    ): TransitionConfig;

##  crossfade

The `crossfade` function creates a pair of [transitions](transition) called
`send` and `receive`. When an element is ‘sent’, it looks for a corresponding
element being ‘received’, and generates a transition that transforms the
element to its counterpart’s position and fades it out. When an element is
‘received’, the reverse happens. If there is no counterpart, the `fallback`
transition is used.

    
    
    function crossfade({
    	fallback,
    	...defaults
    }: CrossfadeParams & {
    	fallback?: (
    		node: Element,
    		params: CrossfadeParams,
    		intro: boolean
    	) => TransitionConfig;
    }): [
    	(
    		node: any,
    		params: CrossfadeParams & {
    			key: any;
    		}
    	) => () => TransitionConfig,
    	(
    		node: any,
    		params: CrossfadeParams & {
    			key: any;
    		}
    	) => () => TransitionConfig
    ];

##  draw

Animates the stroke of an SVG element, like a snake in a tube. `in`
transitions begin with the path invisible and draw the path to the screen over
time. `out` transitions start in a visible state and gradually erase the path.
`draw` only works with elements that have a `getTotalLength` method, like
`<path>` and `<polyline>`.

    
    
    function draw(
    	node: SVGElement & {
    		getTotalLength(): number;
    	},
    	{
    		delay,
    		speed,
    		duration,
    		easing
    	}?: DrawParams | undefined
    ): TransitionConfig;

##  fade

Animates the opacity of an element from 0 to the current opacity for `in`
transitions and from the current opacity to 0 for `out` transitions.

    
    
    function fade(
    	node: Element,
    	{ delay, duration, easing }?: FadeParams | undefined
    ): TransitionConfig;

##  fly

Animates the x and y positions and the opacity of an element. `in` transitions
animate from the provided values, passed as parameters to the element’s
default values. `out` transitions animate from the element’s default values to
the provided values.

    
    
    function fly(
    	node: Element,
    	{
    		delay,
    		duration,
    		easing,
    		x,
    		y,
    		opacity
    	}?: FlyParams | undefined
    ): TransitionConfig;

##  scale

Animates the opacity and scale of an element. `in` transitions animate from
the provided values, passed as parameters, to an element’s current (default)
values. `out` transitions animate from an element’s default values to the
provided values.

    
    
    function scale(
    	node: Element,
    	{
    		delay,
    		duration,
    		easing,
    		start,
    		opacity
    	}?: ScaleParams | undefined
    ): TransitionConfig;

##  slide

Slides an element in and out.

    
    
    function slide(
    	node: Element,
    	{
    		delay,
    		duration,
    		easing,
    		axis
    	}?: SlideParams | undefined
    ): TransitionConfig;

##  BlurParams

    
    
    interface BlurParams {…}
    
    
    delay?: number;
    
    
    duration?: number;
    
    
    easing?: EasingFunction;
    
    
    amount?: number | string;
    
    
    opacity?: number;

##  CrossfadeParams

    
    
    interface CrossfadeParams {…}
    
    
    delay?: number;
    
    
    duration?: number | ((len: number) => number);
    
    
    easing?: EasingFunction;

##  DrawParams

    
    
    interface DrawParams {…}
    
    
    delay?: number;
    
    
    speed?: number;
    
    
    duration?: number | ((len: number) => number);
    
    
    easing?: EasingFunction;

##  EasingFunction

    
    
    type EasingFunction = (t: number) => number;

##  FadeParams

    
    
    interface FadeParams {…}
    
    
    delay?: number;
    
    
    duration?: number;
    
    
    easing?: EasingFunction;

##  FlyParams

    
    
    interface FlyParams {…}
    
    
    delay?: number;
    
    
    duration?: number;
    
    
    easing?: EasingFunction;
    
    
    x?: number | string;
    
    
    y?: number | string;
    
    
    opacity?: number;

##  ScaleParams

    
    
    interface ScaleParams {…}
    
    
    delay?: number;
    
    
    duration?: number;
    
    
    easing?: EasingFunction;
    
    
    start?: number;
    
    
    opacity?: number;

##  SlideParams

    
    
    interface SlideParams {…}
    
    
    delay?: number;
    
    
    duration?: number;
    
    
    easing?: EasingFunction;
    
    
    axis?: 'x' | 'y';

##  TransitionConfig

    
    
    interface TransitionConfig {…}
    
    
    delay?: number;
    
    
    duration?: number;
    
    
    easing?: EasingFunction;
    
    
    css?: (t: number, u: number) => string;
    
    
    tick?: (t: number, u: number) => void;

# <svelte:window>

### On this page

  * [<svelte:window>](svelte-window)

    
    
    <svelte:window onevent={handler} />
    
    
    <svelte:window bind:prop={value} />

The `<svelte:window>` element allows you to add event listeners to the
`window` object without worrying about removing them when the component is
destroyed, or checking for the existence of `window` when server-side
rendering.

This element may only appear at the top level of your component — it cannot be
inside a block or element.

    
    
    <script>
    	function handleKeydown(event) {
    		alert(`pressed the ${event.key} key`);
    	}
    </script>
    
    <svelte:window onkeydown={handleKeydown} />

You can also bind to the following properties:

  * `innerWidth`
  * `innerHeight`
  * `outerWidth`
  * `outerHeight`
  * `scrollX`
  * `scrollY`
  * `online` — an alias for `window.navigator.onLine`
  * `devicePixelRatio`

All except `scrollX` and `scrollY` are readonly.

    
    
    <svelte:window bind:scrollY={y} />

> Note that the page will not be scrolled to the initial value to avoid
> accessibility issues. Only subsequent changes to the bound variable of
> `scrollX` and `scrollY` will cause scrolling. If you have a legitimate
> reason to scroll when the component is rendered, call `scrollTo()` in an
> `$effect`.

# svelte

### On this page

  * [svelte](svelte)
  * SvelteComponent
  * SvelteComponentTyped
  * afterUpdate
  * beforeUpdate
  * createEventDispatcher
  * createRawSnippet
  * flushSync
  * getAllContexts
  * getContext
  * hasContext
  * hydrate
  * mount
  * onDestroy
  * onMount
  * setContext
  * tick
  * unmount
  * untrack
  * Component
  * ComponentConstructorOptions
  * ComponentEvents
  * ComponentInternals
  * ComponentProps
  * ComponentType
  * EventDispatcher
  * MountOptions
  * Snippet

    
    
    import {
    	SvelteComponent,
    	SvelteComponentTyped,
    	afterUpdate,
    	beforeUpdate,
    	createEventDispatcher,
    	createRawSnippet,
    	flushSync,
    	getAllContexts,
    	getContext,
    	hasContext,
    	hydrate,
    	mount,
    	onDestroy,
    	onMount,
    	setContext,
    	tick,
    	unmount,
    	untrack
    } from 'svelte';

##  SvelteComponent

This was the base class for Svelte components in Svelte 4. Svelte 5+
components are completely different under the hood. For typing, use
`Component` instead. To instantiate components, use `mount` instead. See
[migration guide](v5-migration-guide#Components-are-no-longer-classes) for
more info.

    
    
    class SvelteComponent<
    	Props extends Record<string, any> = Record<string, any>,
    	Events extends Record<string, any> = any,
    	Slots extends Record<string, any> = any
    > {…}
    
    
    static element?: typeof HTMLElement;

The custom element version of the component. Only present if compiled with the
`customElement` compiler option

    
    
    [prop: string]: any;
    
    
    constructor(options: ComponentConstructorOptions<Properties<Props, Slots>>);

  * deprecated This constructor only exists when using the `asClassComponent` compatibility helper, which is a stop-gap solution. Migrate towards using `mount` instead. See [migration guide](v5-migration-guide#Components-are-no-longer-classes) for more info.

    
    
    $destroy(): void;

  * deprecated This method only exists when using one of the legacy compatibility helpers, which is a stop-gap solution. See [migration guide](v5-migration-guide#Components-are-no-longer-classes) for more info.

    
    
    $on<K extends Extract<keyof Events, string>>(
    	type: K,
    	callback: (e: Events[K]) => void
    ): () => void;

  * deprecated This method only exists when using one of the legacy compatibility helpers, which is a stop-gap solution. See [migration guide](v5-migration-guide#Components-are-no-longer-classes) for more info.

    
    
    $set(props: Partial<Props>): void;

  * deprecated This method only exists when using one of the legacy compatibility helpers, which is a stop-gap solution. See [migration guide](v5-migration-guide#Components-are-no-longer-classes) for more info.

##  SvelteComponentTyped

> Use `Component` instead. See [migration guide](v5-migration-
> guide#Components-are-no-longer-classes) for more information.
    
    
    class SvelteComponentTyped<
    	Props extends Record<string, any> = Record<string, any>,
    	Events extends Record<string, any> = any,
    	Slots extends Record<string, any> = any
    > extends SvelteComponent<Props, Events, Slots> {}

##  afterUpdate

> Use [`$effect`]($effect) instead

Schedules a callback to run immediately after the component has been updated.

The first time the callback runs will be after the initial `onMount`.

In runes mode use `$effect` instead.

    
    
    function afterUpdate(fn: () => void): void;

##  beforeUpdate

> Use [`$effect.pre`]($effect#$effect.pre) instead

Schedules a callback to run immediately before the component is updated after
any state change.

The first time the callback runs will be before the initial `onMount`.

In runes mode use `$effect.pre` instead.

    
    
    function beforeUpdate(fn: () => void): void;

##  createEventDispatcher

> Use callback props and/or the `$host()` rune instead — see [migration
> guide](v5-migration-guide#Event-changes-Component-events)

Creates an event dispatcher that can be used to dispatch [component
events](legacy-on#Component-events). Event dispatchers are functions that can
take two arguments: `name` and `detail`.

Component events created with `createEventDispatcher` create a
[CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent).
These events do not [bubble](https://developer.mozilla.org/en-
US/docs/Learn/JavaScript/Building_blocks/Events#Event_bubbling_and_capture).
The `detail` argument corresponds to the
[CustomEvent.detail](https://developer.mozilla.org/en-
US/docs/Web/API/CustomEvent/detail) property and can contain any type of data.

The event dispatcher can be typed to narrow the allowed event names and the
type of the `detail` argument:

    
    
    const dispatch = createEventDispatcher<{
     loaded: null; // does not take a detail argument
     change: string; // takes a detail argument of type string, which is required
     optional: number | null; // takes an optional detail argument of type number
    }>();
    
    
    function createEventDispatcher<
    	EventMap extends Record<string, any> = any
    >(): EventDispatcher<EventMap>;

##  createRawSnippet

Create a snippet programmatically

    
    
    function createRawSnippet<Params extends unknown[]>(
    	fn: (...params: Getters<Params>) => {
    		render: () => string;
    		setup?: (element: Element) => void | (() => void);
    	}
    ): Snippet<Params>;

##  flushSync

Synchronously flush any pending updates. Returns void if no callback is
provided, otherwise returns the result of calling the callback.

    
    
    function flushSync<T = void>(fn?: (() => T) | undefined): T;

##  getAllContexts

Retrieves the whole context map that belongs to the closest parent component.
Must be called during component initialisation. Useful, for example, if you
programmatically create a component and want to pass the existing context to
it.

    
    
    function getAllContexts<
    	T extends Map<any, any> = Map<any, any>
    >(): T;

##  getContext

Retrieves the context that belongs to the closest parent component with the
specified `key`. Must be called during component initialisation.

    
    
    function getContext<T>(key: any): T;

##  hasContext

Checks whether a given `key` has been set in the context of a parent
component. Must be called during component initialisation.

    
    
    function hasContext(key: any): boolean;

##  hydrate

Hydrates a component on the given target and returns the exports and
potentially the props (if compiled with `accessors: true`) of the component

    
    
    function hydrate<
    	Props extends Record<string, any>,
    	Exports extends Record<string, any>
    >(
    	component:
    		| ComponentType<SvelteComponent<Props>>
    		| Component<Props, Exports, any>,
    	options: {} extends Props
    		? {
    				target: Document | Element | ShadowRoot;
    				props?: Props;
    				events?: Record<string, (e: any) => any>;
    				context?: Map<any, any>;
    				intro?: boolean;
    				recover?: boolean;
    			}
    		: {
    				target: Document | Element | ShadowRoot;
    				props: Props;
    				events?: Record<string, (e: any) => any>;
    				context?: Map<any, any>;
    				intro?: boolean;
    				recover?: boolean;
    			}
    ): Exports;

##  mount

Mounts a component to the given target and returns the exports and potentially
the props (if compiled with `accessors: true`) of the component. Transitions
will play during the initial render unless the `intro` option is set to
`false`.

    
    
    function mount<
    	Props extends Record<string, any>,
    	Exports extends Record<string, any>
    >(
    	component:
    		| ComponentType<SvelteComponent<Props>>
    		| Component<Props, Exports, any>,
    	options: MountOptions<Props>
    ): Exports;

##  onDestroy

Schedules a callback to run immediately before the component is unmounted.

Out of `onMount`, `beforeUpdate`, `afterUpdate` and `onDestroy`, this is the
only one that runs inside a server-side component.

    
    
    function onDestroy(fn: () => any): void;

##  onMount

`onMount`, like [`$effect`]($effect), schedules a function to run as soon as
the component has been mounted to the DOM. Unlike `$effect`, the provided
function only runs once.

It must be called during the component’s initialisation (but doesn’t need to
live _inside_ the component; it can be called from an external module). If a
function is returned _synchronously_ from `onMount`, it will be called when
the component is unmounted.

`onMount` functions do not run during [server-side rendering](svelte-
server#render).

    
    
    function onMount<T>(
    	fn: () =>
    		| NotFunction<T>
    		| Promise<NotFunction<T>>
    		| (() => any)
    ): void;

##  setContext

Associates an arbitrary `context` object with the current component and the
specified `key` and returns that object. The context is then available to
children of the component (including slotted content) with `getContext`.

Like lifecycle functions, this must be called during component initialisation.

    
    
    function setContext<T>(key: any, context: T): T;

##  tick

Returns a promise that resolves once any pending state changes have been
applied.

    
    
    function tick(): Promise<void>;

##  unmount

Unmounts a component that was previously mounted using `mount` or `hydrate`.

Since 5.13.0, if `options.outro` is `true`, [transitions](transition) will
play before the component is removed from the DOM.

Returns a `Promise` that resolves after transitions have completed if
`options.outro` is true, or immediately otherwise (prior to 5.13.0, returns
`void`).

    
    
    import { mount, unmount } from 'svelte';
    import App from './App.svelte';
    
    const app = mount(App, { target: document.body });
    
    // later...
    unmount(app, { outro: true });
    
    
    function unmount(
    	component: Record<string, any>,
    	options?:
    		| {
    				outro?: boolean;
    		  }
    		| undefined
    ): Promise<void>;

##  untrack

When used inside a [`$derived`]($derived) or [`$effect`]($effect), any state
read inside `fn` will not be treated as a dependency.

    
    
    $effect(() => {
    	// this will run when `data` changes, but not when `time` changes
    	save(data, {
    		timestamp: untrack(() => time)
    	});
    });
    
    
    function untrack<T>(fn: () => T): T;

##  Component

Can be used to create strongly typed Svelte components.

####  Example:

You have component library on npm called `component-library`, from which you
export a component called `MyComponent`. For Svelte+TypeScript users, you want
to provide typings. Therefore you create a `index.d.ts`:

    
    
    import type { Component } from 'svelte';
    export declare const MyComponent: Component<{ foo: string }> {}

Typing this makes it possible for IDEs like VS Code with the Svelte extension
to provide intellisense and to use the component like this in a Svelte file
with TypeScript:

    
    
    <script lang="ts">
    	import { MyComponent } from "component-library";
    </script>
    <MyComponent foo={'bar'} />
    
    
    interface Component<
    	Props extends Record<string, any> = {},
    	Exports extends Record<string, any> = {},
    	Bindings extends keyof Props | '' = string
    > {…}
    
    
    (
    	this: void,
    	internals: ComponentInternals,
    	props: Props
    ): {
    	/**
    	 * @deprecated This method only exists when using one of the legacy compatibility helpers, which
    	 * is a stop-gap solution. See [migration guide](https://svelte.dev/docs/svelte/v5-migration-guide#Components-are-no-longer-classes)
    	 * for more info.
    	 */
    	$on?(type: string, callback: (e: any) => void): () => void;
    	/**
    	 * @deprecated This method only exists when using one of the legacy compatibility helpers, which
    	 * is a stop-gap solution. See [migration guide](https://svelte.dev/docs/svelte/v5-migration-guide#Components-are-no-longer-classes)
    	 * for more info.
    	 */
    	$set?(props: Partial<Props>): void;
    } & Exports;

  * `internal` An internal object used by Svelte. Do not use or modify.
  * `props` The props passed to the component.

    
    
    element?: typeof HTMLElement;

The custom element version of the component. Only present if compiled with the
`customElement` compiler option

##  ComponentConstructorOptions

> In Svelte 4, components are classes. In Svelte 5, they are functions. Use
> `mount` instead to instantiate components. See [migration
> guide](v5-migration-guide#Components-are-no-longer-classes) for more info.
    
    
    interface ComponentConstructorOptions<
    	Props extends Record<string, any> = Record<string, any>
    > {…}
    
    
    target: Element | Document | ShadowRoot;
    
    
    anchor?: Element;
    
    
    props?: Props;
    
    
    context?: Map<any, any>;
    
    
    hydrate?: boolean;
    
    
    intro?: boolean;
    
    
    recover?: boolean;
    
    
    sync?: boolean;
    
    
    idPrefix?: string;
    
    
    $$inline?: boolean;

##  ComponentEvents

> The new `Component` type does not have a dedicated Events type. Use
> `ComponentProps` instead.
    
    
    type ComponentEvents<Comp extends SvelteComponent> =
    	Comp extends SvelteComponent<any, infer Events>
    		? Events
    		: never;

##  ComponentInternals

Internal implementation details that vary between environments

    
    
    type ComponentInternals = Branded<{}, 'ComponentInternals'>;

##  ComponentProps

Convenience type to get the props the given component expects.

Example: Ensure a variable contains the props expected by `MyComponent`:

    
    
    import type { ComponentProps } from 'svelte';
    import MyComponent from './MyComponent.svelte';
    
    // Errors if these aren't the correct props expected by MyComponent.
    const props: ComponentProps<typeof MyComponent> = { foo: 'bar' };

> In Svelte 4, you would do `ComponentProps<MyComponent>` because
> `MyComponent` was a class.

Example: A generic function that accepts some component and infers the type of
its props:

    
    
    import type { Component, ComponentProps } from 'svelte';
    import MyComponent from './MyComponent.svelte';
    
    function withProps<TComponent extends Component<any>>(
    	component: TComponent,
    	props: ComponentProps<TComponent>
    ) {};
    
    // Errors if the second argument is not the correct props expected by the component in the first argument.
    withProps(MyComponent, { foo: 'bar' });
    
    
    type ComponentProps<
    	Comp extends SvelteComponent | Component<any, any>
    > =
    	Comp extends SvelteComponent<infer Props>
    		? Props
    		: Comp extends Component<infer Props, any>
    			? Props
    			: never;

##  ComponentType

> This type is obsolete when working with the new `Component` type.
    
    
    type ComponentType<
    	Comp extends SvelteComponent = SvelteComponent
    > = (new (
    	options: ComponentConstructorOptions<
    		Comp extends SvelteComponent<infer Props>
    			? Props
    			: Record<string, any>
    	>
    ) => Comp) & {
    	/** The custom element version of the component. Only present if compiled with the `customElement` compiler option */
    	element?: typeof HTMLElement;
    };

##  EventDispatcher

    
    
    interface EventDispatcher<
    	EventMap extends Record<string, any>
    > {…}
    
    
    <Type extends keyof EventMap>(
    	...args: null extends EventMap[Type]
    		? [type: Type, parameter?: EventMap[Type] | null | undefined, options?: DispatchOptions]
    		: undefined extends EventMap[Type]
    			? [type: Type, parameter?: EventMap[Type] | null | undefined, options?: DispatchOptions]
    			: [type: Type, parameter: EventMap[Type], options?: DispatchOptions]
    ): boolean;

##  MountOptions

Defines the options accepted by the `mount()` function.

    
    
    type MountOptions<
    	Props extends Record<string, any> = Record<string, any>
    > = {
    	/**
    	 * Target element where the component will be mounted.
    	 */
    	target: Document | Element | ShadowRoot;
    	/**
    	 * Optional node inside `target`. When specified, it is used to render the component immediately before it.
    	 */
    	anchor?: Node;
    	/**
    	 * Allows the specification of events.
    	 * @deprecated Use callback props instead.
    	 */
    	events?: Record<string, (e: any) => any>;
    	/**
    	 * Can be accessed via `getContext()` at the component level.
    	 */
    	context?: Map<any, any>;
    	/**
    	 * Whether or not to play transitions on initial render.
    	 * @default true
    	 */
    	intro?: boolean;
    } & ({} extends Props
    	? {
    			/**
    			 * Component properties.
    			 */
    			props?: Props;
    		}
    	: {
    			/**
    			 * Component properties.
    			 */
    			props: Props;
    		});

##  Snippet

The type of a `#snippet` block. You can use it to (for example) express that
your component expects a snippet of a certain type:

    
    
    let { banner }: { banner: Snippet<[{ text: string }]> } = $props();

You can only call a snippet through the `{@render ...}` tag.

See the [snippet documentation](snippet) for more info.

    
    
    interface Snippet<Parameters extends unknown[] = []> {…}
    
    
    (
    	this: void,
    	// this conditional allows tuples but not arrays. Arrays would indicate a
    	// rest parameter type, which is not supported. If rest parameters are added
    	// in the future, the condition can be removed.
    	...args: number extends Parameters['length'] ? never : Parameters
    ): {
    	'{@render ...} must be called with a Snippet': "import type { Snippet } from 'svelte'";
    } & typeof SnippetReturn;

# Testing

### On this page

  * [Testing](testing)
  * Unit and integration testing using Vitest
  * E2E tests using Playwright

Testing helps you write and maintain your code and guard against regressions.
Testing frameworks help you with that, allowing you to describe assertions or
expectations about how your code should behave. Svelte is unopinionated about
which testing framework you use — you can write unit tests, integration tests,
and end-to-end tests using solutions like [Vitest](https://vitest.dev/),
[Jasmine](https://jasmine.github.io/), [Cypress](https://www.cypress.io/) and
[Playwright](https://playwright.dev/).

##  Unit and integration testing using Vitest

Unit tests allow you to test small isolated parts of your code. Integration
tests allow you to test parts of your application to see if they work
together. If you’re using Vite (including via SvelteKit), we recommend using
[Vitest](https://vitest.dev/). You can use the Svelte CLI to [setup
Vitest](https://svelte.dev/docs/cli/vitest) either during project creation or
later on.

To setup Vitest manually, first install it:

    
    
    npm install -D vitest

Then adjust your `vite.config.js`:

vite.config

    
    
    import { defineConfig } from 'vitest/config';
    
    export default defineConfig({
    	// ...
    	// Tell Vitest to use the `browser` entry points in `package.json` files, even though it's running in Node
    	resolve: process.env.VITEST
    		? {
    				conditions: ['browser']
    			}
    		: undefined
    });

> If loading the browser version of all your packages is undesirable, because
> (for example) you also test backend libraries, [you may need to resort to an
> alias configuration](https://github.com/testing-library/svelte-testing-
> library/issues/222#issuecomment-1909993331)

You can now write unit tests for code inside your `.js/.ts` files:

multiplier.svelte.test

    
    
    import { flushSync } from 'svelte';
    import { expect, test } from 'vitest';
    import { multiplier } from './multiplier.svelte.js';
    
    test('Multiplier', () => {
    	let double = multiplier(0, 2);
    
    	expect(double.value).toEqual(0);
    
    	double.set(5);
    
    	expect(double.value).toEqual(10);
    });

multiplier.svelte

    
    
    /**
     * @param {number} initial
     * @param {number} k
     */
    export function multiplier(initial, k) {
    	let count = $state(initial);
    
    	return {
    		get value() {
    			return count * k;
    		},
    		/** @param {number} c */
    		set: (c) => {
    			count = c;
    		}
    	};
    }
    
    
    export function multiplier(initial: number, k: number) {
    	let count = $state(initial);
    
    	return {
    		get value() {
    			return count * k;
    		},
    
    		set: (c: number) => {
    			count = c;
    		}
    	};
    }

###  Using runes inside your test files

Since Vitest processes your test files the same way as your source files, you
can use runes inside your tests as long as the filename includes `.svelte`:

multiplier.svelte.test

    
    
    import { flushSync } from 'svelte';
    import { expect, test } from 'vitest';
    import { multiplier } from './multiplier.svelte.js';
    
    test('Multiplier', () => {
    	let count = $state(0);
    	let double = multiplier(() => count, 2);
    
    	expect(double.value).toEqual(0);
    
    	count = 5;
    
    	expect(double.value).toEqual(10);
    });

multiplier.svelte

    
    
    /**
     * @param {() => number} getCount
     * @param {number} k
     */
    export function multiplier(getCount, k) {
    	return {
    		get value() {
    			return getCount() * k;
    		}
    	};
    }
    
    
    export function multiplier(getCount: () => number, k: number) {
    	return {
    		get value() {
    			return getCount() * k;
    		}
    	};
    }

If the code being tested uses effects, you need to wrap the test inside
`$effect.root`:

logger.svelte.test

    
    
    import { flushSync } from 'svelte';
    import { expect, test } from 'vitest';
    import { logger } from './logger.svelte.js';
    
    test('Effect', () => {
    	const cleanup = $effect.root(() => {
    		let count = $state(0);
    
    		// logger uses an $effect to log updates of its input
    		let log = logger(() => count);
    
    		// effects normally run after a microtask,
    		// use flushSync to execute all pending effects synchronously
    		flushSync();
    		expect(log.value).toEqual([0]);
    
    		count = 1;
    		flushSync();
    
    		expect(log.value).toEqual([0, 1]);
    	});
    
    	cleanup();
    });

logger.svelte

    
    
    /**
     * @param {() => any} getValue
     */
    export function logger(getValue) {
    	/** @type {any[]} */
    	let log = $state([]);
    
    	$effect(() => {
    		log.push(getValue());
    	});
    
    	return {
    		get value() {
    			return log;
    		}
    	};
    }
    
    
    export function logger(getValue: () => any) {
    	let log: any[] = $state([]);
    
    	$effect(() => {
    		log.push(getValue());
    	});
    
    	return {
    		get value() {
    			return log;
    		}
    	};
    }

###  Component testing

It is possible to test your components in isolation using Vitest.

> Before writing component tests, think about whether you actually need to
> test the component, or if it’s more about the logic _inside_ the component.
> If so, consider extracting out that logic to test it in isolation, without
> the overhead of a component

To get started, install jsdom (a library that shims DOM APIs):

    
    
    npm install -D jsdom

Then adjust your `vite.config.js`:

vite.config

    
    
    import { defineConfig } from 'vitest/config';
    
    export default defineConfig({
    	plugins: [
    		/* ... */
    	],
    	test: {
    		// If you are testing components client-side, you need to setup a DOM environment.
    		// If not all your files should have this environment, you can use a
    		// `// @vitest-environment jsdom` comment at the top of the test files instead.
    		environment: 'jsdom'
    	},
    	// Tell Vitest to use the `browser` entry points in `package.json` files, even though it's running in Node
    	resolve: process.env.VITEST
    		? {
    				conditions: ['browser']
    			}
    		: undefined
    });

After that, you can create a test file in which you import the component to
test, interact with it programmatically and write expectations about the
results:

component.test

    
    
    import { flushSync, mount, unmount } from 'svelte';
    import { expect, test } from 'vitest';
    import Component from './Component.svelte';
    
    test('Component', () => {
    	// Instantiate the component using Svelte's `mount` API
    	const component = mount(Component, {
    		target: document.body, // `document` exists because of jsdom
    		props: { initial: 0 }
    	});
    
    	expect(document.body.innerHTML).toBe('<button>0</button>');
    
    	// Click the button, then flush the changes so you can synchronously write expectations
    	document.body.querySelector('button').click();
    	flushSync();
    
    	expect(document.body.innerHTML).toBe('<button>1</button>');
    
    	// Remove the component from the DOM
    	unmount(component);
    });

While the process is very straightforward, it is also low level and somewhat
brittle, as the precise structure of your component may change frequently.
Tools like [@testing-library/svelte](https://testing-library.com/docs/svelte-
testing-library/intro/) can help streamline your tests. The above test could
be rewritten like this:

component.test

    
    
    import { render, screen } from '@testing-library/svelte';
    import userEvent from '@testing-library/user-event';
    import { expect, test } from 'vitest';
    import Component from './Component.svelte';
    
    test('Component', async () => {
    	const user = userEvent.setup();
    	render(Component);
    
    	const button = screen.getByRole('button');
    	expect(button).toHaveTextContent(0);
    
    	await user.click(button);
    	expect(button).toHaveTextContent(1);
    });

When writing component tests that involve two-way bindings, context or snippet
props, it’s best to create a wrapper component for your specific test and
interact with that. `@testing-library/svelte` contains some
[examples](https://testing-library.com/docs/svelte-testing-library/example).

##  E2E tests using Playwright

E2E (short for ‘end to end’) tests allow you to test your full application
through the eyes of the user. This section uses
[Playwright](https://playwright.dev/) as an example, but you can also use
other solutions like [Cypress](https://www.cypress.io/) or
[NightwatchJS](https://nightwatchjs.org/).

You can use the Svelte CLI to [setup
Playwright](https://svelte.dev/docs/cli/playwright) either during project
creation or later on. You can also [set it up with `npm init
playwright`](https://playwright.dev/docs/intro). Additionally, you may also
want to install an IDE plugin such as [the VS Code
extension](https://playwright.dev/docs/getting-started-vscode) to be able to
execute tests from inside your IDE.

If you’ve run `npm init playwright` or are not using Vite, you may need to
adjust the Playwright config to tell Playwright what to do before running the
tests - mainly starting your application at a certain port. For example:

playwright.config

    
    
    const config = {
    	webServer: {
    		command: 'npm run build && npm run preview',
    		port: 4173
    	},
    	testDir: 'tests',
    	testMatch: /(.+\.)?(test|spec)\.[jt]s/
    };
    
    export default config;

You can now start writing tests. These are totally unaware of Svelte as a
framework, so you mainly interact with the DOM and write assertions.

tests/hello-world.spec

    
    
    import { expect, test } from '@playwright/test';
    
    test('home page has expected h1', async ({ page }) => {
    	await page.goto('/');
    	await expect(page.locator('h1')).toBeVisible();
    });

# transition:

### On this page

  * [transition:](transition)
  * Local vs global
  * Built-in transitions
  * Transition parameters
  * Custom transition functions
  * Transition events

A _transition_ is triggered by an element entering or leaving the DOM as a
result of a state change.

When a block (such as an `{#if ...}` block) is transitioning out, all elements
inside it, including those that do not have their own transitions, are kept in
the DOM until every transition in the block has been completed.

The `transition:` directive indicates a _bidirectional_ transition, which
means it can be smoothly reversed while the transition is in progress.

    
    
    <script>
    	import { fade } from 'svelte/transition';
    
    	let visible = $state(false);
    </script>
    
    <button onclick={() => visible = !visible}>toggle</button>
    
    {#if visible}
    	<div transition:fade>fades in and out</div>
    {/if}

##  Local vs global

Transitions are local by default. Local transitions only play when the block
they belong to is created or destroyed, _not_ when parent blocks are created
or destroyed.

    
    
    {#if x}
    	{#if y}
    		<p transition:fade>fades in and out only when y changes</p>
    
    		<p transition:fade|global>fades in and out when x or y change</p>
    	{/if}
    {/if}

##  Built-in transitions

A selection of built-in transitions can be imported from the
[`svelte/transition`](svelte-transition) module.

##  Transition parameters

Transitions can have parameters.

(The double `{{curlies}}` aren’t a special syntax; this is an object literal
inside an expression tag.)

    
    
    {#if visible}
    	<div transition:fade={{ duration: 2000 }}>fades in and out over two seconds</div>
    {/if}

##  Custom transition functions

    
    
    transition = (node: HTMLElement, params: any, options: { direction: 'in' | 'out' | 'both' }) => {
    	delay?: number,
    	duration?: number,
    	easing?: (t: number) => number,
    	css?: (t: number, u: number) => string,
    	tick?: (t: number, u: number) => void
    }

Transitions can use custom functions. If the returned object has a `css`
function, Svelte will generate keyframes for a [web
animation](https://developer.mozilla.org/en-
US/docs/Web/API/Web_Animations_API).

The `t` argument passed to `css` is a value between `0` and `1` after the
`easing` function has been applied. _In_ transitions run from `0` to `1`,
_out_ transitions run from `1` to `0` — in other words, `1` is the element’s
natural state, as though no transition had been applied. The `u` argument is
equal to `1 - t`.

The function is called repeatedly _before_ the transition begins, with
different `t` and `u` arguments.

App

    
    
    <script>
    	import { elasticOut } from 'svelte/easing';
    
    	/** @type {boolean} */
    	export let visible;
    
    	/**
    	 * @param {HTMLElement} node
    	 * @param {{ delay?: number, duration?: number, easing?: (t: number) => number }} params
    	 */
    	function whoosh(node, params) {
    		const existingTransform = getComputedStyle(node).transform.replace('none', '');
    
    		return {
    			delay: params.delay || 0,
    			duration: params.duration || 400,
    			easing: params.easing || elasticOut,
    			css: (t, u) => `transform: ${existingTransform} scale(${t})`
    		};
    	}
    </script>
    
    {#if visible}
    	<div in:whoosh>whooshes in</div>
    {/if}
    
    
    <script lang="ts">
    	import { elasticOut } from 'svelte/easing';
    	export let visible: boolean;
    
    	function whoosh(node: HTMLElement, params: { delay?: number, duration?: number, easing?: (t: number) => number }) {
    		const existingTransform = getComputedStyle(node).transform.replace('none', '');
    
    		return {
    			delay: params.delay || 0,
    			duration: params.duration || 400,
    			easing: params.easing || elasticOut,
    			css: (t, u) => `transform: ${existingTransform} scale(${t})`
    		};
    	}
    </script>
    
    {#if visible}
    	<div in:whoosh>whooshes in</div>
    {/if}

A custom transition function can also return a `tick` function, which is
called _during_ the transition with the same `t` and `u` arguments.

> If it’s possible to use `css` instead of `tick`, do so — web animations can
> run off the main thread, preventing jank on slower devices.

App

    
    
    <script>
    	export let visible = false;
    
    	/**
    	 * @param {HTMLElement} node
    	 * @param {{ speed?: number }} params
    	 */
    	function typewriter(node, { speed = 1 }) {
    		const valid = node.childNodes.length === 1 && node.childNodes[0].nodeType === Node.TEXT_NODE;
    
    		if (!valid) {
    			throw new Error(`This transition only works on elements with a single text node child`);
    		}
    
    		const text = node.textContent;
    		const duration = text.length / (speed * 0.01);
    
    		return {
    			duration,
    			tick: (t) => {
    				const i = ~~(text.length * t);
    				node.textContent = text.slice(0, i);
    			}
    		};
    	}
    </script>
    
    {#if visible}
    	<p in:typewriter={{ speed: 1 }}>The quick brown fox jumps over the lazy dog</p>
    {/if}
    
    
    <script lang="ts">
    	export let visible = false;
    
    	function typewriter(node: HTMLElement, { speed = 1 }: { speed?: number }) {
    		const valid = node.childNodes.length === 1 && node.childNodes[0].nodeType === Node.TEXT_NODE;
    
    		if (!valid) {
    			throw new Error(`This transition only works on elements with a single text node child`);
    		}
    
    		const text = node.textContent;
    		const duration = text.length / (speed * 0.01);
    
    		return {
    			duration,
    			tick: (t) => {
    				const i = ~~(text.length * t);
    				node.textContent = text.slice(0, i);
    			}
    		};
    	}
    </script>
    
    {#if visible}
    	<p in:typewriter={{ speed: 1 }}>The quick brown fox jumps over the lazy dog</p>
    {/if}

If a transition returns a function instead of a transition object, the
function will be called in the next microtask. This allows multiple
transitions to coordinate, making [crossfade
effects](https://svelte.dev/tutorial/deferred-transitions) possible.

Transition functions also receive a third argument, `options`, which contains
information about the transition.

Available values in the `options` object are:

  * `direction` \- one of `in`, `out`, or `both` depending on the type of transition

##  Transition events

An element with transitions will dispatch the following events in addition to
any standard DOM events:

  * `introstart`
  * `introend`
  * `outrostart`
  * `outroend`

    
    
    {#if visible}
    	<p
    		transition:fly={{ y: 200, duration: 2000 }}
    		onintrostart={() => (status = 'intro started')}
    		onoutrostart={() => (status = 'outro started')}
    		onintroend={() => (status = 'intro ended')}
    		onoutroend={() => (status = 'outro ended')}
    	>
    		Flies in and out
    	</p>
    {/if}

# TypeScript

### On this page

  * [TypeScript](typescript)
  * <script lang=”ts”>
  * Preprocessor setup
  * tsconfig.json settings
  * Typing $props
  * Generic $props
  * Typing wrapper components
  * Typing $state
  * The Component type
  * Enhancing built-in DOM types

You can use TypeScript within Svelte components. IDE extensions like the
[Svelte VS Code
extension](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-
vscode) will help you catch errors right in your editor, and [`svelte-
check`](https://www.npmjs.com/package/svelte-check) does the same on the
command line, which you can integrate into your CI.

##  <script lang="ts">

To use TypeScript inside your Svelte components, add `lang="ts"` to your
`script` tags:

    
    
    <script lang="ts">
    	let name: string = 'world';
    
    	function greet(name: string) {
    		alert(`Hello, ${name}!`);
    	}
    </script>
    
    <button onclick={(e: Event) => greet(e.target.innerText)}>
    	{name as string}
    </button>

Doing so allows you to use TypeScript’s _type-only_ features. That is, all
features that just disappear when transpiling to JavaScript, such as type
annotations or interface declarations. Features that require the TypeScript
compiler to output actual code are not supported. This includes:

  * using enums
  * using `private`, `protected` or `public` modifiers in constructor functions together with initializers
  * using features that are not yet part of the ECMAScript standard (i.e. not level 4 in the TC39 process) and therefore not implemented yet within Acorn, the parser we use for parsing JavaScript

If you want to use one of these features, you need to setup up a `script`
preprocessor.

##  Preprocessor setup

To use non-type-only TypeScript features within Svelte components, you need to
add a preprocessor that will turn TypeScript into JavaScript.

svelte.config

    
    
    import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
    
    const config = {
    	// Note the additional `{ script: true }`
    	preprocess: vitePreprocess({ script: true })
    };
    
    export default config;

###  Using SvelteKit or Vite

The easiest way to get started is scaffolding a new SvelteKit project by
typing `npx sv create`, following the prompts and choosing the TypeScript
option.

svelte.config

    
    
    import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
    
    const config = {
    	preprocess: vitePreprocess()
    };
    
    export default config;

If you don’t need or want all the features SvelteKit has to offer, you can
scaffold a Svelte-flavoured Vite project instead by typing `npm create
vite@latest` and selecting the `svelte-ts` option.

In both cases, a `svelte.config.js` with `vitePreprocess` will be added.
Vite/SvelteKit will read from this config file.

###  Other build tools

If you’re using tools like Rollup or Webpack instead, install their respective
Svelte plugins. For Rollup that’s [rollup-plugin-
svelte](https://github.com/sveltejs/rollup-plugin-svelte) and for Webpack
that’s [svelte-loader](https://github.com/sveltejs/svelte-loader). For both,
you need to install `typescript` and `svelte-preprocess` and add the
preprocessor to the plugin config (see the respective READMEs for more info).
If you’re starting a new project, you can also use the
[rollup](https://github.com/sveltejs/template) or
[webpack](https://github.com/sveltejs/template-webpack) template to scaffold
the setup from a script.

> If you’re starting a new project, we recommend using SvelteKit or Vite
> instead

##  tsconfig.json settings

When using TypeScript, make sure your `tsconfig.json` is setup correctly.

  * Use a [`target`](https://www.typescriptlang.org/tsconfig/#target) of at least `ES2022`, or a `target` of at least `ES2015` alongside [`useDefineForClassFields`](https://www.typescriptlang.org/tsconfig/#useDefineForClassFields). This ensures that rune declarations on class fields are not messed with, which would break the Svelte compiler
  * Set [`verbatimModuleSyntax`](https://www.typescriptlang.org/tsconfig/#verbatimModuleSyntax) to `true` so that imports are left as-is
  * Set [`isolatedModules`](https://www.typescriptlang.org/tsconfig/#isolatedModules) to `true` so that each file is looked at in isolation. TypeScript has a few features which require cross-file analysis and compilation, which the Svelte compiler and tooling like Vite don’t do.

##  Typing $props

Type `$props` just like a regular object with certain properties.

    
    
    <script lang="ts">
    	import type { Snippet } from 'svelte';
    
    	interface Props {
    		requiredProperty: number;
    		optionalProperty?: boolean;
    		snippetWithStringArgument: Snippet<[string]>;
    		eventHandler: (arg: string) => void;
    		[key: string]: unknown;
    	}
    
    	let {
    		requiredProperty,
    		optionalProperty,
    		snippetWithStringArgument,
    		eventHandler,
    		...everythingElse
    	}: Props = $props();
    </script>
    
    <button onclick={() => eventHandler('clicked button')}>
    	{@render snippetWithStringArgument('hello')}
    </button>

##  Generic $props

Components can declare a generic relationship between their properties. One
example is a generic list component that receives a list of items and a
callback property that receives an item from the list. To declare that the
`items` property and the `select` callback operate on the same types, add the
`generics` attribute to the `script` tag:

    
    
    <script lang="ts" generics="Item extends { text: string }">
    	interface Props {
    		items: Item[];
    		select(item: Item): void;
    	}
    
    	let { items, select }: Props = $props();
    </script>
    
    {#each items as item}
    	<button onclick={() => select(item)}>
    		{item.text}
    	</button>
    {/each}

The content of `generics` is what you would put between the `<...>` tags of a
generic function. In other words, you can use multiple generics, `extends` and
fallback types.

##  Typing wrapper components

In case you’re writing a component that wraps a native element, you may want
to expose all the attributes of the underlying element to the user. In that
case, use (or extend from) one of the interfaces provided by
`svelte/elements`. Here’s an example for a `Button` component:

    
    
    <script lang="ts">
    	import type { HTMLButtonAttributes } from 'svelte/elements';
    
    	let { children, ...rest }: HTMLButtonAttributes = $props();
    </script>
    
    <button {...rest}>
    	{@render children?.()}
    </button>

Not all elements have a dedicated type definition. For those without one, use
`SvelteHTMLElements`:

    
    
    <script lang="ts">
    	import type { SvelteHTMLElements } from 'svelte/elements';
    
    	let { children, ...rest }: SvelteHTMLElements['div'] = $props();
    </script>
    
    <div {...rest}>
    	{@render children?.()}
    </div>

##  Typing $state

You can type `$state` like any other variable.

    
    
    let count: number = $state(0);

If you don’t give `$state` an initial value, part of its types will be
`undefined`.

    
    
    // Error: Type 'number | undefined' is not assignable to type 'number'
    let count: number = $state();

If you know that the variable _will_ be defined before you first use it, use
an `as` casting. This is especially useful in the context of classes:

    
    
    class Counter {
    	count = $state() as number;
    	constructor(initial: number) {
    		this.count = initial;
    	}
    }

##  The Component type

Svelte components are of type `Component`. You can use it and its related
types to express a variety of constraints.

Using it together with dynamic components to restrict what kinds of component
can be passed to it:

    
    
    <script lang="ts">
    	import type { Component } from 'svelte';
    
    	interface Props {
    		// only components that have at most the "prop"
    		// property required can be passed
    		DynamicComponent: Component<{ prop: string }>;
    	}
    
    	let { DynamicComponent }: Props = $props();
    </script>
    
    <DynamicComponent prop="foo" />

> Legacy mode
>
> In Svelte 4, components were of type `SvelteComponent`

To extract the properties from a component, use `ComponentProps`.

    
    
    import type { Component, ComponentProps } from 'svelte';
    import MyComponent from './MyComponent.svelte';
    
    function withProps<TComponent extends Component<any>>(
    	component: TComponent,
    	props: ComponentProps<TComponent>
    ) {}
    
    // Errors if the second argument is not the correct props expected
    // by the component in the first argument.
    withProps(MyComponent, { foo: 'bar' });

To declare that a variable expects the constructor or instance type of a
component:

    
    
    <script lang="ts">
    	import MyComponent from './MyComponent.svelte';
    
    	let componentConstructor: typeof MyComponent = MyComponent;
    	let componentInstance: MyComponent;
    </script>
    
    <MyComponent bind:this={componentInstance} />

##  Enhancing built-in DOM types

Svelte provides a best effort of all the HTML DOM types that exist. Sometimes
you may want to use experimental attributes or custom events coming from an
action. In these cases, TypeScript will throw a type error, saying that it
does not know these types. If it’s a non-experimental standard
attribute/event, this may very well be a missing typing from our [HTML
typings](https://github.com/sveltejs/svelte/blob/main/packages/svelte/elements.d.ts).
In that case, you are welcome to open an issue and/or a PR fixing it.

In case this is a custom or experimental attribute/event, you can enhance the
typings like this:

additional-svelte-typings.d

    
    
    declare namespace svelteHTML {
    	// enhance elements
    	interface IntrinsicElements {
    		'my-custom-element': { someattribute: string; 'on:event': (e: CustomEvent<any>) => void };
    	}
    	// enhance attributes
    	interface HTMLAttributes<T> {
    		// If you want to use the beforeinstallprompt event
    		onbeforeinstallprompt?: (event: any) => any;
    		// If you want to use myCustomAttribute={..} (note: all lowercase)
    		mycustomattribute?: any; // You can replace any with something more specific if you like
    	}
    }

Then make sure that `d.ts` file is referenced in your `tsconfig.json`. If it
reads something like `"include": ["src/**/*"]` and your `d.ts` file is inside
`src`, it should work. You may need to reload for the changes to take effect.

You can also declare the typings by augmenting the `svelte/elements` module
like this:

additional-svelte-typings.d

    
    
    import { HTMLButtonAttributes } from 'svelte/elements';
    
    declare module 'svelte/elements' {
    	export interface SvelteHTMLElements {
    		'custom-button': HTMLButtonAttributes;
    	}
    
    	// allows for more granular control over what element to add the typings to
    	export interface HTMLButtonAttributes {
    		veryexperimentalattribute?: string;
    	}
    }
    
    export {}; // ensure this is not an ambient module, else types will be overridden instead of augmented

# use:

### On this page

  * [use:](use)
  * Typing

> In Svelte 5.29 and newer, consider using [attachments](@attach) instead, as
> they are more flexible and composable.

Actions are functions that are called when an element is mounted. They are
added with the `use:` directive, and will typically use an `$effect` so that
they can reset any state when the element is unmounted:

App

    
    
    <script>
    	/** @type {import('svelte/action').Action} */
    	function myaction(node) {
    		// the node has been mounted in the DOM
    
    		$effect(() => {
    			// setup goes here
    
    			return () => {
    				// teardown goes here
    			};
    		});
    	}
    </script>
    
    <div use:myaction>...</div>
    
    
    <script lang="ts">
    	import type { Action } from 'svelte/action';
    
    	const myaction: Action = (node) => {
    		// the node has been mounted in the DOM
    
    		$effect(() => {
    			// setup goes here
    
    			return () => {
    				// teardown goes here
    			};
    		});
    	};
    </script>
    
    <div use:myaction>...</div>

An action can be called with an argument:

App

    
    
    <script>
    	/** @type {import('svelte/action').Action} */
    	function myaction(node, data) {
    		// ...
    	}
    </script>
    
    <div use:myaction={data}>...</div>
    
    
    <script lang="ts">
    	import type { Action } from 'svelte/action';
    
    	const myaction: Action = (node, data) => {
    		// ...
    	};
    </script>
    
    <div use:myaction={data}>...</div>

The action is only called once (but not during server-side rendering) — it
will _not_ run again if the argument changes.

> Legacy mode
>
> Prior to the `$effect` rune, actions could return an object with `update`
> and `destroy` methods, where `update` would be called with the latest value
> of the argument if it changed. Using effects is preferred.

##  Typing

The `Action` interface receives three optional type arguments — a node type
(which can be `Element`, if the action applies to everything), a parameter,
and any custom event handlers created by the action:

App

    
    
    <script>
    	/**
    	 * @type {import('svelte/action').Action<
    	 * 	HTMLDivElement,
    	 * 	undefined,
    	 * 	{
    	 * 		onswiperight: (e: CustomEvent) => void;
    	 * 		onswipeleft: (e: CustomEvent) => void;
    	 * 		// ...
    	 * 	}
    	 * >}
    	 */
    	function gestures(node) {
    		$effect(() => {
    			// ...
    			node.dispatchEvent(new CustomEvent('swipeleft'));
    
    			// ...
    			node.dispatchEvent(new CustomEvent('swiperight'));
    		});
    	}
    </script>
    
    <div
    	use:gestures
    	onswipeleft={next}
    	onswiperight={prev}
    >...</div>
    
    
    <script lang="ts">
    	import type { Action } from 'svelte/action';
    
    	const gestures: Action<
    		HTMLDivElement,
    		undefined,
    		{
    			onswiperight: (e: CustomEvent) => void;
    			onswipeleft: (e: CustomEvent) => void;
    			// ...
    		}
    	> = (node) => {
    		$effect(() => {
    			// ...
    			node.dispatchEvent(new CustomEvent('swipeleft'));
    
    			// ...
    			node.dispatchEvent(new CustomEvent('swiperight'));
    		});
    	};
    </script>
    
    <div
    	use:gestures
    	onswipeleft={next}
    	onswiperight={prev}
    >...</div>

# Svelte 4 migration guide

### On this page

  * [Svelte 4 migration guide](v4-migration-guide)
  * Minimum version requirements
  * Browser conditions for bundlers
  * Removal of CJS related output
  * Stricter types for Svelte functions
  * Custom Elements with Svelte
  * SvelteComponentTyped is deprecated
  * Transitions are local by default
  * Default slot bindings
  * Preprocessors
  * New eslint package
  * Other breaking changes

This migration guide provides an overview of how to migrate from Svelte
version 3 to 4. See the linked PRs for more details about each change. Use the
migration script to migrate some of these automatically: `npx svelte-
migrate@latest svelte-4`

If you’re a library author, consider whether to only support Svelte 4 or if
it’s possible to support Svelte 3 too. Since most of the breaking changes
don’t affect many people, this may be easily possible. Also remember to update
the version range in your `peerDependencies`.

##  Minimum version requirements

  * Upgrade to Node 16 or higher. Earlier versions are no longer supported. ([#8566](https://github.com/sveltejs/svelte/issues/8566))
  * If you are using SvelteKit, upgrade to 1.20.4 or newer ([sveltejs/kit#10172](https://github.com/sveltejs/kit/pull/10172))
  * If you are using Vite without SvelteKit, upgrade to `vite-plugin-svelte` 2.4.1 or newer ([#8516](https://github.com/sveltejs/svelte/issues/8516))
  * If you are using webpack, upgrade to webpack 5 or higher and `svelte-loader` 3.1.8 or higher. Earlier versions are no longer supported. ([#8515](https://github.com/sveltejs/svelte/issues/8515), [198dbcf](https://github.com/sveltejs/svelte/commit/198dbcf))
  * If you are using Rollup, upgrade to `rollup-plugin-svelte` 7.1.5 or higher ([198dbcf](https://github.com/sveltejs/svelte/commit/198dbcf))
  * If you are using TypeScript, upgrade to TypeScript 5 or higher. Lower versions might still work, but no guarantees are made about that. ([#8488](https://github.com/sveltejs/svelte/issues/8488))

##  Browser conditions for bundlers

Bundlers must now specify the `browser` condition when building a frontend
bundle for the browser. SvelteKit and Vite will handle this automatically for
you. If you’re using any others, you may observe lifecycle callbacks such as
`onMount` not get called and you’ll need to update the module resolution
configuration.

  * For Rollup this is done within the `@rollup/plugin-node-resolve` plugin by setting `browser: true` in its options. See the [`rollup-plugin-svelte`](https://github.com/sveltejs/rollup-plugin-svelte/#usage) documentation for more details
  * For webpack this is done by adding `"browser"` to the `conditionNames` array. You may also have to update your `alias` config, if you have set it. See the [`svelte-loader`](https://github.com/sveltejs/svelte-loader#usage) documentation for more details

([#8516](https://github.com/sveltejs/svelte/issues/8516))

##  Removal of CJS related output

Svelte no longer supports the CommonJS (CJS) format for compiler output and
has also removed the `svelte/register` hook and the CJS runtime version. If
you need to stay on the CJS output format, consider using a bundler to convert
Svelte’s ESM output to CJS in a post-build step.
([#8613](https://github.com/sveltejs/svelte/issues/8613))

##  Stricter types for Svelte functions

There are now stricter types for `createEventDispatcher`, `Action`,
`ActionReturn`, and `onMount`:

  * `createEventDispatcher` now supports specifying that a payload is optional, required, or non-existent, and the call sites are checked accordingly ([#7224](https://github.com/sveltejs/svelte/issues/7224))

    
    
    import { createEventDispatcher } from 'svelte';
    
    const dispatch = createEventDispatcher<{
    	optional: number | null;
    	required: string;
    	noArgument: null;
    }>();
    
    // Svelte version 3:
    dispatch('optional');
    dispatch('required'); // I can still omit the detail argument
    dispatch('noArgument', 'surprise'); // I can still add a detail argument
    
    // Svelte version 4 using TypeScript strict mode:
    dispatch('optional');
    dispatch('required'); // error, missing argument
    dispatch('noArgument', 'surprise'); // error, cannot pass an argument

  * `Action` and `ActionReturn` have a default parameter type of `undefined` now, which means you need to type the generic if you want to specify that this action receives a parameter. The migration script will migrate this automatically ([#7442](https://github.com/sveltejs/svelte/pull/7442))

    
    
    const action: Action = (node, params) => { ... } // this is now an error if you use params in any way
    const action: Action<HTMLElement, string> = (node, params) => { ... } // params is of type string

  * `onMount` now shows a type error if you return a function asynchronously from it, because this is likely a bug in your code where you expect the callback to be called on destroy, which it will only do for synchronously returned functions ([#8136](https://github.com/sveltejs/svelte/issues/8136))

    
    
    // Example where this change reveals an actual bug
    onMount(
    	// someCleanup() not called because function handed to onMount is async
    	async () => {
    		const something = await foo();
               	// someCleanup() is called because function handed to onMount is sync
    	() => {
    		foo().then(something => {...});
    		// ...
    		return () => someCleanup();
    	}
    );

##  Custom Elements with Svelte

The creation of custom elements with Svelte has been overhauled and
significantly improved. The `tag` option is deprecated in favor of the new
`customElement` option:

    
    
    <svelte:options tag="my-component" />
    <svelte:options customElement="my-component" />

This change was made to allow [more configurability](custom-
elements#Component-options) for advanced use cases. The migration script will
adjust your code automatically. The update timing of properties has changed
slightly as well. ([#8457](https://github.com/sveltejs/svelte/issues/8457))

##  SvelteComponentTyped is deprecated

`SvelteComponentTyped` is deprecated, as `SvelteComponent` now has all its
typing capabilities. Replace all instances of `SvelteComponentTyped` with
`SvelteComponent`.

    
    
    import { SvelteComponentTyped } from 'svelte';
    import { SvelteComponent } from 'svelte';
    
    export class Foo extends SvelteComponentTyped<{ aProp: string }> {}
    export class Foo extends SvelteComponent<{ aProp: string }> {}

If you have used `SvelteComponent` as the component instance type previously,
you may see a somewhat opaque type error now, which is solved by changing `:
typeof SvelteComponent` to `: typeof SvelteComponent<any>`.

    
    
    <script>
    	import ComponentA from './ComponentA.svelte';
    	import ComponentB from './ComponentB.svelte';
    	import { SvelteComponent } from 'svelte';
    
    	let component: typeof SvelteComponent<any>;
    
    	function choseRandomly() {
    		component = Math.random() > 0.5 ? ComponentA : ComponentB;
    	}
    </script>
    
    <button on:click={choseRandomly}>random</button>
    <svelte:element this={component} />

The migration script will do both automatically for you.
([#8512](https://github.com/sveltejs/svelte/issues/8512))

##  Transitions are local by default

Transitions are now local by default to prevent confusion around page
navigations. “local” means that a transition will not play if it’s within a
nested control flow block (`each/if/await/key`) and not the direct parent
block but a block above it is created/destroyed. In the following example, the
`slide` intro animation will only play when `success` goes from `false` to
`true`, but it will _not_ play when `show` goes from `false` to `true`:

    
    
    {#if show}
    	...
    	{#if success}
    		<p in:slide>Success</p>
    	{/each}
    {/if}

To make transitions global, add the `|global` modifier - then they will play
when _any_ control flow block above is created/destroyed. The migration script
will do this automatically for you.
([#6686](https://github.com/sveltejs/svelte/issues/6686))

##  Default slot bindings

Default slot bindings are no longer exposed to named slots and vice versa:

    
    
    <script>
    	import Nested from './Nested.svelte';
    </script>
    
    <Nested let:count>
    	<p>
    		count in default slot - is available: {count}
    	</p>
    	<p slot="bar">
    		count in bar slot - is not available: {count}
    	</p>
    </Nested>

This makes slot bindings more consistent as the behavior is undefined when for
example the default slot is from a list and the named slot is not.
([#6049](https://github.com/sveltejs/svelte/issues/6049))

##  Preprocessors

The order in which preprocessors are applied has changed. Now, preprocessors
are executed in order, and within one group, the order is markup, script,
style.

    
    
    import { preprocess } from 'svelte/compiler';
    
    const { code } = await preprocess(
    	source,
    	[
    		{
    			markup: () => {
    				console.log('markup-1');
    			},
    			script: () => {
    				console.log('script-1');
    			},
    			style: () => {
    				console.log('style-1');
    			}
    		},
    		{
    			markup: () => {
    				console.log('markup-2');
    			},
    			script: () => {
    				console.log('script-2');
    			},
    			style: () => {
    				console.log('style-2');
    			}
    		}
    	],
    	{
    		filename: 'App.svelte'
    	}
    );
    
    // Svelte 3 logs:
    // markup-1
    // markup-2
    // script-1
    // script-2
    // style-1
    // style-2
    
    // Svelte 4 logs:
    // markup-1
    // script-1
    // style-1
    // markup-2
    // script-2
    // style-2

This could affect you for example if you are using `MDsveX` \- in which case
you should make sure it comes before any script or style preprocessor.

    
    
    preprocess: [
    	vitePreprocess(),
    	mdsvex(mdsvexConfig)
    	mdsvex(mdsvexConfig),
    	vitePreprocess()
    ]

Each preprocessor must also have a name.
([#8618](https://github.com/sveltejs/svelte/issues/8618))

##  New eslint package

`eslint-plugin-svelte3` is deprecated. It may still work with Svelte 4 but we
make no guarantees about that. We recommend switching to our new package
[eslint-plugin-svelte](https://github.com/sveltejs/eslint-plugin-svelte). See
[this Github
post](https://github.com/sveltejs/kit/issues/10242#issuecomment-1610798405)
for an instruction how to migrate. Alternatively, you can create a new project
using `npm create svelte@latest`, select the eslint (and possibly TypeScript)
option and then copy over the related files into your existing project.

##  Other breaking changes

  * the `inert` attribute is now applied to outroing elements to make them invisible to assistive technology and prevent interaction. ([#8628](https://github.com/sveltejs/svelte/pull/8628))
  * the runtime now uses `classList.toggle(name, boolean)` which may not work in very old browsers. Consider using a [polyfill](https://github.com/eligrey/classList.js) if you need to support these browsers. ([#8629](https://github.com/sveltejs/svelte/issues/8629))
  * the runtime now uses the `CustomEvent` constructor which may not work in very old browsers. Consider using a [polyfill](https://github.com/theftprevention/event-constructor-polyfill/tree/master) if you need to support these browsers. ([#8775](https://github.com/sveltejs/svelte/pull/8775))
  * people implementing their own stores from scratch using the `StartStopNotifier` interface (which is passed to the create function of `writable` etc) from `svelte/store` now need to pass an update function in addition to the set function. This has no effect on people using stores or creating stores using the existing Svelte stores. ([#6750](https://github.com/sveltejs/svelte/issues/6750))
  * `derived` will now throw an error on falsy values instead of stores passed to it. ([#7947](https://github.com/sveltejs/svelte/issues/7947))
  * type definitions for `svelte/internal` were removed to further discourage usage of those internal methods which are not public API. Most of these will likely change for Svelte 5
  * Removal of DOM nodes is now batched which slightly changes its order, which might affect the order of events fired if you’re using a `MutationObserver` on these elements ([#8763](https://github.com/sveltejs/svelte/pull/8763))
  * if you enhanced the global typings through the `svelte.JSX` namespace before, you need to migrate this to use the `svelteHTML` namespace. Similarly if you used the `svelte.JSX` namespace to use type definitions from it, you need to migrate those to use the types from `svelte/elements` instead. You can find more information about what to do [here](https://github.com/sveltejs/language-tools/blob/master/docs/preprocessors/typescript.md#im-getting-deprecation-warnings-for-sveltejsx--i-want-to-migrate-to-the-new-typings)

# Svelte 5 migration guide

### On this page

  * [Svelte 5 migration guide](v5-migration-guide)
  * Reactivity syntax changes
  * Event changes
  * Snippets instead of slots
  * Migration script
  * Components are no longer classes
  * <svelte:component> is no longer necessary
  * Whitespace handling changed
  * Modern browser required
  * Changes to compiler options
  * The children prop is reserved
  * Breaking changes in runes mode
  * Other breaking changes

Version 5 comes with an overhauled syntax and reactivity system. While it may
look different at first, you’ll soon notice many similarities. This guide goes
over the changes in detail and shows you how to upgrade. Along with it, we
also provide information on _why_ we did these changes.

You don’t have to migrate to the new syntax right away - Svelte 5 still
supports the old Svelte 4 syntax, and you can mix and match components using
the new syntax with components using the old and vice versa. We expect many
people to be able to upgrade with only a few lines of code changed initially.
There’s also a migration script that helps you with many of these steps
automatically.

##  Reactivity syntax changes

At the heart of Svelte 5 is the new runes API. Runes are basically compiler
instructions that inform Svelte about reactivity. Syntactically, runes are
functions starting with a dollar-sign.

###  let → $state

In Svelte 4, a `let` declaration at the top level of a component was
implicitly reactive. In Svelte 5, things are more explicit: a variable is
reactive when created using the `$state` rune. Let’s migrate the counter to
runes mode by wrapping the counter in `$state`:

    
    
    <script>
    	let count = $state(0);
    </script>

Nothing else changes. `count` is still the number itself, and you read and
write directly to it, without a wrapper like `.value` or `getCount()`.

> Why we did this
>
> `let` being implicitly reactive at the top level worked great, but it meant
> that reactivity was constrained - a `let` declaration anywhere else was not
> reactive. This forced you to resort to using stores when refactoring code
> out of the top level of components for reuse. This meant you had to learn an
> entirely separate reactivity model, and the result often wasn’t as nice to
> work with. Because reactivity is more explicit in Svelte 5, you can keep
> using the same API outside the top level of components. Head to [the
> tutorial](https://svelte.dev/tutorial) to learn more.

###  $: → $derived/$effect

In Svelte 4, a `$:` statement at the top level of a component could be used to
declare a derivation, i.e. state that is entirely defined through a
computation of other state. In Svelte 5, this is achieved using the `$derived`
rune:

    
    
    <script>
    	let count = $state(0);
    	$: const double = $derived(count * 2);
    </script>

As with `$state`, nothing else changes. `double` is still the number itself,
and you read it directly, without a wrapper like `.value` or `getDouble()`.

A `$:` statement could also be used to create side effects. In Svelte 5, this
is achieved using the `$effect` rune:

    
    
    <script>
    	let count = $state(0);
    
    	$:$effect(() => {
    		if (count > 5) {
    			alert('Count is too high!');
    		}
    	});
    </script>

Note that [when `$effect` runs is different]($effect#Understanding-
dependencies) than when `$:` runs.

> Why we did this
>
> `$:` was a great shorthand and easy to get started with: you could slap a
> `$:` in front of most code and it would somehow work. This intuitiveness was
> also its drawback the more complicated your code became, because it wasn’t
> as easy to reason about. Was the intent of the code to create a derivation,
> or a side effect? With `$derived` and `$effect`, you have a bit more up-
> front decision making to do (spoiler alert: 90% of the time you want
> `$derived`), but future-you and other developers on your team will have an
> easier time.
>
> There were also gotchas that were hard to spot:
>
>   * `$:` only updated directly before rendering, which meant you could read
> stale values in-between rerenders
>   * `$:` only ran once per tick, which meant that statements may run less
> often than you think
>   * `$:` dependencies were determined through static analysis of the
> dependencies. This worked in most cases, but could break in subtle ways
> during a refactoring where dependencies would be for example moved into a
> function and no longer be visible as a result
>   * `$:` statements were also ordered by using static analysis of the
> dependencies. In some cases there could be ties and the ordering would be
> wrong as a result, needing manual interventions. Ordering could also break
> while refactoring code and some dependencies no longer being visible as a
> result.
>

>
> Lastly, it wasn’t TypeScript-friendly (our editor tooling had to jump
> through some hoops to make it valid for TypeScript), which was a blocker for
> making Svelte’s reactivity model truly universal.
>
> `$derived` and `$effect` fix all of these by
>
>   * always returning the latest value
>   * running as often as needed to be stable
>   * determining the dependencies at runtime, and therefore being immune to
> refactorings
>   * executing dependencies as needed and therefore being immune to ordering
> problems
>   * being TypeScript-friendly
>

###  export let → $props

In Svelte 4, properties of a component were declared using `export let`. Each
property was one declaration. In Svelte 5, all properties are declared through
the `$props` rune, through destructuring:

    
    
    <script>
    	export let optional = 'unset';
    	export let required;
    	let { optional = 'unset', required } = $props();
    </script>

There are multiple cases where declaring properties becomes less
straightforward than having a few `export let` declarations:

  * you want to rename the property, for example because the name is a reserved identifier (e.g. `class`)
  * you don’t know which other properties to expect in advance
  * you want to forward every property to another component

All these cases need special syntax in Svelte 4:

  * renaming: `export { klass as class}`
  * other properties: `$$restProps`
  * all properties `$$props`

In Svelte 5, the `$props` rune makes this straightforward without any
additional Svelte-specific syntax:

  * renaming: use property renaming `let { class: klass } = $props();`
  * other properties: use spreading `let { foo, bar, ...rest } = $props();`
  * all properties: don’t destructure `let props = $props();`

    
    
    <script>
    	let klass = '';
    	export { klass as class};
    	let { class: klass, ...rest } = $props();
    </script>
    <button class={klass} {...$$restPropsrest}>click me</button>

> Why we did this
>
> `export let` was one of the more controversial API decisions, and there was
> a lot of debate about whether you should think about a property being
> `export`ed or `import`ed. `$props` doesn’t have this trait. It’s also in
> line with the other runes, and the general thinking reduces to “everything
> special to reactivity in Svelte is a rune”.
>
> There were also a lot of limitations around `export let`, which required
> additional API, as shown above. `$props` unite this in one syntactical
> concept that leans heavily on regular JavaScript destructuring syntax.

##  Event changes

Event handlers have been given a facelift in Svelte 5. Whereas in Svelte 4 we
use the `on:` directive to attach an event listener to an element, in Svelte 5
they are properties like any other (in other words - remove the colon):

    
    
    <script>
    	let count = $state(0);
    </script>
    
    <button on:click={() => count++}>
    	clicks: {count}
    </button>

Since they’re just properties, you can use the normal shorthand syntax...

    
    
    <script>
    	let count = $state(0);
    
    	function onclick() {
    		count++;
    	}
    </script>
    
    <button {onclick}>
    	clicks: {count}
    </button>

...though when using a named event handler function it’s usually better to use
a more descriptive name.

###  Component events

In Svelte 4, components could emit events by creating a dispatcher with
`createEventDispatcher`.

This function is deprecated in Svelte 5. Instead, components should accept
_callback props_ \- which means you then pass functions as properties to these
components:

App

    
    
    <script>
    	import Pump from './Pump.svelte';
    
    	let size = $state(15);
    	let burst = $state(false);
    
    	function reset() {
    		size = 15;
    		burst = false;
    	}
    </script>
    
    <Pump
    	on:inflate={(power) => {
    		size += power.detail;
    		if (size > 75) burst = true;
    	}}
    	on:deflate={(power) => {
    		if (size > 0) size -= power.detail;
    	}}
    />
    
    {#if burst}
    	<button onclick={reset}>new balloon</button>
    	<span class="boom">💥</span>
    {:else}
    	<span class="balloon" style="scale: {0.01 * size}">
    		🎈
    	</span>
    {/if}
    
    
    <script lang="ts">
    	import Pump from './Pump.svelte';
    
    	let size = $state(15);
    	let burst = $state(false);
    
    	function reset() {
    		size = 15;
    		burst = false;
    	}
    </script>
    
    <Pump
    	on:inflate={(power) => {
    		size += power.detail;
    		if (size > 75) burst = true;
    	}}
    	on:deflate={(power) => {
    		if (size > 0) size -= power.detail;
    	}}
    />
    
    {#if burst}
    	<button onclick={reset}>new balloon</button>
    	<span class="boom">💥</span>
    {:else}
    	<span class="balloon" style="scale: {0.01 * size}">
    		🎈
    	</span>
    {/if}

Pump

    
    
    <script>
    	import { createEventDispatcher } from 'svelte';
    	const dispatch = createEventDispatcher();
    
    	let { inflate, deflate } = $props();
    	let power = $state(5);
    </script>
    
    <button onclick={() => dispatch('inflate', power)inflate(power)}>
    	inflate
    </button>
    <button onclick={() => dispatch('deflate', power)deflate(power)}>
    	deflate
    </button>
    <button onclick={() => power--}>-</button>
    Pump power: {power}
    <button onclick={() => power++}>+</button>
    
    
    <script lang="ts">
    	import { createEventDispatcher } from 'svelte';
    	const dispatch = createEventDispatcher();
    
    	let { inflate, deflate } = $props();
    	let power = $state(5);
    </script>
    
    <button onclick={() => dispatch('inflate', power)inflate(power)}>
    	inflate
    </button>
    <button onclick={() => dispatch('deflate', power)deflate(power)}>
    	deflate
    </button>
    <button onclick={() => power--}>-</button>
    Pump power: {power}
    <button onclick={() => power++}>+</button>

###  Bubbling events

Instead of doing `<button on:click>` to ‘forward’ the event from the element
to the component, the component should accept an `onclick` callback prop:

    
    
    <script>
    	let { onclick } = $props();
    </script>
    
    <button on:click {onclick}>
    	click me
    </button>

Note that this also means you can ‘spread’ event handlers onto the element
along with other props instead of tediously forwarding each event separately:

    
    
    <script>
    	let props = $props();
    </script>
    
    <button {...$$props} on:click on:keydown on:all_the_other_stuff {...props}>
    	click me
    </button>

###  Event modifiers

In Svelte 4, you can add event modifiers to handlers:

    
    
    <button on:click|once|preventDefault={handler}>...</button>

Modifiers are specific to `on:` and as such do not work with modern event
handlers. Adding things like `event.preventDefault()` inside the handler
itself is preferable, since all the logic lives in one place rather than being
split between handler and modifiers.

Since event handlers are just functions, you can create your own wrappers as
necessary:

    
    
    <script>
    	function once(fn) {
    		return function (event) {
    			if (fn) fn.call(this, event);
    			fn = null;
    		};
    	}
    
    	function preventDefault(fn) {
    		return function (event) {
    			event.preventDefault();
    			fn.call(this, event);
    		};
    	}
    </script>
    
    <button onclick={once(preventDefault(handler))}>...</button>

There are three modifiers — `capture`, `passive` and `nonpassive` — that can’t
be expressed as wrapper functions, since they need to be applied when the
event handler is bound rather than when it runs.

For `capture`, we add the modifier to the event name:

    
    
    <button onclickcapture={...}>...</button>

Changing the [`passive`](https://developer.mozilla.org/en-
US/docs/Web/API/EventTarget/addEventListener#using_passive_listeners) option
of an event handler, meanwhile, is not something to be done lightly. If you
have a use case for it — and you probably don’t! — then you will need to use
an action to apply the event handler yourself.

###  Multiple event handlers

In Svelte 4, this is possible:

    
    
    <button on:click={one} on:click={two}>...</button>

Duplicate attributes/properties on elements — which now includes event
handlers — are not allowed. Instead, do this:

    
    
    <button
    	onclick={(e) => {
    		one(e);
    		two(e);
    	}}
    >
    	...
    </button>

When spreading props, local event handlers must go _after_ the spread, or they
risk being overwritten:

    
    
    <button
    	{...props}
    	onclick={(e) => {
    		doStuff(e);
    		props.onclick?.(e);
    	}}
    >
    	...
    </button>

> Why we did this
>
> `createEventDispatcher` was always a bit boilerplate-y:
>
>   * import the function
>   * call the function to get a dispatch function
>   * call said dispatch function with a string and possibly a payload
>   * retrieve said payload on the other end through a `.detail` property,
> because the event itself was always a `CustomEvent`
>

>
> It was always possible to use component callback props, but because you had
> to listen to DOM events using `on:`, it made sense to use
> `createEventDispatcher` for component events due to syntactical consistency.
> Now that we have event attributes (`onclick`), it’s the other way around:
> Callback props are now the more sensible thing to do.
>
> The removal of event modifiers is arguably one of the changes that seems
> like a step back for those who’ve liked the shorthand syntax of event
> modifiers. Given that they are not used that frequently, we traded a smaller
> surface area for more explicitness. Modifiers also were inconsistent,
> because most of them were only useable on DOM elements.
>
> Multiple listeners for the same event are also no longer possible, but it
> was something of an anti-pattern anyway, since it impedes readability: if
> there are many attributes, it becomes harder to spot that there are two
> handlers unless they are right next to each other. It also implies that the
> two handlers are independent, when in fact something like
> `event.stopImmediatePropagation()` inside `one` would prevent `two` from
> being called.
>
> By deprecating `createEventDispatcher` and the `on:` directive in favour of
> callback props and normal element properties, we:
>
>   * reduce Svelte’s learning curve
>   * remove boilerplate, particularly around `createEventDispatcher`
>   * remove the overhead of creating `CustomEvent` objects for events that
> may not even have listeners
>   * add the ability to spread event handlers
>   * add the ability to know which event handlers were provided to a
> component
>   * add the ability to express whether a given event handler is required or
> optional
>   * increase type safety (previously, it was effectively impossible for
> Svelte to guarantee that a component didn’t emit a particular event)
>

##  Snippets instead of slots

In Svelte 4, content can be passed to components using slots. Svelte 5
replaces them with snippets which are more powerful and flexible, and as such
slots are deprecated in Svelte 5.

They continue to work, however, and you can pass snippets to a component that
uses slots:

Child

    
    
    <slot />
    <hr />
    <slot name="foo" message="hello" />

Parent

    
    
    <script>
    	import Child from './Child.svelte';
    </script>
    
    <Child>
    	default child content
    
    	{#snippet foo({ message })}
    		message from child: {message}
    	{/snippet}
    </Child>
    
    
    <script lang="ts">
    	import Child from './Child.svelte';
    </script>
    
    <Child>
    	default child content
    
    	{#snippet foo({ message })}
    		message from child: {message}
    	{/snippet}
    </Child>

(The reverse is not true — you cannot pass slotted content to a component that
uses [`{@render ...}`](@render) tags.)

When using custom elements, you should still use `<slot />` like before. In a
future version, when Svelte removes its internal version of slots, it will
leave those slots as-is, i.e. output a regular DOM tag instead of transforming
it.

###  Default content

In Svelte 4, the easiest way to pass a piece of UI to the child was using a
`<slot />`. In Svelte 5, this is done using the `children` prop instead, which
is then shown with `{@render children()}`:

    
    
    <script>
    	let { children } = $props();
    </script>
    
    <slot />
    {@render children?.()}

###  Multiple content placeholders

If you wanted multiple UI placeholders, you had to use named slots. In Svelte
5, use props instead, name them however you like and `{@render ...}` them:

    
    
    <script>
    	let { header, main, footer } = $props();
    </script>
    
    <header>
    	<slot name="header" />
    	{@render header()}
    </header>
    
    <main>
    	<slot name="main" />
    	{@render main()}
    </main>
    
    <footer>
    	<slot name="footer" />
    	{@render footer()}
    </footer>

###  Passing data back up

In Svelte 4, you would pass data to a `<slot />` and then retrieve it with
`let:` in the parent component. In Svelte 5, snippets take on that
responsibility:

App

    
    
    <script>
    	import List from './List.svelte';
    </script>
    
    <List items={['one', 'two', 'three']} let:item>
    	{#snippet item(text)}
    		<span>{text}</span>
    	{/snippet}
    	<span slot="empty">No items yet</span>
    	{#snippet empty()}
    		<span>No items yet</span>
    	{/snippet}
    </List>
    
    
    <script lang="ts">
    	import List from './List.svelte';
    </script>
    
    <List items={['one', 'two', 'three']} let:item>
    	{#snippet item(text)}
    		<span>{text}</span>
    	{/snippet}
    	<span slot="empty">No items yet</span>
    	{#snippet empty()}
    		<span>No items yet</span>
    	{/snippet}
    </List>

List

    
    
    <script>
    	let { items, item, empty } = $props();
    </script>
    
    {#if items.length}
    	<ul>
    		{#each items as entry}
    			<li>
    				<slot item={entry} />
    				{@render item(entry)}
    			</li>
    		{/each}
    	</ul>
    {:else}
    	<slot name="empty" />
    	{@render empty?.()}
    {/if}
    
    
    <script lang="ts">
    	let { items, item, empty } = $props();
    </script>
    
    {#if items.length}
    	<ul>
    		{#each items as entry}
    			<li>
    				<slot item={entry} />
    				{@render item(entry)}
    			</li>
    		{/each}
    	</ul>
    {:else}
    	<slot name="empty" />
    	{@render empty?.()}
    {/if}

> Why we did this
>
> Slots were easy to get started with, but the more advanced the use case
> became, the more involved and confusing the syntax became:
>
>   * the `let:` syntax was confusing to many people as it _creates_ a
> variable whereas all other `:` directives _receive_ a variable
>   * the scope of a variable declared with `let:` wasn’t clear. In the
> example above, it may look like you can use the `item` slot prop in the
> `empty` slot, but that’s not true
>   * named slots had to be applied to an element using the `slot` attribute.
> Sometimes you didn’t want to create an element, so we had to add the
> `<svelte:fragment>` API
>   * named slots could also be applied to a component, which changed the
> semantics of where `let:` directives are available (even today us
> maintainers often don’t know which way around it works)
>

>
> Snippets solve all of these problems by being much more readable and clear.
> At the same time they’re more powerful as they allow you to define sections
> of UI that you can render _anywhere_ , not just passing them as props to a
> component.

##  Migration script

By now you should have a pretty good understanding of the before/after and how
the old syntax relates to the new syntax. It probably also became clear that a
lot of these migrations are rather technical and repetitive - something you
don’t want to do by hand.

We thought the same, which is why we provide a migration script to do most of
the migration automatically. You can upgrade your project by using `npx sv
migrate svelte-5`. This will do the following things:

  * bump core dependencies in your `package.json`
  * migrate to runes (`let` → `$state` etc)
  * migrate to event attributes for DOM elements (`on:click` → `onclick`)
  * migrate slot creations to render tags (`<slot />` → `{@render children()}`)
  * migrate slot usages to snippets (`<div slot="x">...</div>` → `{#snippet x()}<div>...</div>{/snippet}`)
  * migrate obvious component creations (`new Component(...)` → `mount(Component, ...)`)

You can also migrate a single component in VS Code through the `Migrate
Component to Svelte 5 Syntax` command, or in our Playground through the
`Migrate` button.

Not everything can be migrated automatically, and some migrations need manual
cleanup afterwards. The following sections describe these in more detail.

###  run

You may see that the migration script converts some of your `$:` statements to
a `run` function which is imported from `svelte/legacy`. This happens if the
migration script couldn’t reliably migrate the statement to a `$derived` and
concluded this is a side effect instead. In some cases this may be wrong and
it’s best to change this to use a `$derived` instead. In other cases it may be
right, but since `$:` statements also ran on the server but `$effect` does
not, it isn’t safe to transform it as such. Instead, `run` is used as a
stopgap solution. `run` mimics most of the characteristics of `$:`, in that it
runs on the server once, and runs as `$effect.pre` on the client
(`$effect.pre` runs _before_ changes are applied to the DOM; most likely you
want to use `$effect` instead).

    
    
    <script>
    	import { run } from 'svelte/legacy';
    	run(() => {
    	$effect(() => {
    		// some side effect code
    	})
    </script>

###  Event modifiers

Event modifiers are not applicable to event attributes (e.g. you can’t do
`onclick|preventDefault={...}`). Therefore, when migrating event directives to
event attributes, we need a function-replacement for these modifiers. These
are imported from `svelte/legacy`, and should be migrated away from in favor
of e.g. just using `event.preventDefault()`.

    
    
    <script>
    	import { preventDefault } from 'svelte/legacy';
    </script>
    
    <button
    	onclick={preventDefault((event) => {
    		event.preventDefault();
    		// ...
    	})}
    >
    	click me
    </button>

###  Things that are not automigrated

The migration script does not convert `createEventDispatcher`. You need to
adjust those parts manually. It doesn’t do it because it’s too risky because
it could result in breakage for users of the component, which the migration
script cannot find out.

The migration script does not convert `beforeUpdate/afterUpdate`. It doesn’t
do it because it’s impossible to determine the actual intent of the code. As a
rule of thumb you can often go with a combination of `$effect.pre` (runs at
the same time as `beforeUpdate` did) and `tick` (imported from `svelte`,
allows you to wait until changes are applied to the DOM and then do some
work).

##  Components are no longer classes

In Svelte 3 and 4, components are classes. In Svelte 5 they are functions and
should be instantiated differently. If you need to manually instantiate
components, you should use `mount` or `hydrate` (imported from `svelte`)
instead. If you see this error using SvelteKit, try updating to the latest
version of SvelteKit first, which adds support for Svelte 5. If you’re using
Svelte without SvelteKit, you’ll likely have a `main.js` file (or similar)
which you need to adjust:

    
    
    import { mount } from 'svelte';
    import App from './App.svelte'
    
    const app = new App({ target: document.getElementById("app") });
    const 
        $on?(type: string, callback: (e: any) => void): () => void;
        $set?(props: Partial<Record<string, any>>): void;
    } & Record<string, any>
        $on?(type: string, callback: (e: any) => void): () => void;
        $set?(props: Partial<Record<string, any>>): void;
    } & Record<string, any>

app = `

    
    
    mount<Record<string, any>, {

` $on?(type: string, callback: (e: any) => void): () => void; $set?(props: Partial<Record<string, any>>): void; } & Record<...>>(component: ComponentType<...> | Component<...>, options: MountOptions<...>): { $on?(type: string, callback: (e: any) => void): () => void; $set?(props: Partial<Record<string, any>>): void; } & Record<...>

Mounts a component to the given target and returns the exports and potentially
the props (if compiled with `accessors: true`) of the component. Transitions
will play during the initial render unless the `intro` option is set to
`false`.

mount(`const App: LegacyComponentType`App, { `target: Document | Element | ShadowRoot`

Target element where the component will be mounted.

target: `var document: Document`

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/document)

document.`Document.getElementById(elementId: string): HTMLElement | null`

Returns a reference to the first object with the specified value of the ID
attribute.

@paramelementId String that specifies the ID value.

getElementById("app") }); export default `

    
    
    const app: {
        $on?(type: string, callback: (e: any) => void): () => void;
        $set?(props: Partial<Record<string, any>>): void;
    } & Record<string, any>

`app;

`mount` and `hydrate` have the exact same API. The difference is that
`hydrate` will pick up the Svelte’s server-rendered HTML inside its target and
hydrate it. Both return an object with the exports of the component and
potentially property accessors (if compiled with `accessors: true`). They do
not come with the `$on`, `$set` and `$destroy` methods you may know from the
class component API. These are its replacements:

For `$on`, instead of listening to events, pass them via the `events` property
on the options argument.

    
    
    import { mount } from 'svelte';
    import App from './App.svelte'
    
    const app = new App({ target: document.getElementById("app") });
    app.$on('event', callback);
    const 
        $on?(type: string, callback: (e: any) => void): () => void;
        $set?(props: Partial<Record<string, any>>): void;
    } & Record<string, any>
        $on?(type: string, callback: (e: any) => void): () => void;
        $set?(props: Partial<Record<string, any>>): void;
    } & Record<string, any>

app = `

    
    
    mount<Record<string, any>, {

` $on?(type: string, callback: (e: any) => void): () => void; $set?(props: Partial<Record<string, any>>): void; } & Record<...>>(component: ComponentType<...> | Component<...>, options: MountOptions<...>): { $on?(type: string, callback: (e: any) => void): () => void; $set?(props: Partial<Record<string, any>>): void; } & Record<...>

Mounts a component to the given target and returns the exports and potentially
the props (if compiled with `accessors: true`) of the component. Transitions
will play during the initial render unless the `intro` option is set to
`false`.

mount(`const App: LegacyComponentType`App, { `target: Document | Element | ShadowRoot`

Target element where the component will be mounted.

target: `var document: Document`

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/document)

document.`Document.getElementById(elementId: string): HTMLElement | null`

Returns a reference to the first object with the specified value of the ID
attribute.

@paramelementId String that specifies the ID value.

getElementById("app"), `events?: Record<string, (e: any) => any> | undefined`

Allows the specification of events.

@deprecatedUse callback props instead.

events: { `event: any`event: callback } });

> Note that using `events` is discouraged — instead, use callbacks

For `$set`, use `$state` instead to create a reactive property object and
manipulate it. If you’re doing this inside a `.js` or `.ts` file, adjust the
ending to include `.svelte`, i.e. `.svelte.js` or `.svelte.ts`.

    
    
    import { mount } from 'svelte';
    import App from './App.svelte'
    
    const app = new App({ target: document.getElementById("app"), props: { foo: 'bar' } });
    app.$set({ foo: 'baz' });
    const 
        foo: string;
    }
        foo: string;
    }

props = `

    
    
    function $state<{

` foo: string; }>(initial: { foo: string; }): { foo: string; } (+1 overload)
namespace $state

Declares reactive state.

Example:

    
    
    let count = $state(0);

[https://svelte.dev/docs/svelte/$state]($state)

@paraminitial The initial value

$state({ `foo: string`foo: 'bar' }); const `

    
    
    const app: {

` $on?(type: string, callback: (e: any) => void): () => void; $set?(props:
Partial<Record<string, any>>): void; } & Record<string, any>app = `

    
    
    mount<Record<string, any>, {

` $on?(type: string, callback: (e: any) => void): () => void; $set?(props: Partial<Record<string, any>>): void; } & Record<...>>(component: ComponentType<...> | Component<...>, options: MountOptions<...>): { $on?(type: string, callback: (e: any) => void): () => void; $set?(props: Partial<Record<string, any>>): void; } & Record<...>

Mounts a component to the given target and returns the exports and potentially
the props (if compiled with `accessors: true`) of the component. Transitions
will play during the initial render unless the `intro` option is set to
`false`.

mount(`const App: LegacyComponentType`App, { `target: Document | Element | ShadowRoot`

Target element where the component will be mounted.

target: `var document: Document`

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/document)

document.`Document.getElementById(elementId: string): HTMLElement | null`

Returns a reference to the first object with the specified value of the ID
attribute.

@paramelementId String that specifies the ID value.

getElementById("app"), `props?: Record<string, any> | undefined`

Component properties.

props }); `

    
    
    const props: {

` foo: string; }props.`foo: string`foo = 'baz';

For `$destroy`, use `unmount` instead.

    
    
    import { mount, 
        outro?: boolean;
    } | undefined): Promise<void>
        outro?: boolean;
    } | undefined): Promise<void>

Unmounts a component that was previously mounted using `mount` or `hydrate`.

Since 5.13.0, if `options.outro` is `true`, [transitions](transition) will
play before the component is removed from the DOM.

Returns a `Promise` that resolves after transitions have completed if
`options.outro` is true, or immediately otherwise (prior to 5.13.0, returns
`void`).

    
    
    import { mount, unmount } from 'svelte';
    import App from './App.svelte';
    
    const app = mount(App, { target: document.body });
    
    // later...
    unmount(app, { outro: true });

unmount } from 'svelte'; import `

    
    
    type App = SvelteComponent<Record<string, any>, any, any>
    const App: LegacyComponentType

`App from './App.svelte' const app = new App({ target:
document.getElementById("app"), props: { foo: 'bar' } }); app.$destroy();
const `

    
    
    const app: {

` $on?(type: string, callback: (e: any) => void): () => void; $set?(props:
Partial<Record<string, any>>): void; } & Record<string, any>app = `

    
    
    mount<Record<string, any>, {

` $on?(type: string, callback: (e: any) => void): () => void; $set?(props: Partial<Record<string, any>>): void; } & Record<...>>(component: ComponentType<...> | Component<...>, options: MountOptions<...>): { $on?(type: string, callback: (e: any) => void): () => void; $set?(props: Partial<Record<string, any>>): void; } & Record<...>

Mounts a component to the given target and returns the exports and potentially
the props (if compiled with `accessors: true`) of the component. Transitions
will play during the initial render unless the `intro` option is set to
`false`.

mount(`const App: LegacyComponentType`App, { `target: Document | Element | ShadowRoot`

Target element where the component will be mounted.

target: `var document: Document`

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/document)

document.`Document.getElementById(elementId: string): HTMLElement | null`

Returns a reference to the first object with the specified value of the ID
attribute.

@paramelementId String that specifies the ID value.

getElementById("app") }); `

    
    
    function unmount(component: Record<string, any>, options?: {

` outro?: boolean; } | undefined): Promise<void>

Unmounts a component that was previously mounted using `mount` or `hydrate`.

Since 5.13.0, if `options.outro` is `true`, [transitions](transition) will
play before the component is removed from the DOM.

Returns a `Promise` that resolves after transitions have completed if
`options.outro` is true, or immediately otherwise (prior to 5.13.0, returns
`void`).

    
    
    import { mount, unmount } from 'svelte';
    import App from './App.svelte';
    
    const app = mount(App, { target: document.body });
    
    // later...
    unmount(app, { outro: true });

unmount(`

    
    
    const app: {

` $on?(type: string, callback: (e: any) => void): () => void; $set?(props:
Partial<Record<string, any>>): void; } & Record<string, any>app);

As a stop-gap-solution, you can also use `createClassComponent` or
`asClassComponent` (imported from `svelte/legacy`) instead to keep the same
API known from Svelte 4 after instantiating.

    
    
    import { 
        component: ComponentType<SvelteComponent<Props, Events, Slots>> | Component<Props>;
    }): SvelteComponent<Props, Events, Slots> & Exports
        component: ComponentType<SvelteComponent<Props, Events, Slots>> | Component<Props>;
    }): SvelteComponent<Props, Events, Slots> & Exports

Takes the same options as a Svelte 4 component and the component function and
returns a Svelte 4 compatible component.

@deprecatedUse this only as a temporary solution to migrate your imperative
component code to Svelte 5.

createClassComponent } from 'svelte/legacy'; import `

    
    
    type App = SvelteComponent<Record<string, any>, any, any>
    const App: LegacyComponentType

`App from './App.svelte' const app = new App({ target:
document.getElementById("app") }); const `const app:
SvelteComponent<Record<string, any>, any, any> & Record<string, any>`app = `

    
    
    createClassComponent<Record<string, any>, Record<string, any>, any, any>(options: ComponentConstructorOptions<Record<string, any>> & {

` component: Component<...> | ComponentType<...>; }): SvelteComponent<...> & Record<...>

Takes the same options as a Svelte 4 component and the component function and
returns a Svelte 4 compatible component.

@deprecatedUse this only as a temporary solution to migrate your imperative
component code to Svelte 5.

createClassComponent({ `component: Component<Record<string, any>, {}, string> | ComponentType<SvelteComponent<Record<string, any>, any, any>>`component: `const App: LegacyComponentType`App, `ComponentConstructorOptions<Props extends Record<string, any> = Record<string, any>>.target: Document | Element | ShadowRoot`target: `var document: Document`

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/document)

document.`Document.getElementById(elementId: string): HTMLElement | null`

Returns a reference to the first object with the specified value of the ID
attribute.

@paramelementId String that specifies the ID value.

getElementById("app") }); export default `const app:
SvelteComponent<Record<string, any>, any, any> & Record<string, any>`app;

If this component is not under your control, you can use the
`compatibility.componentApi` compiler option for auto-applied backwards
compatibility, which means code using `new Component(...)` keeps working
without adjustments (note that this adds a bit of overhead to each component).
This will also add `$set` and `$on` methods for all component instances you
get through `bind:this`.

    
    
    /// svelte.config.js
    export default {
    	compilerOptions: {
    		compatibility: {
    			componentApi: 4
    		}
    	}
    };

Note that `mount` and `hydrate` are _not_ synchronous, so things like
`onMount` won’t have been called by the time the function returns and the
pending block of promises will not have been rendered yet (because `#await`
waits a microtask to wait for a potentially immediately-resolved promise). If
you need that guarantee, call `flushSync` (import from `'svelte'`) after
calling `mount/hydrate`.

###  Server API changes

Similarly, components no longer have a `render` method when compiled for
server side rendering. Instead, pass the function to `render` from
`svelte/server`:

    
    
    import { 
        props?: Omit<Props, "$$slots" | "$$events">;
        context?: Map<any, any>;
        idPrefix?: string;
    }] : [component: Comp extends SvelteComponent<any> ? ComponentType<Comp> : Comp, options: {
        props: Omit<Props, "$$slots" | "$$events">;
        context?: Map<any, any>;
        idPrefix?: string;
    }]): RenderOutput
        props?: Omit<Props, "$$slots" | "$$events">;
        context?: Map<any, any>;
        idPrefix?: string;
    }] : [component: Comp extends SvelteComponent<any> ? ComponentType<Comp> : Comp, options: {
        props: Omit<Props, "$$slots" | "$$events">;
        context?: Map<any, any>;
        idPrefix?: string;
    }]): RenderOutput

Only available on the server and when compiling with the `server` option.
Takes a component and returns an object with `body` and `head` properties on
it, which you can use to populate the HTML when server-rendering your app.

render } from 'svelte/server'; import `

    
    
    type App = SvelteComponent<Record<string, any>, any, any>
    const App: LegacyComponentType

`App from './App.svelte'; const { html, head } = App.render({ props: {
message: 'hello' }}); const { `const html: string`html, `const head: string`

HTML that goes into the `&#x3C;head>`

head } = `

    
    
    render<SvelteComponent<Record<string, any>, any, any>, Record<string, any>>(component: ComponentType<SvelteComponent<Record<string, any>, any, any>>, options?: {

` ...; } | undefined): RenderOutput

Only available on the server and when compiling with the `server` option.
Takes a component and returns an object with `body` and `head` properties on
it, which you can use to populate the HTML when server-rendering your app.

render(`const App: LegacyComponentType`App, { `props?: Omit<Record<string, any>, "$$slots" | "$$events"> | undefined`props: { `message: string`message: 'hello' }});

In Svelte 4, rendering a component to a string also returned the CSS of all
components. In Svelte 5, this is no longer the case by default because most of
the time you’re using a tooling chain that takes care of it in other ways
(like SvelteKit). If you need CSS to be returned from `render`, you can set
the `css` compiler option to `'injected'` and it will add `<style>` elements
to the `head`.

###  Component typing changes

The change from classes towards functions is also reflected in the typings:
`SvelteComponent`, the base class from Svelte 4, is deprecated in favour of
the new `Component` type which defines the function shape of a Svelte
component. To manually define a component shape in a `d.ts` file:

    
    
    import type { Component } from 'svelte';
    export declare const MyComponent: Component<{
    	foo: string;
    }>;

To declare that a component of a certain type is required:

    
    
    import { ComponentA, ComponentB } from 'component-library';
    import type { SvelteComponent } from 'svelte';
    import type { Component } from 'svelte';
    
    let C: typeof SvelteComponent<{ foo: string }> = $state(
    let 
        foo: string;
    }, {}, string>
        foo: string;
    }, {}, string>

C: `interface Component<Props extends Record<string, any> = {}, Exports extends Record<string, any> = {}, Bindings extends keyof Props | "" = string>`

Can be used to create strongly typed Svelte components.

####  Example:

You have component library on npm called `component-library`, from which

you export a component called `MyComponent`. For Svelte+TypeScript users, you
want to provide typings. Therefore you create a `index.d.ts`:

    
    
    import type { Component } from 'svelte';
    export declare const MyComponent: Component&#x3C;{ foo: string }> {}

Typing this makes it possible for IDEs like VS Code with the Svelte extension

to provide intellisense and to use the component like this in a Svelte file
with TypeScript:

    
    
    &#x3C;script lang="ts">
    import { MyComponent } from "component-library";
    &#x3C;/script>
    &#x3C;MyComponent foo={'bar'} />

Component<{ `foo: string`foo: string }> = `

    
    
    function $state<any>(initial: any): any (+1 overload)

` namespace $state

Declares reactive state.

Example:

    
    
    let count = $state(0);

[https://svelte.dev/docs/svelte/$state]($state)

@paraminitial The initial value

$state( `var Math: Math`

An intrinsic object that provides basic mathematics functionality and
constants.

Math.`Math.random(): number`

Returns a pseudorandom number between 0 and 1.

random() ? `import ComponentA`ComponentA : `import ComponentB`ComponentB );

The two utility types `ComponentEvents` and `ComponentType` are also
deprecated. `ComponentEvents` is obsolete because events are defined as
callback props now, and `ComponentType` is obsolete because the new
`Component` type is the component type already (i.e.
`ComponentType<SvelteComponent<{ prop: string }>>` is equivalent to
`Component<{ prop: string }>`).

###  bind:this changes

Because components are no longer classes, using `bind:this` no longer returns
a class instance with `$set`, `$on` and `$destroy` methods on it. It only
returns the instance exports (`export function/const`) and, if you’re using
the `accessors` option, a getter/setter-pair for each property.

##  <svelte:component> is no longer necessary

In Svelte 4, components are _static_ — if you render `<Thing>`, and the value
of `Thing` changes, [nothing
happens](https://svelte.dev/playground/7f1fa24f0ab44c1089dcbb03568f8dfa?version=4.2.18).
To make it dynamic you had to use `<svelte:component>`.

This is no longer true in Svelte 5:

    
    
    <script>
    	import A from './A.svelte';
    	import B from './B.svelte';
    
    	let Thing = $state();
    </script>
    
    <select bind:value={Thing}>
    	<option value={A}>A</option>
    	<option value={B}>B</option>
    </select>
    
    <!-- these are equivalent -->
    <Thing />
    <svelte:component this={Thing} />

While migrating, keep in mind that your component’s name should be capitalized
(`Thing`) to distinguish it from elements, unless using dot notation.

###  Dot notation indicates a component

In Svelte 4, `<foo.bar>` would create an element with a tag name of
`"foo.bar"`. In Svelte 5, `foo.bar` is treated as a component instead. This is
particularly useful inside `each` blocks:

    
    
    {#each items as item}
    	<item.component {...item.props} />
    {/each}

##  Whitespace handling changed

Previously, Svelte employed a very complicated algorithm to determine if
whitespace should be kept or not. Svelte 5 simplifies this which makes it
easier to reason about as a developer. The rules are:

  * Whitespace between nodes is collapsed to one whitespace
  * Whitespace at the start and end of a tag is removed completely
  * Certain exceptions apply such as keeping whitespace inside `pre` tags

As before, you can disable whitespace trimming by setting the
`preserveWhitespace` option in your compiler settings or on a per-component
basis in `<svelte:options>`.

##  Modern browser required

Svelte 5 requires a modern browser (in other words, not Internet Explorer) for
various reasons:

  * it uses [`Proxies`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)
  * elements with `clientWidth` / `clientHeight`/`offsetWidth`/`offsetHeight` bindings use a [`ResizeObserver`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver) rather than a convoluted `<iframe>` hack
  * `<input type="range" bind:value={...} />` only uses an `input` event listener, rather than also listening for `change` events as a fallback

The `legacy` compiler option, which generated bulkier but IE-friendly code, no
longer exists.

##  Changes to compiler options

  * The `false` / `true` (already deprecated previously) and the `"none"` values were removed as valid values from the `css` option
  * The `legacy` option was repurposed
  * The `hydratable` option has been removed. Svelte components are always hydratable now
  * The `enableSourcemap` option has been removed. Source maps are always generated now, tooling can choose to ignore it
  * The `tag` option was removed. Use `<svelte:options customElement="tag-name" />` inside the component instead
  * The `loopGuardTimeout`, `format`, `sveltePath`, `errorMode` and `varsReport` options were removed

##  The children prop is reserved

Content inside component tags becomes a snippet prop called `children`. You
cannot have a separate prop by that name.

##  Breaking changes in runes mode

Some breaking changes only apply once your component is in runes mode.

###  Bindings to component exports are not allowed

Exports from runes mode components cannot be bound to directly. For example,
having `export const foo = ...` in component `A` and then doing `<A bind:foo
/>` causes an error. Use `bind:this` instead — `<A bind:this={a} />` — and
access the export as `a.foo`. This change makes things easier to reason about,
as it enforces a clear separation between props and exports.

###  Bindings need to be explicitly defined using $bindable()

In Svelte 4 syntax, every property (declared via `export let`) is bindable,
meaning you can `bind:` to it. In runes mode, properties are not bindable by
default: you need to denote bindable props with the `$bindable` rune.

If a bindable property has a default value (e.g. `let { foo = $bindable('bar')
} = $props();`), you need to pass a non-`undefined` value to that property if
you’re binding to it. This prevents ambiguous behavior — the parent and child
must have the same value — and results in better performance (in Svelte 4, the
default value was reflected back to the parent, resulting in wasteful
additional render cycles).

###  accessors option is ignored

Setting the `accessors` option to `true` makes properties of a component
directly accessible on the component instance.

    
    
    <svelte:options accessors={true} />
    
    <script>
    	// available via componentInstance.name
    	export let name;
    </script>

In runes mode, properties are never accessible on the component instance. You
can use component exports instead if you need to expose them.

    
    
    <script>
    	let { name } = $props();
    	// available via componentInstance.getName()
    	export const getName = () => name;
    </script>

Alternatively, if the place where they are instantiated is under your control,
you can also make use of runes inside `.js/.ts` files by adjusting their
ending to include `.svelte`, i.e. `.svelte.js` or `.svelte.ts`, and then use
`$state`:

    
    
    import { mount } from 'svelte';
    import App from './App.svelte'
    
    const app = new App({ target: document.getElementById("app"), props: { foo: 'bar' } });
    app.foo = 'baz'
    const 
        foo: string;
    }
        foo: string;
    }

props = `

    
    
    function $state<{

` foo: string; }>(initial: { foo: string; }): { foo: string; } (+1 overload)
namespace $state

Declares reactive state.

Example:

    
    
    let count = $state(0);

[https://svelte.dev/docs/svelte/$state]($state)

@paraminitial The initial value

$state({ `foo: string`foo: 'bar' }); const `

    
    
    const app: {

` $on?(type: string, callback: (e: any) => void): () => void; $set?(props:
Partial<Record<string, any>>): void; } & Record<string, any>app = `

    
    
    mount<Record<string, any>, {

` $on?(type: string, callback: (e: any) => void): () => void; $set?(props: Partial<Record<string, any>>): void; } & Record<...>>(component: ComponentType<...> | Component<...>, options: MountOptions<...>): { $on?(type: string, callback: (e: any) => void): () => void; $set?(props: Partial<Record<string, any>>): void; } & Record<...>

Mounts a component to the given target and returns the exports and potentially
the props (if compiled with `accessors: true`) of the component. Transitions
will play during the initial render unless the `intro` option is set to
`false`.

mount(`const App: LegacyComponentType`App, { `target: Document | Element | ShadowRoot`

Target element where the component will be mounted.

target: `var document: Document`

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/document)

document.`Document.getElementById(elementId: string): HTMLElement | null`

Returns a reference to the first object with the specified value of the ID
attribute.

@paramelementId String that specifies the ID value.

getElementById("app"), `props?: Record<string, any> | undefined`

Component properties.

props }); `

    
    
    const props: {

` foo: string; }props.`foo: string`foo = 'baz';

###  immutable option is ignored

Setting the `immutable` option has no effect in runes mode. This concept is
replaced by how `$state` and its variations work.

###  Classes are no longer “auto-reactive”

In Svelte 4, doing the following triggered reactivity:

    
    
    <script>
    	let foo = new Foo();
    </script>
    
    <button on:click={() => (foo.value = 1)}>{foo.value}</button
    >

This is because the Svelte compiler treated the assignment to `foo.value` as
an instruction to update anything that referenced `foo`. In Svelte 5,
reactivity is determined at runtime rather than compile time, so you should
define `value` as a reactive `$state` field on the `Foo` class. Wrapping `new
Foo()` with `$state(...)` will have no effect — only vanilla objects and
arrays are made deeply reactive.

###  Touch and wheel events are passive

When using `onwheel`, `onmousewheel`, `ontouchstart` and `ontouchmove` event
attributes, the handlers are [passive](https://developer.mozilla.org/en-
US/docs/Web/API/EventTarget/addEventListener#using_passive_listeners) to align
with browser defaults. This greatly improves responsiveness by allowing the
browser to scroll the document immediately, rather than waiting to see if the
event handler calls `event.preventDefault()`.

In the very rare cases that you need to prevent these event defaults, you
should use [`on`](svelte-events#on) instead (for example inside an action).

###  Attribute/prop syntax is stricter

In Svelte 4, complex attribute values needn’t be quoted:

    
    
    <Component prop=this{is}valid />

This is a footgun. In runes mode, if you want to concatenate stuff you must
wrap the value in quotes:

    
    
    <Component prop="this{is}valid" />

Note that Svelte 5 will also warn if you have a single expression wrapped in
quotes, like `answer="{42}"` — in Svelte 6, that will cause the value to be
converted to a string, rather than passed as a number.

###  HTML structure is stricter

In Svelte 4, you were allowed to write HTML code that would be repaired by the
browser when server side rendering it. For example you could write this...

    
    
    <table>
    	<tr>
    		<td>hi</td>
    	</tr>
    </table>

... and the browser would auto-insert a `<tbody>` element:

    
    
    <table>
    	<tbody>
    		<tr>
    			<td>hi</td>
    		</tr>
    	</tbody>
    </table>

Svelte 5 is more strict about the HTML structure and will throw a compiler
error in cases where the browser would repair the DOM.

##  Other breaking changes

###  Stricter @const assignment validation

Assignments to destructured parts of a `@const` declaration are no longer
allowed. It was an oversight that this was ever allowed.

###  :is(...) and :where(...) are scoped

Previously, Svelte did not analyse selectors inside `:is(...)` and
`:where(...)`, effectively treating them as global. Svelte 5 analyses them in
the context of the current component. As such, some selectors may now be
treated as unused if they were relying on this treatment. To fix this, use
`:global(...)` inside the `:is(...)/:where(...)` selectors.

When using Tailwind’s `@apply` directive, add a `:global` selector to preserve
rules that use Tailwind-generated `:is(...)` selectors:

    
    
    main :global {
    	@apply bg-blue-100 dark:bg-blue-900;
    }

###  CSS hash position no longer deterministic

Previously Svelte would always insert the CSS hash last. This is no longer
guaranteed in Svelte 5. This is only breaking if you [have very weird css
selectors](https://stackoverflow.com/questions/15670631/does-the-order-of-
classes-listed-on-an-item-affect-the-css).

###  Scoped CSS uses :where(...)

To avoid issues caused by unpredictable specificity changes, scoped CSS
selectors now use `:where(.svelte-xyz123)` selector modifiers alongside
`.svelte-xyz123` (where `xyz123` is, as previously, a hash of the `<style>`
contents). You can read more detail
[here](https://github.com/sveltejs/svelte/pull/10443).

In the event that you need to support ancient browsers that don’t implement
`:where`, you can manually alter the emitted CSS, at the cost of unpredictable
specificity changes:

    
    
    css = css.replace(/:where\((.+?)\)/, '$1');

###  Error/warning codes have been renamed

Error and warning codes have been renamed. Previously they used dashes to
separate the words, they now use underscores (e.g. foo-bar becomes foo_bar).
Additionally, a handful of codes have been reworded slightly.

###  Reduced number of namespaces

The number of valid namespaces you can pass to the compiler option `namespace`
has been reduced to `html` (the default), `mathml` and `svg`.

The `foreign` namespace was only useful for Svelte Native, which we’re
planning to support differently in a 5.x minor.

###  beforeUpdate/afterUpdate changes

`beforeUpdate` no longer runs twice on initial render if it modifies a
variable referenced in the template.

`afterUpdate` callbacks in a parent component will now run after `afterUpdate`
callbacks in any child components.

`beforeUpdate/afterUpdate` no longer run when the component contains a
`<slot>` and its content is updated.

Both functions are disallowed in runes mode — use `$effect.pre(...)` and
`$effect(...)` instead.

###  contenteditable behavior change

If you have a `contenteditable` node with a corresponding binding _and_ a
reactive value inside it (example: `<div contenteditable=true
bind:textContent>count is {count}</div>`), then the value inside the
contenteditable will not be updated by updates to `count` because the binding
takes full control over the content immediately and it should only be updated
through it.

###  oneventname attributes no longer accept string values

In Svelte 4, it was possible to specify event attributes on HTML elements as a
string:

    
    
    <button onclick="alert('hello')">...</button>

This is not recommended, and is no longer possible in Svelte 5, where
properties like `onclick` replace `on:click` as the mechanism for adding event
handlers.

###  null and undefined become the empty string

In Svelte 4, `null` and `undefined` were printed as the corresponding string.
In 99 out of 100 cases you want this to become the empty string instead, which
is also what most other frameworks out there do. Therefore, in Svelte 5,
`null` and `undefined` become the empty string.

###  bind:files values can only be null, undefined or FileList

`bind:files` is now a two-way binding. As such, when setting a value, it needs
to be either falsy (`null` or `undefined`) or of type `FileList`.

###  Bindings now react to form resets

Previously, bindings did not take into account `reset` event of forms, and
therefore values could get out of sync with the DOM. Svelte 5 fixes this by
placing a `reset` listener on the document and invoking bindings where
necessary.

###  walk no longer exported

`svelte/compiler` reexported `walk` from `estree-walker` for convenience. This
is no longer true in Svelte 5, import it directly from that package instead in
case you need it.

###  Content inside svelte:options is forbidden

In Svelte 4 you could have content inside a `<svelte:options />` tag. It was
ignored, but you could write something in there. In Svelte 5, content inside
that tag is a compiler error.

###  <slot> elements in declarative shadow roots are preserved

Svelte 4 replaced the `<slot />` tag in all places with its own version of
slots. Svelte 5 preserves them in the case they are a child of a `<template
shadowrootmode="...">` element.

###  <svelte:element> tag must be an expression

In Svelte 4, `<svelte:element this="div">` is valid code. This makes little
sense — you should just do `<div>`. In the vanishingly rare case that you _do_
need to use a literal value for some reason, you can do this:

    
    
    <svelte:element this={"div"}>

Note that whereas Svelte 4 would treat `<svelte:element this="input">` (for
example) identically to `<input>` for the purposes of determining which
`bind:` directives could be applied, Svelte 5 does not.

###  mount plays transitions by default

The `mount` function used to render a component tree plays transitions by
default unless the `intro` option is set to `false`. This is different from
legacy class components which, when manually instantiated, didn’t play
transitions by default.

###  <img src={...}> and {@html ...} hydration mismatches are not repaired

In Svelte 4, if the value of a `src` attribute or `{@html ...}` tag differ
between server and client (a.k.a. a hydration mismatch), the mismatch is
repaired. This is very costly: setting a `src` attribute (even if it evaluates
to the same thing) causes images and iframes to be reloaded, and reinserting a
large blob of HTML is slow.

Since these mismatches are extremely rare, Svelte 5 assumes that the values
are unchanged, but in development will warn you if they are not. To force an
update you can do something like this:

    
    
    <script>
    	let { markup, src } = $props();
    
    	if (typeof window !== 'undefined') {
    		// stash the values...
    		const initial = { markup, src };
    
    		// unset them...
    		markup = src = undefined;
    
    		$effect(() => {
    			// ...and reset after we've mounted
    			markup = initial.markup;
    			src = initial.src;
    		});
    	}
    </script>
    
    {@html markup}
    <img {src} />

###  Hydration works differently

Svelte 5 makes use of comments during server side rendering which are used for
more robust and efficient hydration on the client. As such, you shouldn’t
remove comments from your HTML output if you intend to hydrate it, and if you
manually authored HTML to be hydrated by a Svelte component, you need to
adjust that HTML to include said comments at the correct positions.

###  onevent attributes are delegated

Event attributes replace event directives: Instead of `on:click={handler}` you
write `onclick={handler}`. For backwards compatibility the `on:event` syntax
is still supported and behaves the same as in Svelte 4. Some of the `onevent`
attributes however are delegated, which means you need to take care to not
stop event propagation on those manually, as they then might never reach the
listener for this event type at the root.

###  \--style-props uses a different element

Svelte 5 uses an extra `<svelte-css-wrapper>` element instead of a `<div>` to
wrap the component when using CSS custom properties.

# What are runes?

### On this page

  * [What are runes?](what-are-runes)

> **rune** /ruːn/ _noun_
>
> A letter or mark used as a mystical or magic symbol.

Runes are symbols that you use in `.svelte` and `.svelte.js` / `.svelte.ts`
files to control the Svelte compiler. If you think of Svelte as a language,
runes are part of the syntax — they are _keywords_.

Runes have a `$` prefix and look like functions:

    
    
    let message = $state('hello');

They differ from normal JavaScript functions in important ways, however:

  * You don’t need to import them — they are part of the language
  * They’re not values — you can’t assign them to a variable or pass them as arguments to a function
  * Just like JavaScript keywords, they are only valid in certain positions (the compiler will help you if you put them in the wrong place)

> Legacy mode
>
> Runes didn’t exist prior to Svelte 5.