## docs/svelte/index.md

--- title: Svelte ---

## docs/svelte/01-introduction/index.md

--- title: Introduction ---

## docs/svelte/01-introduction/01-overview.md

--- title: 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... ```svelte <!file: App.svelte> <script> 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](../kit)) and everything in between. These pages serve as reference documentation. If you're new to Svelte, we recommend starting with the [interactive tutorial](/tutorial) and coming back here when you have questions. You can also try Svelte online in the [playground](/playground) or, if you need a more fully-featured environment, on [StackBlitz](https://sveltekit.new).

## docs/svelte/01-introduction/02-getting-started.md

--- title: Getting started --- We recommend using [SvelteKit](../kit), which lets you [build almost anything](../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: ```sh 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 via [vite-plugin-svelte](https://github.com/sveltejs/vite-plugin-svelte) by running `npm create vite@latest` and selecting the `svelte` option (or, if working with an existing project, adding the plugin to your `vite.config.js` file). With this, `npm run build` will generate HTML, JS, and CSS files inside the `dist` directory. In most cases, you will probably need to [choose a routing library](/packages#routing) as well. >[!NOTE] Vite is often used in standalone mode to build [single page apps (SPAs)](../kit/glossary#SPA), which you can also [build with SvelteKit](../kit/single-page-apps). There are also [plugins for other bundlers](/packages#bundler-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/collection/editor-support-c85c080efc292a34) and tools as well. You can also check your code from the command line using [`npx sv check`](https://svelte.dev/docs/cli/sv-check). ## Getting help Don't be shy about asking for help in the [Discord chatroom](/chat)! You can also find answers on [Stack Overflow](https://stackoverflow.com/questions/tagged/svelte).

## docs/svelte/01-introduction/03-svelte-files.md

--- title: .svelte files --- 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. ```svelte /// file: MyComponent.svelte <script module> // module-level logic goes here // (you will rarely use this) </script> <script> // instance-level logic goes here </script> <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. ```svelte <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. > In Svelte 4, this script tag was created using `<script context="module">` ## `<style>` CSS inside a `<style>` block will be scoped to that component. ```svelte <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).

## docs/svelte/01-introduction/04-svelte-js-files.md

--- title: .svelte.js and .svelte.ts 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)). > This is a concept that didn't exist prior to Svelte 5

## docs/svelte/02-runes/index.md

--- title: Runes ---

## docs/svelte/02-runes/01-what-are-runes.md

--- title: What are runes? --- > > 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: ```js 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) > Runes didn't exist prior to Svelte 5.

## docs/svelte/02-runes/02-$state.md

--- title: $state tags: rune-state --- The `$state` rune allows you to create _reactive state_, which means that your UI _reacts_ when it changes. ```svelte <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 or an object created with `Object.create`). In a case like this... ```js 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: ```js let todos = [{ done: false, text: 'add more todos' }]; //cut todos[0].done = !todos[0].done; ``` If you push a new object to the array, it will also be proxified: ```js let todos = [{ done: false, text: 'add more todos' }]; //cut todos.push({ done: false, text: 'eat lunch' }); ``` 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: ```js let todos = [{ done: false, text: 'add more todos' }]; //cut 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`: ```js // @errors: 7006 2554 class Todo { done = $state(false); constructor(text) { this.text = $state(text); } reset() { this.text = ''; this.done = false; } } ``` 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`: ```svelte <button onclick={todo.reset}> reset </button> ``` You can either use an inline function... ```svelte <button onclick={() => todo.reset()}> reset </button> ``` ...or use an arrow function in the class definition: ```js // @errors: 7006 2554 class Todo { done = $state(false); constructor(text) { this.text = $state(text); } reset = () => { this.text = ''; this.done = false; } } ``` ### Built-in classes Svelte provides reactive implementations of built-in classes like `Set`, `Map`, `Date` and `URL` 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: ```js 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`: ```svelte <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`. ## `$state.eager` When state changes, it may not be reflected in the UI immediately if it is used by an `await` expression, because [updates are synchronized](await-expressions#Synchronized-updates). In some cases, you may want to update the UI as soon as the state changes. For example, you might want to update a navigation bar when the user clicks on a link, so that they get visual feedback while waiting for the new page to load. To do this, use `$state.eager(value)`: ```svelte <nav> <a href="/" aria-current={$state.eager(pathname) === '/' ? 'page' : null}>home</a> <a href="/about" aria-current={$state.eager(pathname) === '/about' ? 'page' : null}>about</a> </nav> ``` Use this feature sparingly, and only to provide feedback in response to user action — in general, allowing Svelte to coordinate updates will provide a better user experience. ## 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: ```js /// file: index.js // @filename: index.js //cut /** * @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! ``` 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: ```js /// file: index.js // @filename: index.js //cut /** * @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 ``` State in Svelte is no different — when you reference something declared with the `$state` rune... ```js let a =$state(1); let b =$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... ```js /// file: index.js // @filename: index.js //cut /** * @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 ``` ...though if you find yourself writing code like that, consider using [classes](#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: ```js /// file: state.svelte.js 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: ```js /// file: state.svelte.js (compiler output) // @filename: index.ts interface Signal<T> { value: T; } interface Svelte { state<T>(value?: T): Signal<T>; get<T>(source: Signal<T>): T; set<T>(source: Signal<T>, value: T): void; } declare const $: Svelte; //cut export let count = $.state(0); export function increment() { $.set(count, $.get(count) + 1); } ``` 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`: ```js // @filename: state.svelte.js export let count = 0; // @filename: index.js //cut 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... ```js // 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: ```js let count = $state(0); export function getCount() { return count; } export function increment() { count += 1; } ```

## docs/svelte/02-runes/03-$derived.md

--- title: $derived tags: rune-derived --- Derived state is declared with the `$derived` rune: ```svelte <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`. ## `$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. ```svelte <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: ```svelte <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> ``` ## 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](/REMOVED)... ```js // @errors: 7005 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. ## Destructuring If you use destructuring with a `$derived` declaration, the resulting variables will all be reactive — this... ```js function stuff() { return { a: 1, b: 2, c: 3 } } //cut let { a, b, c } = $derived(stuff()); ``` ...is roughly equivalent to this: ```js function stuff() { return { a: 1, b: 2, c: 3 } } //cut let _stuff = $derived(stuff()); let a = $derived(_stuff.a); let b = $derived(_stuff.b); let c = $derived(_stuff.c); ``` ## 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`: ```svelte <script> let count = $state(0); let large = $derived(count > 10); </script> <button onclick={() => count++}> {large} </button> ```

## docs/svelte/02-runes/04-$effect.md

--- title: $effect tags: rune-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`](#When-not-to-use-$effect) to learn about alternative approaches. You can create an effect with the `$effect` rune ([demo](/REMOVED)): ```svelte <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. ### 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. An effect can return a _teardown function_ which will run immediately before the effect re-runs ([demo](/REMOVED)). ```svelte <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](https://svelte.dev/docs/svelte/$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](/REMOVED)): ```ts // @filename: index.ts declare let canvas: { width: number; height: number; getContext(type: '2d', options?: CanvasRenderingContext2DSettings): CanvasRenderingContext2D; }; declare let color: string; declare let size: number; //cut $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).) ```svelte <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. This means that changes to either `condition` or `color` [will cause the effect to re-run](/REMOVED). Conversely, if `condition` is `false`, `color` will not be evaluated, and the effect will _only_ re-run again when `condition` changes. ```ts // @filename: ambient.d.ts declare module 'canvas-confetti' { interface ConfettiOptions { colors: string[]; } function confetti(opts?: ConfettiOptions): void; export default confetti; } // @filename: index.js //cut 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: ```svelte <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](/REMOVED)): ```svelte <script> console.log('in component setup:', $effect.tracking()); // false $effect(() => { console.log('in effect:', $effect.tracking()); // true }); </script> <p>in template: {$effect.tracking()}</p> ``` It is used to implement abstractions like [`createSubscriber`](/docs/svelte/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.pending` When using [`await`](await-expressions) in components, the `$effect.pending()` rune tells you how many promises are pending in the current [boundary](svelte-boundary), not including child boundaries ([demo](/REMOVED)): ```svelte <button onclick={() => a++}>a++</button> <button onclick={() => b++}>b++</button> <p>{a} + {b} = {await add(a, b)}</p> {#if $effect.pending()} <p>pending promises: {$effect.pending()}</p> {/if} ``` ## `$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. ```js 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... ```svelte <script> let count = $state(0); let doubled = $state(); // don't do this! $effect(() => { doubled = count * 2; }); </script> ``` ...do this: ```svelte <script> let count = $state(0); let doubled = $derived(count * 2); </script> ``` 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](/REMOVED)): ```svelte <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](/REMOVED)): ```svelte <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).

## docs/svelte/02-runes/05-$props.md

--- title: $props tags: rune-props --- 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: ```svelte <!file: App.svelte> <script> import MyComponent from './MyComponent.svelte'; </script> <MyComponent adjective="cool" /> ``` On the other side, inside `MyComponent.svelte`, we can receive props with the `$props` rune... ```svelte <!file: MyComponent.svelte> <script> 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: ```svelte <!file: MyComponent.svelte> <script> 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`): ```js let { adjective = 'happy' } = $props(); ``` ## 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`: ```js 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: ```js 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](/REMOVED)): ```svelte <!file: App.svelte> <script> import Child from './Child.svelte'; let count = $state(0); </script> <button onclick={() => (count += 1)}> clicks (parent): {count} </button> <Child {count} /> ``` ```svelte <!file: Child.svelte> <script> 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](/REMOVED)): ```svelte <!file: App.svelte> <script> import Child from './Child.svelte'; </script> <Child object={{ count: 0 }} /> ``` ```svelte <!file: Child.svelte> <script> 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](/REMOVED)): ```svelte <!file: App.svelte> <script> import Child from './Child.svelte'; let object = $state({count: 0}); </script> <Child {object} /> ``` ```svelte <!file: Child.svelte> <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> ``` 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](/REMOVED)) ```svelte <!file: Child.svelte> <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> ``` 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... ```svelte <script lang="ts"> let { adjective }: { adjective: string } = $props(); </script> ``` ...while in JSDoc you can do this: ```svelte <script> /** @type {{ adjective: string }} */ let { adjective } = $props(); </script> ``` You can, of course, separate the type declaration from the annotation: ```svelte <script lang="ts"> interface Props { adjective: string; } let { adjective }: Props = $props(); </script> ``` If your component exposes [snippet](snippet) props like `children`, these should be typed using the `Snippet` interface imported from `'svelte'` — see [Typing snippets](snippet#Typing-snippets) for examples. 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`. ```svelte <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> ```

## docs/svelte/02-runes/06-$bindable.md

--- title: $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 — overuse can make your data flow unpredictable and your components harder to maintain — but it can simplify your code if used sparingly and carefully. It also means that a state proxy can be _mutated_ in the child. To mark a prop as bindable, we use the `$bindable` rune: ```svelte /// file: FancyInput.svelte <script> 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](/REMOVED)): ```svelte /// file: App.svelte <script> 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: ```js /// file: FancyInput.svelte let { value = $bindable('fallback'), ...props } = $props(); ```

## docs/svelte/02-runes/07-$inspect.md

--- title: $inspect tags: rune-inspect --- 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](/REMOVED)): ```svelte <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} /> ``` On updates, a stack trace will be printed, making it easy to find the origin of a state change (unless you're in the playground, due to technical limitations). ## $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](/REMOVED)): ```svelte <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> ``` ## $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. ```svelte <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.

## docs/svelte/02-runes/08-$host.md

--- title: $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](/REMOVED)): ```svelte /// file: Stepper.svelte <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 /// file: App.svelte <script> import './Stepper.svelte'; let count = $state(0); </script> <my-stepper ondecrement={() => count -= 1} onincrement={() => count += 1} ></my-stepper> <p>count: {count}</p> ```

## docs/svelte/03-template-syntax/index.md

--- title: Template syntax ---

## docs/svelte/03-template-syntax/01-basic-markup.md

--- title: Basic markup --- 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_. ```svelte <script> import Widget from './Widget.svelte'; </script> <div> <Widget /> </div> ``` ## Element attributes By default, attributes work exactly like their HTML counterparts. ```svelte <div class="foo"> <button disabled>can't touch this</button> </div> ``` As in HTML, values may be unquoted. ```svelte <input type=checkbox /> ``` Attribute values can contain JavaScript expressions. ```svelte <a href="page/{p}">page {p}</a> ``` Or they can _be_ JavaScript expressions. ```svelte <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`). ```svelte <input required={false} placeholder="This input field is not required" /> <div title={null}>This div has no title attribute</div> ``` > > > ```svelte > <button disabled="{number !== 42}">...</button> > ``` When the attribute name and value match (`name={name}`), they can be replaced with `{name}`. ```svelte <button {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. ```svelte <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`: ```svelte <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: ```svelte <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. ```svelte {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. ```svelte <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. ```svelte {@html potentiallyUnsafeHtmlString} ``` ## Comments You can use HTML comments inside components. ```svelte <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 <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. ````svelte <script> let { name } = $props(); </script> <main> <h1> Hello, {name} </h1> </main> ````

## docs/svelte/03-template-syntax/02-if.md

--- title: {#if ...} tags: template-if --- ```svelte <!copy: false> {#if expression}...{/if} ``` ```svelte <!copy: false> {#if expression}...{:else if expression}...{/if} ``` ```svelte <!copy: false> {#if expression}...{:else}...{/if} ``` Content that is conditionally rendered can be wrapped in an if block. ```svelte {#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. ```svelte {#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.)

## docs/svelte/03-template-syntax/03-each.md

--- title: {#each ...} tags: template-each --- ```svelte <!copy: false> {#each expression as name}...{/each} ``` ```svelte <!copy: false> {#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`. (Internally, they are converted to arrays with [`Array.from`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from).) If the value is `null` or `undefined`, it is treated the same as an empty array (which will cause [else blocks](#Else-blocks) to be rendered, where applicable). ```svelte <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: ```svelte {#each items as item, i} <li>{i + 1}: {item.name} x {item.qty}</li> {/each} ``` ## Keyed each blocks ```svelte <!copy: false> {#each expression as name (key)}...{/each} ``` ```svelte <!copy: false> {#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. ```svelte {#each items as item (item.id)} <li>{item.name} x {item.qty}</li> {/each} {#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. ```svelte {#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 ```svelte <!copy: false> {#each expression}...{/each} ``` ```svelte <!copy: false> {#each expression, index}...{/each} ``` In case you just want to render something `n` times, you can omit the `as` part ([demo](/REMOVED)): ```svelte <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 ```svelte <!copy: false> {#each expression as name}...{:else}...{/each} ``` An each block can also have an `{:else}` clause, which is rendered if the list is empty. ```svelte {#each todos as todo} <p>{todo.text}</p> {:else} <p>No tasks today!</p> {/each} ```

## docs/svelte/03-template-syntax/04-key.md

--- title: {#key ...} tags: template-key --- ```svelte <!copy: false> {#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: ```svelte {#key value} <Component /> {/key} ``` It's also useful if you want a transition to play whenever a value changes: ```svelte {#key value} <div transition:fade>{value}</div> {/key} ```

## docs/svelte/03-template-syntax/05-await.md

--- title: {#await ...} tags: template-await --- ```svelte <!copy: false> {#await expression}...{:then name}...{:catch name}...{/await} ``` ```svelte <!copy: false> {#await expression}...{:then name}...{/await} ``` ```svelte <!copy: false> {#await expression then name}...{/await} ``` ```svelte <!copy: false> {#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. ```svelte {#await promise} <p>waiting for the promise to resolve...</p> {:then value} <p>The value is {value}</p> {:catch error} <p>Something went wrong: {error.message}</p> {/await} ``` > > 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). ```svelte {#await promise} <p>waiting for the promise to resolve...</p> {:then value} <p>The value is {value}</p> {/await} ``` If you don't care about the pending state, you can also omit the initial block. ```svelte {#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. ```svelte {#await promise catch error} <p>The error is {error}</p> {/await} ``` > > ```svelte > {#await import('./Component.svelte') then { default: Component }} > <Component /> > {/await} > ```

## docs/svelte/03-template-syntax/06-snippet.md

--- title: {#snippet ...} --- ```svelte <!copy: false> {#snippet name()}...{/snippet} ``` ```svelte <!copy: false> {#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](/REMOVED)... ```svelte {#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](/REMOVED): ```svelte {#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](/REMOVED))... ```svelte <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): ```svelte <div> {#snippet x()} {#snippet y()}...{/snippet} {@render y()} {/snippet} {@render y()} </div> {@render x()} ``` Snippets can reference themselves and each other ([demo](/REMOVED)): ```svelte {#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](/REMOVED)): ```svelte <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](/REMOVED)): ```svelte <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](/REMOVED)): ```svelte <!file: App.svelte> <Button>click me</Button> ``` ```svelte <!file: Button.svelte> <script> let { children } = $props(); </script> <button>{@render children()}</button> ``` ### 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... ```svelte <script> let { children } = $props(); </script> {@render children?.()} ``` ...or use an `#if` block to render fallback content: ```svelte <script> let { children } = $props(); </script> {#if children} {@render children()} {:else} fallback content {/if} ``` ## Typing snippets Snippets implement the `Snippet` interface imported from `'svelte'`: ```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: ```svelte <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](/REMOVED)): ```svelte <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 so slots have been deprecated in Svelte 5.

## docs/svelte/03-template-syntax/07-@render.md

--- title: {@render ...} --- To render a [snippet](snippet), use a `{@render ...}` tag. ```svelte {#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: ```svelte {@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: ```svelte {@render children?.()} ``` Alternatively, use an [`{#if ...}`](if) block with an `:else` clause to render fallback content: ```svelte {#if children} {@render children()} {:else} <p>fallback content</p> {/if} ```

## docs/svelte/03-template-syntax/08-@html.md

--- title: {@html ...} tags: template-html --- To inject raw HTML into your component, use the `{@html ...}` tag: ```svelte <article> {@html content} </article> ``` The expression should be valid standalone HTML — this will not work, because `</div>` is not valid HTML: ```svelte {@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: ```svelte <article> {@html content} </article> <style> article { a { color: hotpink } img { width: 100% } } </style> ``` Instead, use the `:global` modifier to target everything inside the `<article>`: ```svelte <style> article:global{ a { color: hotpink } img { width: 100% } } </style> ```

## docs/svelte/03-template-syntax/09-@attach.md

--- title: {@attach ...} tags: 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. ```svelte <!file: App.svelte> <script> /** @type {import('svelte/attachments').Attachment} */ function myAttachment(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](/REMOVED)): ```svelte <!file: App.svelte> <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> ``` 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](#Controlling-when-attachments-re-run).) ## Inline attachments Attachments can also be created inline ([demo](/REMOVED)): ```svelte <!file: App.svelte> <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. ## Conditional attachments Falsy values like `false` or `undefined` are treated as no attachment, enabling conditional usage: ```svelte <div {@attach enabled && myAttachment}>...</div> ``` ## 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](/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](/REMOVED)): ```svelte <!file: Button.svelte> <script> /** @type {import('svelte/elements').HTMLButtonAttributes} */ let { children, ...props } = $props(); </script> <button {...props}> {@render children?.()} </button> ``` ```svelte <!file: App.svelte> <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> ``` ## 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`): ```js // @errors: 7006 2304 2552 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: ```js // @errors: 7006 2304 2552 function foo(getBar) { return (node) => { veryExpensiveSetupWork(node); $effect(() => { update(node, 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.

## docs/svelte/03-template-syntax/10-@const.md

--- title: {@const ...} --- The `{@const ...}` tag defines a local constant. ```svelte {#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>`.

## docs/svelte/03-template-syntax/11-@debug.md

--- title: {@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. ```svelte <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). ```svelte {@debug user} {@debug user1, user2, user3} {@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.

## docs/svelte/03-template-syntax/12-bind.md

--- title: bind: --- 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: ```svelte <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: ```svelte <input bind:value={ () => value, (v) => value = v.toLowerCase()} /> ``` In the case of readonly bindings like [dimension bindings](#Dimensions), the `get` value should be `null`: ```svelte <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: ```svelte <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](/REMOVED)): ```svelte <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`. ```svelte <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 inputs can be bound with `bind:checked`: ```svelte <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`. ```svelte <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: ```svelte <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](/REMOVED)): ```svelte <!file: BurritoChooser.svelte> <script> let tortilla = $state('Plain'); /** @type {string[]} */ let fillings = $state([]); </script> <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> <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> ``` ## `<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. ```svelte <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. ## `<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). ```svelte <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>`. ```svelte <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. ```svelte <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`. ```svelte <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) ```svelte <audio src={clip} bind:duration bind:currentTime bind:paused></audio> ``` ## `<video>` `<video>` elements have all the same bindings as [`<audio>`](#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. ```svelte <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) ```svelte <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) ```svelte <div bind:offsetWidth={width} bind:offsetHeight={height}> <Chart {width} {height} /> </div> ``` ## bind:this ```svelte <!copy: false> 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: ```svelte <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. ```svelte <!file: App.svelte> <ShoppingCart bind:this={cart} /> <button onclick={() => cart.empty()}> Empty shopping cart </button> ``` ```svelte <!file: ShoppingCart.svelte> <script> // All instance exports are available on the instance object export function empty() { // ... } </script> ``` ## bind:_property_ for components ```svelte bind:property={variable} ``` You can bind to component props using the same syntax as for elements. ```svelte <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: ```svelte <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: ```svelte <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.

## docs/svelte/03-template-syntax/13-use.md

--- title: use: --- > 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: ```svelte <!file: App.svelte> <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> ``` An action can be called with an argument: ```svelte <!file: App.svelte> <script> /** @type {import('svelte/action').Action} */ function myaction(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. > 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: ```svelte <!file: App.svelte> <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> ```

## docs/svelte/03-template-syntax/14-transition.md

--- title: transition: tags: transitions --- 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. ```svelte <script> import { fade } from 'svelte/transition'; let visible = $state(false); </script> <button onclick={() => visible = !visible}>toggle</button> {#if visible} <divtransition: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. ```svelte {#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.) ```svelte {#if visible} <div transition:fade={{ duration: 2000 }}>fades in and out over two seconds</div> {/if} ``` ## Custom transition functions ```js /// copy: false // @noErrors 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. ```svelte <!file: App.svelte> <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} ``` A custom transition function can also return a `tick` function, which is called _during_ the transition with the same `t` and `u` arguments. ```svelte <!file: App.svelte> <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} ``` 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](/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` ```svelte {#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} ```

## docs/svelte/03-template-syntax/15-in-and-out.md

--- title: in: and out: tags: transitions --- 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. ```svelte <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} ```

## docs/svelte/03-template-syntax/16-animate.md

--- title: animate: --- 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](#Custom-animation-functions). ```svelte {#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.) ```svelte {#each list as item, index (item)} <li animate:flip={{ delay: 500 }}>{item}</li> {/each} ``` ## Custom animation functions ```js /// copy: false // @noErrors 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. ```svelte <!file: App.svelte> <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} ``` A custom animation function can also return a `tick` function, which is called _during_ the animation with the same `t` and `u` arguments. ```svelte <!file: App.svelte> <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} ```

## docs/svelte/03-template-syntax/17-style.md

--- title: style: tags: template-style --- The `style:` directive provides a shorthand for setting multiple styles on an element. ```svelte <div style:color="red">...</div> <div style="color: red;">...</div> ``` The value can contain arbitrary expressions: ```svelte <div style:color={myColor}>...</div> ``` The shorthand form is allowed: ```svelte <div style:color>...</div> ``` Multiple styles can be set on a single element: ```svelte <div style:color style:width="12rem" style:background-color={darkMode ? 'black' : 'white'}>...</div> ``` To mark a style as important, use the `|important` modifier: ```svelte <div style:color|important="red">...</div> ``` When `style:` directives are combined with `style` attributes, the directives will take precedence, even over `!important` properties: ```svelte <div style:color="red" style="color: blue">This will be red</div> <div style:color="red" style="color: blue !important">This will still be red</div> ```

## docs/svelte/03-template-syntax/18-class.md

--- title: class tags: template-style --- 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: ```svelte <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: ```svelte <script> let { cool } = $props(); </script> <div class={{ cool, lame: !cool }}>...</div> ``` If the value is an array, the truthy values are combined: ```svelte <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: ```svelte <!file: Button.svelte> <script> 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: ```svelte <!file: App.svelte> <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> ``` Since Svelte 5.19, 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: ```svelte <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. ```svelte <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: ```svelte <div class:cool class:lame={!cool}>...</div> ```

## docs/svelte/03-template-syntax/19-await-expressions.md

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

## docs/svelte/04-styling/index.md

--- title: Styling ---

## docs/svelte/04-styling/01-scoped-styles.md

--- title: Scoped styles tags: styles-scoped --- 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`). ```svelte <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: ```svelte <style> .bouncy { animation: bounce 10s; } /* these keyframes are only accessible inside this component */ @keyframes bounce { /* ... */ } </style> ```

## docs/svelte/04-styling/02-global-styles.md

--- title: Global styles tags: styles-global --- ## :global(...) To apply styles to a single selector globally, use the `:global(...)` modifier: ```svelte <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. ```svelte <style> @keyframes -global-my-animation-name { /* code goes here */ } </style> ``` ## :global To apply styles to a group of selectors globally, create a `:global {...}` block: ```svelte <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> ```

## docs/svelte/04-styling/03-custom-properties.md

--- title: Custom properties tags: styles-custom-properties --- You can pass CSS custom properties — both static and dynamic — to components: ```svelte <Slider bind:value min={0} max={100} --track-color="black" --thumb-color="rgb({r} {g} {b})" /> ``` The above code essentially desugars to this: ```svelte <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: ```svelte <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): ```svelte <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.

## docs/svelte/04-styling/04-nested-style-elements.md

--- title: 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. ```svelte <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> ```

## docs/svelte/05-special-elements/index.md

--- title: Special elements ---

## docs/svelte/05-special-elements/01-svelte-boundary.md

--- title: <svelte:boundary> --- ```svelte <svelte:boundary onerror={handler}>...</svelte:boundary> ``` > This feature was added in 5.3.0 Boundaries allow you to 'wall off' parts of your app, so that you can: - provide UI that should be shown when [`await`](await-expressions) expressions are first resolving - handle errors that occur during rendering or while running effects, and provide UI that should be rendered when an error happens If a boundary handles an error (with a `failed` snippet or `onerror` handler, or both) its existing content will be removed. ## Properties For the boundary to do anything, one or more of the following must be provided. ### `pending` This snippet will be shown when the boundary is first created, and will remain visible until all the [`await`](await-expressions) expressions inside the boundary have resolved ([demo](/REMOVED)): ```svelte <svelte:boundary> <p>{await delayed('hello!')}</p> {#snippet pending()} <p>loading...</p> {/snippet} </svelte:boundary> ``` The `pending` snippet will _not_ be shown for subsequent async updates — for these, you can use [`$effect.pending()`]($effect#$effect.pending). ### `failed` If a `failed` snippet is provided, it will be rendered when an error is thrown inside the boundary, with the `error` and a `reset` function that recreates the contents ([demo](/REMOVED)): ```svelte <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 > <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 <svelte:boundary onerror={(e) => report(e)}> ... </svelte:boundary> ``` ...or using `error` and `reset` outside the boundary itself: ```svelte <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. ## Using `transformError` By default, error boundaries have no effect on the server — if an error occurs during rendering, the render as a whole will fail. Since 5.51 you can control this behaviour for boundaries with a `failed` snippet, by calling [`render(...)`](imperative-component-api#render) with a `transformError` function. The `transformError` function must return a JSON-stringifiable object which will be used to render the `failed` snippet. This object will be serialized and used to hydrate the snippet in the browser: ```js // @errors: 1005 import { render } from 'svelte/server'; import App from './App.svelte'; const { head, body } = await render(App, { transformError: (error) => { // log the original error, with the stack trace... console.error(error); // ...and return a sanitized user-friendly error // to display in the `failed` snippet return { message: 'An error occurred!' }; }; }); ``` If `transformError` throws (or rethrows) an error, `render(...)` as a whole will fail with that error. If the boundary has an `onerror` handler, it will be called upon hydration with the deserialized error object. The [`mount`](imperative-component-api#mount) and [`hydrate`](imperative-component-api#hydrate) functions also accept a `transformError` option, which defaults to the identity function. As with `render`, this function transforms a render-time error before it is passed to a `failed` snippet or `onerror` handler.

## docs/svelte/05-special-elements/02-svelte-window.md

--- title: <svelte:window> --- ```svelte <svelte:window onevent={handler} /> ``` ```svelte <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. ```svelte <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 <svelte:window bind:scrollY={y} /> ```

## docs/svelte/05-special-elements/03-svelte-document.md

--- title: <svelte:document> --- ```svelte <svelte:document onevent={handler} /> ``` ```svelte <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 [attachments](@attach) 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 <svelte:document onvisibilitychange={handleVisibilityChange} {@attach someAttachment} /> ``` You can also bind to the following properties: - `activeElement` - `fullscreenElement` - `pointerLockElement` - `visibilityState` All are readonly.

## docs/svelte/05-special-elements/04-svelte-body.md

--- title: <svelte:body> --- ```svelte <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 <svelte:body onmouseenter={handleMouseenter} onmouseleave={handleMouseleave} use:someAction /> ```

## docs/svelte/05-special-elements/05-svelte-head.md

--- title: <svelte:head> --- ```svelte <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 <svelte:head> <title>Hello world!</title> <meta name="description" content="This is where the description goes for SEO" /> </svelte:head> ```

## docs/svelte/05-special-elements/06-svelte-element.md

--- title: <svelte:element> --- ```svelte <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: ```svelte <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 <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.

## docs/svelte/05-special-elements/07-svelte-options.md

--- title: <svelte:options> --- ```svelte <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 > 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 <svelte:options customElement="my-custom-element" /> ```

## docs/svelte/06-runtime/index.md

--- title: Runtime ---

## docs/svelte/06-runtime/01-stores.md

--- title: Stores --- A _store_ is an object that allows reactive access to a value via a simple _store contract_. The [`svelte/store` module](../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. ```svelte <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 ```ts /// file: state.svelte.js export const userState = $state({ name: 'name', /* ... */ }); ``` ```svelte <!file: App.svelte> <script> 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. ```js /// file: store.js 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. ```js /// file: store.js 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`. ```ts 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. ```ts // @filename: ambient.d.ts import { type Writable } from 'svelte/store'; declare global { const a: Writable<number>; } export {}; // @filename: index.ts //cut 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`. ```ts // @filename: ambient.d.ts import { type Writable } from 'svelte/store'; declare global { const a: Writable<number>; } export {}; // @filename: index.ts // @errors: 18046 2769 7006 //cut 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. ```ts // @filename: ambient.d.ts import { type Writable } from 'svelte/store'; declare global { const frequency: Writable<number>; } export {}; // @filename: index.ts //cut 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. ```ts // @filename: ambient.d.ts import { type Writable } from 'svelte/store'; declare global { const a: Writable<number>; const b: Writable<number>; } export {}; // @filename: index.ts //cut 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. ```js import { readonly, writable } from 'svelte/store'; const writableStore = writable(1); const readableStore = readonly(writableStore); readableStore.subscribe(console.log); writableStore.set(2); // console: 2 // @errors: 2339 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. ```ts // @filename: ambient.d.ts import { type Writable } from 'svelte/store'; declare global { const store: Writable<string>; } export {}; // @filename: index.ts //cut import { get } from 'svelte/store'; const value = get(store); ``` ## Store contract ```ts // @noErrors store = { subscribe: (subscription: (value: any) => void) => (() => void), set?: (value: any) => void } ``` You can create your own stores without relying on [`svelte/store`](../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.

## docs/svelte/06-runtime/02-context.md

--- title: Context --- 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)`... ```svelte <!file: Parent.svelte> <script> import { setContext } from 'svelte'; setContext('my-context', 'hello from Parent.svelte'); </script> ``` ...and the child retrieves it with `getContext`: ```svelte <!file: Child.svelte> <script> 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](/REMOVED)): ```svelte <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](/REMOVED))... ```svelte <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... ```svelte <button onclick={() => counter = { count: 0 }}> reset </button> ``` ...you must do this: ```svelte <button onclick={() =>counter.count = 0}> reset </button> ``` Svelte will warn you if you get it wrong. ## Type-safe context As an alternative to using `setContext` and `getContext` directly, you can use them via `createContext`. This gives you type safety and makes it unnecessary to use a key: ```ts /// file: context.ts // @filename: ambient.d.ts interface User {} // @filename: index.ts //cut import { createContext } from 'svelte'; export const [getUserContext, setUserContext] = createContext<User>(); ``` When writing [component tests](testing#Unit-and-component-tests-with-Vitest-Component-testing), it can be useful to create a wrapper component that sets the context in order to check the behaviour of a component that uses it. As of version 5.49, you can do this sort of thing: ```js import { mount, unmount } from 'svelte'; import { expect, test } from 'vitest'; import { setUserContext } from './context'; import MyComponent from './MyComponent.svelte'; test('MyComponent', () => { function Wrapper(...args) { setUserContext({ name: 'Bob' }); return MyComponent(...args); } const component = mount(Wrapper, { target: document.body }); expect(document.body.innerHTML).toBe('<h1>Hello Bob!</h1>'); unmount(component); }); ``` This approach also works with [`hydrate`](imperative-component-api#hydrate) and [`render`](imperative-component-api#render). ## 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: ```js /// file: state.svelte.js 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!)... ```svelte <!file: App.svelte-> <script> 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.

## docs/svelte/06-runtime/03-lifecycle-hooks.md

--- title: Lifecycle hooks --- 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. ```svelte <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. ```svelte <script> import { onMount } from 'svelte'; onMount(() => { const interval = setInterval(() => { console.log('beep'); }, 1000); return () => clearInterval(interval); }); </script> ``` ## `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. ```svelte <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. ```svelte <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. ```svelte <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](/REMOVED) - [After](/REMOVED) ```svelte <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> <inputonkeydown={handleKeydown} /> <buttononclick={toggle}> Toggle dark mode </button> </div> ```

## docs/svelte/06-runtime/04-imperative-component-api.md

--- title: Imperative component API --- 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: ```js // @errors: 2322 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`](#mount) or [`hydrate`](#hydrate). If `options.outro` is `true`, [transitions](transition) will play before the component is removed from the DOM: ```js 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: ```js // @errors: 2724 2305 2307 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`](#render) function) inside the target and make it interactive: ```js // @errors: 2322 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.

## docs/svelte/06-runtime/05-hydratable.md

--- title: Hydratable data --- In Svelte, when you want to render asynchronous content data on the server, you can simply `await` it. This is great! However, it comes with a pitfall: when hydrating that content on the client, Svelte has to redo the asynchronous work, which blocks hydration for however long it takes: ```svelte <script> import { getUser } from 'my-database-library'; // This will get the user on the server, render the user's name into the h1, // and then, during hydration on the client, it will get the user _again_, // blocking hydration until it's done. const user = await getUser(); </script> <h1>{user.name}</h1> ``` That's silly, though. If we've already done the hard work of getting the data on the server, we don't want to get it again during hydration on the client. `hydratable` is a low-level API built to solve this problem. You probably won't need this very often — it will be used behind the scenes by whatever datafetching library you use. For example, it powers [remote functions in SvelteKit](/docs/kit/remote-functions). To fix the example above: ```svelte <script> import { hydratable } from 'svelte'; import { getUser } from 'my-database-library'; // During server rendering, this will serialize and stash the result of `getUser`, associating // it with the provided key and baking it into the `head` content. During hydration, it will // look for the serialized version, returning it instead of running `getUser`. After hydration // is done, if it's called again, it'll simply invoke `getUser`. const user = await hydratable('user', () => getUser()); </script> <h1>{user.name}</h1> ``` This API can also be used to provide access to random or time-based values that are stable between server rendering and hydration. For example, to get a random number that doesn't update on hydration: ```ts import { hydratable } from 'svelte'; const rand = hydratable('random', () => Math.random()); ``` If you're a library author, be sure to prefix the keys of your `hydratable` values with the name of your library so that your keys don't conflict with other libraries. ## Serialization All data returned from a `hydratable` function must be serializable. But this doesn't mean you're limited to JSON — Svelte uses [`devalue`](https://npmjs.com/package/devalue), which can serialize all sorts of things including `Map`, `Set`, `URL`, and `BigInt`. Check the documentation page for a full list. In addition to these, thanks to some Svelte magic, you can also fearlessly use promises: ```svelte <script> import { hydratable } from 'svelte'; const promises = hydratable('random', () => { return { one: Promise.resolve(1), two: Promise.resolve(2) } }); </script> {await promises.one} {await promises.two} ``` ## CSP `hydratable` adds an inline `<script>` block to the `head` returned from `render`. If you're using [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) (CSP), this script will likely fail to run. You can provide a `nonce` to `render`: ```js /// file: server.js import { render } from 'svelte/server'; import App from './App.svelte'; //cut const nonce = crypto.randomUUID(); const { head, body } = await render(App, { csp: { nonce } }); ``` This will add the `nonce` to the script block, on the assumption that you will later add the same nonce to the CSP header of the document that contains it: ```js /// file: server.js let response = new Response(); let nonce = 'xyz123'; //cut response.headers.set( 'Content-Security-Policy', `script-src 'nonce-${nonce}'` ); ``` It's essential that a `nonce` — which, British slang definition aside, means 'number used once' — is only used when dynamically server rendering an individual response. If instead you are generating static HTML ahead of time, you must use hashes instead: ```js /// file: server.js import { render } from 'svelte/server'; import App from './App.svelte'; //cut const { head, body, hashes } = await render(App, { csp: { hash: true } }); ``` `hashes.script` will be an array of strings like `["sha256-abcd123"]`. As with `nonce`, the hashes should be used in your CSP header: ```js /// file: server.js let response = new Response(); let hashes = { script: ['sha256-xyz123'] }; //cut response.headers.set( 'Content-Security-Policy', `script-src ${hashes.script.map((hash) => `'${hash}'`).join(' ')}` ); ``` We recommend using `nonce` over hash if you can, as `hash` will interfere with streaming SSR in the future.

## docs/svelte/07-misc/index.md

--- title: Misc ---

## docs/svelte/07-misc/01-best-practices.md

--- title: Best practices name: svelte-core-bestpractices description: Guidance on writing fast, robust, modern Svelte code. Load this skill whenever in a Svelte project and asked to write/edit or analyze a Svelte component or module. Covers reactivity, event handling, styling, integration with libraries and more. --- This document outlines some best practices that will help you write fast, robust Svelte apps. It is also available as a `svelte-core-bestpractices` skill for your agents. ## `$state` Only use the `$state` rune for variables that should be _reactive_ — in other words, variables that cause an `$effect`, `$derived` or template expression to update. Everything else can be a normal variable. Objects and arrays (`$state({...})` or `$state([...])`) are made deeply reactive, meaning mutation will trigger updates. This has a trade-off: in exchange for fine-grained reactivity, the objects must be proxied, which has performance overhead. In cases where you're dealing with large objects that are only ever reassigned (rather than mutated), use `$state.raw` instead. This is often the case with API responses, for example. ## `$derived` To compute something from state, use `$derived` rather than `$effect`: ```js // @errors: 2451 let num = 0; //cut // do this let square = $derived(num * num); // don't do this let square; $effect(() => { square = num * num; }); ``` Deriveds are writable — you can assign to them, just like `$state`, except that they will re-evaluate when their expression changes. If the derived expression is an object or array, it will be returned as-is — it is _not_ made deeply reactive. You can, however, use `$state` inside `$derived.by` in the rare cases that you need this. ## `$effect` Effects are an escape hatch and should mostly be avoided. In particular, avoid updating state inside effects. - If you need to sync state to an external library such as D3, it is often neater to use [`{@attach ...}`](@attach) - If you need to run some code in response to user interaction, put the code directly in an event handler or use a [function binding](bind#Function-bindings) as appropriate - If you need to log values for debugging purposes, use [`$inspect`]($inspect) - If you need to observe something external to Svelte, use [`createSubscriber`](svelte-reactivity#createSubscriber) Never wrap the contents of an effect in `if (browser) {...}` or similar — effects do not run on the server. ## `$props` Treat props as though they will change. For example, values that depend on props should usually use `$derived`: ```js // @errors: 2451 let { type } = $props(); // do this let color = $derived(type === 'danger' ? 'red' : 'green'); // don't do this — `color` will not update if `type` changes let color = type === 'danger' ? 'red' : 'green'; ``` ## `$inspect.trace` `$inspect.trace` is a debugging tool for reactivity. If something is not updating properly or running more than it should you can add `$inspect.trace(label)` as the first line of an `$effect` or `$derived.by` (or any function they call) to trace their dependencies and discover which one triggered an update. ## Events Any element attribute starting with `on` is treated as an event listener: ```svelte <button onclick={() => {...}}>click me</button> <button {onclick}>...</button> <button {...props}>...</button> ``` If you need to attach listeners to `window` or `document` you can use `<svelte:window>` and `<svelte:document>`: ```svelte <svelte:window onkeydown={...} /> <svelte:document onvisibilitychange={...} /> ``` Avoid using `onMount` or `$effect` for this. ## Snippets [Snippets](snippet) are a way to define reusable chunks of markup that can be instantiated with the [`{@render ...}`](@render) tag, or passed to components as props. They must be declared within the template. ```svelte {#snippet greeting(name)} <p>hello {name}!</p> {/snippet} {@render greeting('world')} ``` ## Each blocks Prefer to use [keyed each blocks](each#Keyed-each-blocks) — this improves performance by allowing Svelte to surgically insert or remove items rather than updating the DOM belonging to existing items. Avoid destructuring if you need to mutate the item (with something like `bind:value={item.count}`, for example). ## Using JavaScript variables in CSS If you have a JS variable that you want to use inside CSS you can set a CSS custom property with the `style:` directive. ```svelte <div style:--columns={columns}>...</div> ``` You can then reference `var(--columns)` inside the component's `<style>`. ## Styling child components The CSS in a component's `<style>` is scoped to that component. If a parent component needs to control the child's styles, the preferred way is to use CSS custom properties: ```svelte <Child --color="red" /> <h1>Hello</h1> <style> h1 { color: var(--color); } </style> ``` If this impossible (for example, the child component comes from a library) you can use `:global` to override styles: ```svelte <div> <Child /> </div> <style> div :global { h1 { color: red; } } </style> ``` ## Context Consider using context instead of declaring state in a shared module. This will scope the state to the part of the app that needs it, and eliminate the possibility of it leaking between users when server-side rendering. Use `createContext` rather than `setContext` and `getContext`, as it provides type safety. ## Async Svelte If using version 5.36 or higher, you can use [await expressions](await-expressions) and [hydratable](hydratable) to use promises directly inside components. Note that these require the `experimental.async` option to be enabled in `svelte.config.js` as they are not yet considered fully stable. ## Avoid legacy features Always use runes mode for new code, and avoid features that have more modern replacements: - use `$state` instead of implicit reactivity (e.g. `let count = 0; count += 1`) - use `$derived` and `$effect` instead of `$:` assignments and statements (but only use effects when there is no better solution) - use `$props` instead of `export let`, `$$props` and `$$restProps` - use `onclick={...}` instead of `on:click={...}` - use `{#snippet ...}` and `{@render ...}` instead of `<slot>` and `$$slots` and `<svelte:fragment>` - use `<DynamicComponent>` instead of `<svelte:component this={DynamicComponent}>` - use `import Self from './ThisComponent.svelte'` and `<Self>` instead of `<svelte:self>` - use classes with `$state` fields to share reactivity between components, instead of using stores - use `{@attach ...}` instead of `use:action` - use clsx-style arrays and objects in `class` attributes, instead of the `class:` directive

## docs/svelte/07-misc/02-testing.md

--- title: Testing --- 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 component tests with 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](/docs/cli/vitest) either during project creation or later on. To setup Vitest manually, first install it: ```sh npm install -D vitest ``` Then adjust your `vite.config.js`: ```js /// file: vite.config.js 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 }); ``` You can now write unit tests for code inside your `.js/.ts` files: ```js /// file: multiplier.svelte.test.js 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); }); ``` ```js /// file: multiplier.svelte.js /** * @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; } }; } ``` ### 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`: ```js /// file: multiplier.svelte.test.js 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); }); ``` ```js /// file: multiplier.svelte.js /** * @param {() => number} getCount * @param {number} k */ export function multiplier(getCount, k) { return { get value() { return getCount() * k; } }; } ``` If the code being tested uses effects, you need to wrap the test inside `$effect.root`: ```js /// file: logger.svelte.test.js 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).toEqual([0]); count = 1; flushSync(); expect(log).toEqual([0, 1]); }); cleanup(); }); ``` ```js /// file: logger.svelte.js /** * @param {() => any} getValue */ export function logger(getValue) { /** @type {any[]} */ let log = []; $effect(() => { log.push(getValue()); }); return log; } ``` ### Component testing It is possible to test your components in isolation, which allows you to render them in a browser (real or simulated), simulate behavior, and make assertions, without spinning up your whole app. To get started, install jsdom (a library that shims DOM APIs): ```sh npm install -D jsdom ``` Then adjust your `vite.config.js`: ```js /// file: vite.config.js import { defineConfig } from 'vitest/config'; export default defineConfig({ plugins: [ /* ... */ ], test: { // If you are testing components client-side, you need to set up 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: ```js /// file: component.test.js 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: ```js /// file: component.test.js 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). ## Component tests with Storybook [Storybook](https://storybook.js.org) is a tool for developing and documenting UI components, and it can also be used to test your components. They're run with Vitest's browser mode, which renders your components in a real browser for the most realistic testing environment. To get started, first install Storybook ([using Svelte's CLI](/docs/cli/storybook)) in your project via `npx sv add storybook` and choose the recommended configuration that includes testing features. If you're already using Storybook, and for more information on Storybook's testing capabilities, follow the [Storybook testing docs](https://storybook.js.org/docs/writing-tests?renderer=svelte) to get started. You can create stories for component variations and test interactions with the [play function](https://storybook.js.org/docs/writing-tests/interaction-testing?renderer=svelte#writing-interaction-tests), which allows you to simulate behavior and make assertions using the Testing Library and Vitest APIs. Here's an example of two stories that can be tested, one that renders an empty LoginForm component and one that simulates a user filling out the form: ```svelte /// file: LoginForm.stories.svelte <script module> import { defineMeta } from '@storybook/addon-svelte-csf'; import { expect, fn } from 'storybook/test'; import LoginForm from './LoginForm.svelte'; const { Story } = defineMeta({ component: LoginForm, args: { // Pass a mock function to the `onSubmit` prop onSubmit: fn(), } }); </script> <Story name="Empty Form" /> <Story name="Filled Form" play={async ({ args, canvas, userEvent }) => { // Simulate a user filling out the form await userEvent.type(canvas.getByTestId('email'), 'email@provider.com'); await userEvent.type(canvas.getByTestId('password'), 'a-random-password'); await userEvent.click(canvas.getByRole('button')); // Run assertions await expect(args.onSubmit).toHaveBeenCalledTimes(1); await expect(canvas.getByText('You’re in!')).toBeInTheDocument(); }} /> ``` ## End-to-end tests with 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](/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: ```js /// file: playwright.config.js 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. ```js // @errors: 2307 7031 /// file: tests/hello-world.spec.js import { expect, test } from '@playwright/test'; test('home page has expected h1', async ({ page }) => { await page.goto('/'); await expect(page.locator('h1')).toBeVisible(); }); ```

## docs/svelte/07-misc/03-typescript.md

--- title: TypeScript --- 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: ```svelte <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. ```ts /// file: svelte.config.js // @noErrors 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. ```ts /// file: svelte.config.js // @noErrors 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). ## 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 `ES2015` so classes are not compiled to functions - 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. ```svelte <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: ```svelte <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: ```svelte <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`: ```svelte <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. ```ts let count: number = $state(0); ``` If you don't give `$state` an initial value, part of its types will be `undefined`. ```ts // @noErrors // 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: ```ts 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: ```svelte <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" /> ``` To extract the properties from a component, use `ComponentProps`. ```ts 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: ```svelte <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 by augmenting the `svelte/elements` module like this: ```ts /// file: additional-svelte-typings.d.ts import { HTMLButtonAttributes } from 'svelte/elements'; declare module 'svelte/elements' { // add a new element export interface SvelteHTMLElements { 'custom-button': HTMLButtonAttributes; } // add a new global attribute that is available on all html elements export interface HTMLAttributes<T> { globalattribute?: string; } // add a new attribute for button elements export interface HTMLButtonAttributes { veryexperimentalattribute?: string; } } export {}; // ensure this is not an ambient module, else types will be overridden instead of augmented ``` Then make sure that the `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.

## docs/svelte/98-reference/index.md

--- title: Reference ---

## docs/svelte/98-reference/20-svelte.md

--- title: svelte --- ```js // @noErrors import { SvelteComponent, SvelteComponentTyped, afterUpdate, beforeUpdate, createContext, createEventDispatcher, createRawSnippet, flushSync, fork, getAbortSignal, getAllContexts, getContext, hasContext, hydratable, hydrate, mount, onDestroy, onMount, setContext, settled, 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](/docs/svelte/v5-migration-guide#Components-are-no-longer-classes) for more info. <div class="ts-block"> ```dts class SvelteComponent< Props extends Record<string, any> = Record<string, any>, Events extends Record<string, any> = any, Slots extends Record<string, any> = any > {/*…*/} ``` <div class="ts-block-property"> ```dts static element?: typeof HTMLElement; ``` <div class="ts-block-property-details"> The custom element version of the component. Only present if compiled with the `customElement` compiler option </div> </div> <div class="ts-block-property"> ```dts [prop: string]: any; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts constructor(options: ComponentConstructorOptions<Properties<Props, Slots>>); ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag deprecated">deprecated</span> This constructor only exists when using the `asClassComponent` compatibility helper, which is a stop-gap solution. Migrate towards using `mount` instead. See [migration guide](https://svelte.dev/docs/svelte/v5-migration-guide#Components-are-no-longer-classes) for more info. </div> </div> </div> <div class="ts-block-property"> ```dts $destroy(): void; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag deprecated">deprecated</span> 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. </div> </div> </div> <div class="ts-block-property"> ```dts $on<K extends Extract<keyof Events, string>>( type: K, callback: (e: Events[K]) => void ): () => void; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag deprecated">deprecated</span> 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. </div> </div> </div> <div class="ts-block-property"> ```dts $set(props: Partial<Props>): void; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag deprecated">deprecated</span> 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. </div> </div> </div></div> ## SvelteComponentTyped <blockquote class="tag deprecated note"> Use `Component` instead. See [migration guide](/docs/svelte/v5-migration-guide#Components-are-no-longer-classes) for more information. </blockquote> <div class="ts-block"> ```dts 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> {} ``` </div> ## afterUpdate <blockquote class="tag deprecated note"> Use [`$effect`](/docs/svelte/$effect) instead </blockquote> 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. <div class="ts-block"> ```dts function afterUpdate(fn: () => void): void; ``` </div> ## beforeUpdate <blockquote class="tag deprecated note"> Use [`$effect.pre`](/docs/svelte/$effect#$effect.pre) instead </blockquote> 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. <div class="ts-block"> ```dts function beforeUpdate(fn: () => void): void; ``` </div> ## createContext <blockquote class="since note"> Available since 5.40.0 </blockquote> Returns a `[get, set]` pair of functions for working with context in a type-safe way. `get` will throw an error if no parent component called `set`. <div class="ts-block"> ```dts function createContext<T>(): [() => T, (context: T) => T]; ``` </div> ## createEventDispatcher <blockquote class="tag deprecated note"> Use callback props and/or the `$host()` rune instead — see [migration guide](/docs/svelte/v5-migration-guide#Event-changes-Component-events) </blockquote> Creates an event dispatcher that can be used to dispatch [component events](/docs/svelte/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: ```ts 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 }>(); ``` <div class="ts-block"> ```dts function createEventDispatcher< EventMap extends Record<string, any> = any >(): EventDispatcher<EventMap>; ``` </div> ## createRawSnippet Create a snippet programmatically <div class="ts-block"> ```dts function createRawSnippet<Params extends unknown[]>( fn: (...params: Getters<Params>) => { render: () => string; setup?: (element: Element) => void | (() => void); } ): Snippet<Params>; ``` </div> ## flushSync Synchronously flush any pending updates. Returns void if no callback is provided, otherwise returns the result of calling the callback. <div class="ts-block"> ```dts function flushSync<T = void>(fn?: (() => T) | undefined): T; ``` </div> ## fork <blockquote class="since note"> Available since 5.42 </blockquote> Creates a 'fork', in which state changes are evaluated but not applied to the DOM. This is useful for speculatively loading data (for example) when you suspect that the user is about to take some action. Frameworks like SvelteKit can use this to preload data when the user touches or hovers over a link, making any subsequent navigation feel instantaneous. The `fn` parameter is a synchronous function that modifies some state. The state changes will be reverted after the fork is initialised, then reapplied if and when the fork is eventually committed. When it becomes clear that a fork will _not_ be committed (e.g. because the user navigated elsewhere), it must be discarded to avoid leaking memory. <div class="ts-block"> ```dts function fork(fn: () => void): Fork; ``` </div> ## getAbortSignal Returns an [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that aborts when the current [derived](/docs/svelte/$derived) or [effect](/docs/svelte/$effect) re-runs or is destroyed. Must be called while a derived or effect is running. ```svelte <script> import { getAbortSignal } from 'svelte'; let { id } = $props(); async function getData(id) { const response = await fetch(`/items/${id}`, { signal: getAbortSignal() }); return await response.json(); } const data = $derived(await getData(id)); </script> ``` <div class="ts-block"> ```dts function getAbortSignal(): AbortSignal; ``` </div> ## 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. <div class="ts-block"> ```dts function getAllContexts< T extends Map<any, any> = Map<any, any> >(): T; ``` </div> ## getContext Retrieves the context that belongs to the closest parent component with the specified `key`. Must be called during component initialisation. [`createContext`](/docs/svelte/svelte#createContext) is a type-safe alternative. <div class="ts-block"> ```dts function getContext<T>(key: any): T; ``` </div> ## hasContext Checks whether a given `key` has been set in the context of a parent component. Must be called during component initialisation. <div class="ts-block"> ```dts function hasContext(key: any): boolean; ``` </div> ## hydratable <div class="ts-block"> ```dts function hydratable<T>(key: string, fn: () => T): T; ``` </div> ## hydrate Hydrates a component on the given target and returns the exports and potentially the props (if compiled with `accessors: true`) of the component <div class="ts-block"> ```dts 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; transformError?: (error: unknown) => unknown; } : { target: Document | Element | ShadowRoot; props: Props; events?: Record<string, (e: any) => any>; context?: Map<any, any>; intro?: boolean; recover?: boolean; transformError?: (error: unknown) => unknown; } ): Exports; ``` </div> ## 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`. <div class="ts-block"> ```dts function mount< Props extends Record<string, any>, Exports extends Record<string, any> >( component: | ComponentType<SvelteComponent<Props>> | Component<Props, Exports, any>, options: MountOptions<Props> ): Exports; ``` </div> ## 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. <div class="ts-block"> ```dts function onDestroy(fn: () => any): void; ``` </div> ## onMount `onMount`, like [`$effect`](/docs/svelte/$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](/docs/svelte/svelte-server#render). <div class="ts-block"> ```dts function onMount<T>( fn: () => | NotFunction<T> | Promise<NotFunction<T>> | (() => any) ): void; ``` </div> ## 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. [`createContext`](/docs/svelte/svelte#createContext) is a type-safe alternative. <div class="ts-block"> ```dts function setContext<T>(key: any, context: T): T; ``` </div> ## settled <blockquote class="since note"> Available since 5.36 </blockquote> Returns a promise that resolves once any state changes, and asynchronous work resulting from them, have resolved and the DOM has been updated <div class="ts-block"> ```dts function settled(): Promise<void>; ``` </div> ## tick Returns a promise that resolves once any pending state changes have been applied. <div class="ts-block"> ```dts function tick(): Promise<void>; ``` </div> ## unmount Unmounts a component that was previously mounted using `mount` or `hydrate`. Since 5.13.0, if `options.outro` is `true`, [transitions](/docs/svelte/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`). ```js // @errors: 7031 import { mount, unmount } from 'svelte'; import App from './App.svelte'; const app = mount(App, { target: document.body }); // later... unmount(app, { outro: true }); ``` <div class="ts-block"> ```dts function unmount( component: Record<string, any>, options?: | { outro?: boolean; } | undefined ): Promise<void>; ``` </div> ## untrack When used inside a [`$derived`](/docs/svelte/$derived) or [`$effect`](/docs/svelte/$effect), any state read inside `fn` will not be treated as a dependency. ```ts $effect(() => { // this will run when `data` changes, but not when `time` changes save(data, { timestamp: untrack(() => time) }); }); ``` <div class="ts-block"> ```dts function untrack<T>(fn: () => T): T; ``` </div> ## 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`: ```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: ```svelte <script lang="ts"> import { MyComponent } from "component-library"; </script> <MyComponent foo={'bar'} /> ``` <div class="ts-block"> ```dts interface Component< Props extends Record<string, any> = {}, Exports extends Record<string, any> = {}, Bindings extends keyof Props | '' = string > {/*…*/} ``` <div class="ts-block-property"> ```dts ( 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; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - `internal` An internal object used by Svelte. Do not use or modify. - `props` The props passed to the component. </div> </div> </div> <div class="ts-block-property"> ```dts element?: typeof HTMLElement; ``` <div class="ts-block-property-details"> The custom element version of the component. Only present if compiled with the `customElement` compiler option </div> </div></div> ## ComponentConstructorOptions <blockquote class="tag deprecated note"> In Svelte 4, components are classes. In Svelte 5, they are functions. Use `mount` instead to instantiate components. See [migration guide](/docs/svelte/v5-migration-guide#Components-are-no-longer-classes) for more info. </blockquote> <div class="ts-block"> ```dts interface ComponentConstructorOptions< Props extends Record<string, any> = Record<string, any> > {/*…*/} ``` <div class="ts-block-property"> ```dts target: Element | Document | ShadowRoot; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts anchor?: Element; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts props?: Props; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts context?: Map<any, any>; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts hydrate?: boolean; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts intro?: boolean; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts recover?: boolean; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts sync?: boolean; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts idPrefix?: string; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts $$inline?: boolean; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts transformError?: (error: unknown) => unknown; ``` <div class="ts-block-property-details"></div> </div></div> ## ComponentEvents <blockquote class="tag deprecated note"> The new `Component` type does not have a dedicated Events type. Use `ComponentProps` instead. </blockquote> <div class="ts-block"> ```dts type ComponentEvents<Comp extends SvelteComponent> = Comp extends SvelteComponent<any, infer Events> ? Events : never; ``` </div> ## ComponentInternals Internal implementation details that vary between environments <div class="ts-block"> ```dts type ComponentInternals = Branded<{}, 'ComponentInternals'>; ``` </div> ## ComponentProps Convenience type to get the props the given component expects. Example: Ensure a variable contains the props expected by `MyComponent`: ```ts 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' }; ``` Example: A generic function that accepts some component and infers the type of its props: ```ts 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' }); ``` <div class="ts-block"> ```dts type ComponentProps< Comp extends SvelteComponent | Component<any, any> > = Comp extends SvelteComponent<infer Props> ? Props : Comp extends Component<infer Props, any> ? Props : never; ``` </div> ## ComponentType <blockquote class="tag deprecated note"> This type is obsolete when working with the new `Component` type. </blockquote> <div class="ts-block"> ```dts 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; }; ``` </div> ## EventDispatcher <div class="ts-block"> ```dts interface EventDispatcher< EventMap extends Record<string, any> > {/*…*/} ``` <div class="ts-block-property"> ```dts <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; ``` <div class="ts-block-property-details"></div> </div></div> ## Fork <blockquote class="since note"> Available since 5.42 </blockquote> Represents work that is happening off-screen, such as data being preloaded in anticipation of the user navigating <div class="ts-block"> ```dts interface Fork {/*…*/} ``` <div class="ts-block-property"> ```dts commit(): Promise<void>; ``` <div class="ts-block-property-details"> Commit the fork. The promise will resolve once the state change has been applied </div> </div> <div class="ts-block-property"> ```dts discard(): void; ``` <div class="ts-block-property-details"> Discard the fork </div> </div></div> ## MountOptions Defines the options accepted by the `mount()` function. <div class="ts-block"> ```dts 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; /** * A function that transforms errors caught by error boundaries before they are passed to the `failed` snippet. * Defaults to the identity function. */ transformError?: ( error: unknown ) => unknown | Promise<unknown>; } & ({} extends Props ? { /** * Component properties. */ props?: Props; } : { /** * Component properties. */ props: Props; }); ``` </div> ## 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: ```ts let { banner }: { banner: Snippet<[{ text: string }]> } = $props(); ``` You can only call a snippet through the `{@render ...}` tag. See the [snippet documentation](/docs/svelte/snippet) for more info. <div class="ts-block"> ```dts interface Snippet<Parameters extends unknown[] = []> {/*…*/} ``` <div class="ts-block-property"> ```dts ( 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; ``` <div class="ts-block-property-details"></div> </div></div>

## docs/svelte/98-reference/21-svelte-action.md

--- title: svelte/action --- This module provides types for [actions](use), which have been superseded by [attachments](@attach). ## 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: ```ts 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. <div class="ts-block"> ```dts interface Action< Element = HTMLElement, Parameter = undefined, Attributes extends Record<string, any> = Record< never, any > > {/*…*/} ``` <div class="ts-block-property"> ```dts <Node extends Element>( ...args: undefined extends Parameter ? [node: Node, parameter?: Parameter] : [node: Node, parameter: Parameter] ): void | ActionReturn<Parameter, Attributes>; ``` <div class="ts-block-property-details"></div> </div></div> ## 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: ```ts interface Attributes { newprop?: string; 'on:event': (e: CustomEvent<boolean>) => void; } export function myAction(node: HTMLElement, parameter: Parameter): ActionReturn<Parameter, Attributes> { // ... return { update: (updatedParameter) => {...}, destroy: () => {...} }; } ``` <div class="ts-block"> ```dts interface ActionReturn< Parameter = undefined, Attributes extends Record<string, any> = Record< never, any > > {/*…*/} ``` <div class="ts-block-property"> ```dts update?: (parameter: Parameter) => void; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts destroy?: () => void; ``` <div class="ts-block-property-details"></div> </div></div>

## docs/svelte/98-reference/21-svelte-animate.md

--- title: svelte/animate --- ```js // @noErrors 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/). <div class="ts-block"> ```dts function flip( node: Element, { from, to }: { from: DOMRect; to: DOMRect; }, params?: FlipParams ): AnimationConfig; ``` </div> ## AnimationConfig <div class="ts-block"> ```dts interface AnimationConfig {/*…*/} ``` <div class="ts-block-property"> ```dts delay?: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts duration?: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts easing?: (t: number) => number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts css?: (t: number, u: number) => string; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts tick?: (t: number, u: number) => void; ``` <div class="ts-block-property-details"></div> </div></div> ## FlipParams <div class="ts-block"> ```dts interface FlipParams {/*…*/} ``` <div class="ts-block-property"> ```dts delay?: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts duration?: number | ((len: number) => number); ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts easing?: (t: number) => number; ``` <div class="ts-block-property-details"></div> </div></div>

## docs/svelte/98-reference/21-svelte-attachments.md

--- title: svelte/attachments tags: attachments --- ```js // @noErrors import { createAttachmentKey, fromAction } from 'svelte/attachments'; ``` ## createAttachmentKey <blockquote class="since note"> Available since 5.29 </blockquote> 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. ```svelte <script> import { createAttachmentKey } from 'svelte/attachments'; const props = { class: 'cool', onclick: () => alert('clicked'), [createAttachmentKey()]: (node) => { node.textContent = 'attached!'; } }; </script> <button {...props}>click me</button> ``` <div class="ts-block"> ```dts function createAttachmentKey(): symbol; ``` </div> ## fromAction Converts an [action](/docs/svelte/use) into an [attachment](/docs/svelte/@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. ```svelte <div use:foo={bar}>...</div> <div {@attach fromAction(foo, () => bar)}>...</div> ``` <div class="ts-block"> ```dts function fromAction< E extends EventTarget, T extends unknown >( action: | Action<E, T> | ((element: E, arg: T) => void | ActionReturn<T>), fn: () => T ): Attachment<E>; ``` </div> <div class="ts-block"> ```dts function fromAction<E extends EventTarget>( action: | Action<E, void> | ((element: E) => void | ActionReturn<void>) ): Attachment<E>; ``` </div> ## Attachment An [attachment](/docs/svelte/@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`](/docs/svelte/svelte-attachments#createAttachmentKey). <div class="ts-block"> ```dts interface Attachment<T extends EventTarget = Element> {/*…*/} ``` <div class="ts-block-property"> ```dts (element: T): void | (() => void); ``` <div class="ts-block-property-details"></div> </div></div>

## docs/svelte/98-reference/21-svelte-compiler.md

--- title: svelte/compiler --- ```js // @noErrors import { VERSION, compile, compileModule, migrate, parse, parseCss, preprocess, print, walk } from 'svelte/compiler'; ``` ## VERSION The current version, as set in package.json. <div class="ts-block"> ```dts const VERSION: string; ``` </div> ## compile `compile` converts your `.svelte` source code into a JavaScript module that exports a component <div class="ts-block"> ```dts function compile( source: string, options: CompileOptions ): CompileResult; ``` </div> ## compileModule `compileModule` takes your JavaScript source code containing runes, and turns it into a JavaScript module. <div class="ts-block"> ```dts function compileModule( source: string, options: ModuleCompileOptions ): CompileResult; ``` </div> ## 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. <div class="ts-block"> ```dts function migrate( source: string, { filename, use_ts }?: | { filename?: string; use_ts?: boolean; } | undefined ): { code: string; }; ``` </div> ## 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. <div class="ts-block"> ```dts function parse( source: string, options: { filename?: string; modern: true; loose?: boolean; } ): AST.Root; ``` </div> <div class="ts-block"> ```dts function parse( source: string, options?: | { filename?: string; modern?: false; loose?: boolean; } | undefined ): Record<string, any>; ``` </div> ## parseCss The parseCss function parses a CSS stylesheet, returning its abstract syntax tree. <div class="ts-block"> ```dts function parseCss(source: string): AST.CSS.StyleSheetFile; ``` </div> ## 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. <div class="ts-block"> ```dts function preprocess( source: string, preprocessor: PreprocessorGroup | PreprocessorGroup[], options?: | { filename?: string; } | undefined ): Promise<Processed>; ``` </div> ## print `print` converts a Svelte AST node back into Svelte source code. It is primarily intended for tools that parse and transform components using the compiler’s modern AST representation. `print(ast)` requires an AST node produced by parse with modern: true, or any sub-node within that modern AST. The result contains the generated source and a corresponding source map. The output is valid Svelte, but formatting details such as whitespace or quoting may differ from the original. <div class="ts-block"> ```dts function print( ast: AST.SvelteNode, options?: Options | undefined ): { code: string; map: any; }; ``` </div> ## walk <blockquote class="tag deprecated note"> Replace this with `import { walk } from 'estree-walker'` </blockquote> <div class="ts-block"> ```dts function walk(): never; ``` </div> ## AST <div class="ts-block"> ```dts 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; /** Comments found in <script> and {expressions} */ comments: JSComment[]; } 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' | ObjectExpression | undefined; 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 BaseAttribute { 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 BaseAttribute { 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 BaseAttribute { 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 BaseAttribute { 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 BaseAttribute { type: 'OnDirective'; /** The 'x' in `on:x` */ name: string; /** The 'y' in `on:x={y}` */ expression: null | Expression; modifiers: Array< | 'capture' | 'nonpassive' | 'once' | 'passive' | 'preventDefault' | 'self' | 'stopImmediatePropagation' | 'stopPropagation' | 'trusted' >; } /** A `style:` directive */ export interface StyleDirective extends BaseAttribute { 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 BaseAttribute { 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 BaseAttribute { type: 'UseDirective'; /** The 'x' in `use:x` */ name: string; /** The 'y' in `use:x={y}` */ expression: null | Expression; } export interface BaseElement extends BaseNode { name: string; name_loc: SourceLocation; 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 BaseAttribute extends BaseNode { name: string; name_loc: SourceLocation | null; } export interface Attribute extends BaseAttribute { type: 'Attribute'; /** * 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 interface JSComment { type: 'Line' | 'Block'; value: string; start: number; end: number; loc: { start: { line: number; column: number }; end: { line: number; column: number }; }; } 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 | Script; export type { _CSS as CSS }; } ``` </div> ## CompileError <div class="ts-block"> ```dts interface CompileError extends ICompileDiagnostic {} ``` </div> ## CompileOptions <div class="ts-block"> ```dts interface CompileOptions extends ModuleCompileOptions {/*…*/} ``` <div class="ts-block-property"> ```dts name?: string; ``` <div class="ts-block-property-details"> 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` </div> </div> <div class="ts-block-property"> ```dts customElement?: boolean; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `false` </div> If `true`, tells the compiler to generate a custom element constructor instead of a regular Svelte component. </div> </div> <div class="ts-block-property"> ```dts accessors?: boolean; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `false` - <span class="tag deprecated">deprecated</span> This will have no effect in runes mode </div> 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`. </div> </div> <div class="ts-block-property"> ```dts namespace?: Namespace; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `'html'` </div> The namespace of the element; e.g., `"html"`, `"svg"`, `"mathml"`. </div> </div> <div class="ts-block-property"> ```dts immutable?: boolean; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `false` - <span class="tag deprecated">deprecated</span> This will have no effect in runes mode </div> 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. </div> </div> <div class="ts-block-property"> ```dts css?: 'injected' | 'external'; ``` <div class="ts-block-property-details"> - `'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. </div> </div> <div class="ts-block-property"> ```dts cssHash?: CssHashGetter; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `undefined` </div> 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(filename ?? css)}`. </div> </div> <div class="ts-block-property"> ```dts preserveComments?: boolean; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `false` </div> If `true`, your HTML comments will be preserved in the output. By default, they are stripped out. </div> </div> <div class="ts-block-property"> ```dts preserveWhitespace?: boolean; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `false` </div> If `true`, whitespace inside and between elements is kept as you typed it, rather than removed or collapsed to a single space where possible. </div> </div> <div class="ts-block-property"> ```dts fragments?: 'html' | 'tree'; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `'html'` - <span class="tag since">available since</span> v5.33 </div> 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 </div> </div> <div class="ts-block-property"> ```dts runes?: boolean | undefined; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `undefined` </div> 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. </div> </div> <div class="ts-block-property"> ```dts discloseVersion?: boolean; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `true` </div> If `true`, exposes the Svelte major version in the browser by adding it to a `Set` stored in the global `window.__svelte.v`. </div> </div> <div class="ts-block-property"> ```dts compatibility?: {/*…*/} ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag deprecated">deprecated</span> Use these only as a temporary solution before migrating your code </div> <div class="ts-block-property-children"><div class="ts-block-property"> ```dts componentApi?: 4 | 5; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `5` </div> 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 </div> </div></div> </div> </div> <div class="ts-block-property"> ```dts sourcemap?: object | string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `null` </div> An initial sourcemap that will be merged into the final output sourcemap. This is usually the preprocessor sourcemap. </div> </div> <div class="ts-block-property"> ```dts outputFilename?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `null` </div> Used for your JavaScript sourcemap. </div> </div> <div class="ts-block-property"> ```dts cssOutputFilename?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `null` </div> Used for your CSS sourcemap. </div> </div> <div class="ts-block-property"> ```dts hmr?: boolean; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `false` </div> If `true`, compiles components with hot reloading support. </div> </div> <div class="ts-block-property"> ```dts modernAst?: boolean; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `false` </div> 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. </div> </div></div> ## CompileResult The return value of `compile` from `svelte/compiler` <div class="ts-block"> ```dts interface CompileResult {/*…*/} ``` <div class="ts-block-property"> ```dts js: {/*…*/} ``` <div class="ts-block-property-details"> The compiled JavaScript <div class="ts-block-property-children"><div class="ts-block-property"> ```dts code: string; ``` <div class="ts-block-property-details"> The generated code </div> </div> <div class="ts-block-property"> ```dts map: SourceMap; ``` <div class="ts-block-property-details"> A source map </div> </div></div> </div> </div> <div class="ts-block-property"> ```dts css: null | { /** The generated code */ code: string; /** A source map */ map: SourceMap; /** Whether or not the CSS includes global rules */ hasGlobal: boolean; }; ``` <div class="ts-block-property-details"> The compiled CSS </div> </div> <div class="ts-block-property"> ```dts warnings: Warning[]; ``` <div class="ts-block-property-details"> 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 </div> </div> <div class="ts-block-property"> ```dts metadata: {/*…*/} ``` <div class="ts-block-property-details"> Metadata about the compiled component <div class="ts-block-property-children"><div class="ts-block-property"> ```dts runes: boolean; ``` <div class="ts-block-property-details"> Whether the file was compiled in runes mode, either because of an explicit option or inferred from usage. For `compileModule`, this is always `true` </div> </div></div> </div> </div> <div class="ts-block-property"> ```dts ast: any; ``` <div class="ts-block-property-details"> The AST </div> </div></div> ## MarkupPreprocessor A markup preprocessor that takes a string of code and returns a processed version. <div class="ts-block"> ```dts type MarkupPreprocessor = (options: { /** * The whole Svelte file content */ content: string; /** * The filename of the Svelte file */ filename?: string; }) => Processed | void | Promise<Processed | void>; ``` </div> ## ModuleCompileOptions <div class="ts-block"> ```dts interface ModuleCompileOptions {/*…*/} ``` <div class="ts-block-property"> ```dts dev?: boolean; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `false` </div> If `true`, causes extra code to be added that will perform runtime checks and provide debugging information during development. </div> </div> <div class="ts-block-property"> ```dts generate?: 'client' | 'server' | false; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `'client'` </div> 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. </div> </div> <div class="ts-block-property"> ```dts filename?: string; ``` <div class="ts-block-property-details"> Used for debugging hints and sourcemaps. Your bundler plugin will set it automatically. </div> </div> <div class="ts-block-property"> ```dts rootDir?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `process.cwd() on node-like environments, undefined elsewhere` </div> Used for ensuring filenames don't leak filesystem information. Your bundler plugin will set it automatically. </div> </div> <div class="ts-block-property"> ```dts warningFilter?: (warning: Warning) => boolean; ``` <div class="ts-block-property-details"> 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. </div> </div> <div class="ts-block-property"> ```dts experimental?: {/*…*/} ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag since">available since</span> v5.36 </div> Experimental options <div class="ts-block-property-children"><div class="ts-block-property"> ```dts async?: boolean; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag since">available since</span> v5.36 </div> Allow `await` keyword in deriveds, template expressions, and the top level of components </div> </div></div> </div> </div></div> ## Preprocessor A script/style preprocessor that takes a string of code and returns a processed version. <div class="ts-block"> ```dts 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>; ``` </div> ## PreprocessorGroup A preprocessor group is a set of preprocessors that are applied to a Svelte file. <div class="ts-block"> ```dts interface PreprocessorGroup {/*…*/} ``` <div class="ts-block-property"> ```dts name?: string; ``` <div class="ts-block-property-details"> Name of the preprocessor. Will be a required option in the next major version </div> </div> <div class="ts-block-property"> ```dts markup?: MarkupPreprocessor; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts style?: Preprocessor; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts script?: Preprocessor; ``` <div class="ts-block-property-details"></div> </div></div> ## Processed The result of a preprocessor run. If the preprocessor does not return a result, it is assumed that the code is unchanged. <div class="ts-block"> ```dts interface Processed {/*…*/} ``` <div class="ts-block-property"> ```dts code: string; ``` <div class="ts-block-property-details"> The new code </div> </div> <div class="ts-block-property"> ```dts map?: string | object; ``` <div class="ts-block-property-details"> A source map mapping back to the original code </div> </div> <div class="ts-block-property"> ```dts dependencies?: string[]; ``` <div class="ts-block-property-details"> A list of additional files to watch for changes </div> </div> <div class="ts-block-property"> ```dts attributes?: Record<string, string | boolean>; ``` <div class="ts-block-property-details"> Only for script/style preprocessors: The updated attributes to set on the tag. If undefined, attributes stay unchanged. </div> </div> <div class="ts-block-property"> ```dts toString?: () => string; ``` <div class="ts-block-property-details"></div> </div></div> ## Warning <div class="ts-block"> ```dts interface Warning extends ICompileDiagnostic {} ``` </div>

## docs/svelte/98-reference/21-svelte-easing.md

--- title: svelte/easing --- ```js // @noErrors 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 <div class="ts-block"> ```dts function backIn(t: number): number; ``` </div> ## backInOut <div class="ts-block"> ```dts function backInOut(t: number): number; ``` </div> ## backOut <div class="ts-block"> ```dts function backOut(t: number): number; ``` </div> ## bounceIn <div class="ts-block"> ```dts function bounceIn(t: number): number; ``` </div> ## bounceInOut <div class="ts-block"> ```dts function bounceInOut(t: number): number; ``` </div> ## bounceOut <div class="ts-block"> ```dts function bounceOut(t: number): number; ``` </div> ## circIn <div class="ts-block"> ```dts function circIn(t: number): number; ``` </div> ## circInOut <div class="ts-block"> ```dts function circInOut(t: number): number; ``` </div> ## circOut <div class="ts-block"> ```dts function circOut(t: number): number; ``` </div> ## cubicIn <div class="ts-block"> ```dts function cubicIn(t: number): number; ``` </div> ## cubicInOut <div class="ts-block"> ```dts function cubicInOut(t: number): number; ``` </div> ## cubicOut <div class="ts-block"> ```dts function cubicOut(t: number): number; ``` </div> ## elasticIn <div class="ts-block"> ```dts function elasticIn(t: number): number; ``` </div> ## elasticInOut <div class="ts-block"> ```dts function elasticInOut(t: number): number; ``` </div> ## elasticOut <div class="ts-block"> ```dts function elasticOut(t: number): number; ``` </div> ## expoIn <div class="ts-block"> ```dts function expoIn(t: number): number; ``` </div> ## expoInOut <div class="ts-block"> ```dts function expoInOut(t: number): number; ``` </div> ## expoOut <div class="ts-block"> ```dts function expoOut(t: number): number; ``` </div> ## linear <div class="ts-block"> ```dts function linear(t: number): number; ``` </div> ## quadIn <div class="ts-block"> ```dts function quadIn(t: number): number; ``` </div> ## quadInOut <div class="ts-block"> ```dts function quadInOut(t: number): number; ``` </div> ## quadOut <div class="ts-block"> ```dts function quadOut(t: number): number; ``` </div> ## quartIn <div class="ts-block"> ```dts function quartIn(t: number): number; ``` </div> ## quartInOut <div class="ts-block"> ```dts function quartInOut(t: number): number; ``` </div> ## quartOut <div class="ts-block"> ```dts function quartOut(t: number): number; ``` </div> ## quintIn <div class="ts-block"> ```dts function quintIn(t: number): number; ``` </div> ## quintInOut <div class="ts-block"> ```dts function quintInOut(t: number): number; ``` </div> ## quintOut <div class="ts-block"> ```dts function quintOut(t: number): number; ``` </div> ## sineIn <div class="ts-block"> ```dts function sineIn(t: number): number; ``` </div> ## sineInOut <div class="ts-block"> ```dts function sineInOut(t: number): number; ``` </div> ## sineOut <div class="ts-block"> ```dts function sineOut(t: number): number; ``` </div>

## docs/svelte/98-reference/21-svelte-events.md

--- title: svelte/events --- ```js // @noErrors 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 <div class="ts-block"> ```dts function on<Type extends keyof WindowEventMap>( window: Window, type: Type, handler: ( this: Window, event: WindowEventMap[Type] & { currentTarget: Window } ) => any, options?: AddEventListenerOptions | undefined ): () => void; ``` </div> <div class="ts-block"> ```dts function on<Type extends keyof DocumentEventMap>( document: Document, type: Type, handler: ( this: Document, event: DocumentEventMap[Type] & { currentTarget: Document; } ) => any, options?: AddEventListenerOptions | undefined ): () => void; ``` </div> <div class="ts-block"> ```dts function on< Element extends HTMLElement, Type extends keyof HTMLElementEventMap >( element: Element, type: Type, handler: ( this: Element, event: HTMLElementEventMap[Type] & { currentTarget: Element; } ) => any, options?: AddEventListenerOptions | undefined ): () => void; ``` </div> <div class="ts-block"> ```dts function on< Element extends MediaQueryList, Type extends keyof MediaQueryListEventMap >( element: Element, type: Type, handler: ( this: Element, event: MediaQueryListEventMap[Type] & { currentTarget: Element; } ) => any, options?: AddEventListenerOptions | undefined ): () => void; ``` </div> <div class="ts-block"> ```dts function on( element: EventTarget, type: string, handler: EventListener, options?: AddEventListenerOptions | undefined ): () => void; ``` </div>

## docs/svelte/98-reference/21-svelte-motion.md

--- title: svelte/motion --- ```js // @noErrors import { Spring, Tween, prefersReducedMotion, spring, tweened } from 'svelte/motion'; ``` ## Spring <blockquote class="since note"> Available since 5.8.0 </blockquote> 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. ```svelte <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 /> ``` <div class="ts-block"> ```dts class Spring<T> {/*…*/} ``` <div class="ts-block-property"> ```dts constructor(value: T, options?: SpringOpts); ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts static of<U>(fn: () => U, options?: SpringOpts): Spring<U>; ``` <div class="ts-block-property-details"> 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). ```svelte <script> import { Spring } from 'svelte/motion'; let { number } = $props(); const spring = Spring.of(() => number); </script> ``` </div> </div> <div class="ts-block-property"> ```dts set(value: T, options?: SpringUpdateOpts): Promise<void>; ``` <div class="ts-block-property-details"> 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. </div> </div> <div class="ts-block-property"> ```dts damping: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts precision: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts stiffness: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts target: T; ``` <div class="ts-block-property-details"> The end value of the spring. This property only exists on the `Spring` class, not the legacy `spring` store. </div> </div> <div class="ts-block-property"> ```dts get current(): T; ``` <div class="ts-block-property-details"> The current value of the spring. This property only exists on the `Spring` class, not the legacy `spring` store. </div> </div></div> ## Tween <blockquote class="since note"> Available since 5.8.0 </blockquote> 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. ```svelte <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 /> ``` <div class="ts-block"> ```dts class Tween<T> {/*…*/} ``` <div class="ts-block-property"> ```dts static of<U>(fn: () => U, options?: TweenedOptions<U> | undefined): Tween<U>; ``` <div class="ts-block-property-details"> 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). ```svelte <script> import { Tween } from 'svelte/motion'; let { number } = $props(); const tween = Tween.of(() => number); </script> ``` </div> </div> <div class="ts-block-property"> ```dts constructor(value: T, options?: TweenedOptions<T>); ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts set(value: T, options?: TweenedOptions<T> | undefined): Promise<void>; ``` <div class="ts-block-property-details"> 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. </div> </div> <div class="ts-block-property"> ```dts get current(): T; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts set target(v: T); ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts get target(): T; ``` <div class="ts-block-property-details"></div> </div></div> ## prefersReducedMotion <blockquote class="since note"> Available since 5.7.0 </blockquote> A [media query](/docs/svelte/svelte-reactivity#MediaQuery) that matches if the user [prefers reduced motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion). ```svelte <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} ``` <div class="ts-block"> ```dts const prefersReducedMotion: MediaQuery; ``` </div> ## spring <blockquote class="tag deprecated note"> Use [`Spring`](/docs/svelte/svelte-motion#Spring) instead </blockquote> 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. <div class="ts-block"> ```dts function spring<T = any>( value?: T | undefined, opts?: SpringOpts | undefined ): Spring<T>; ``` </div> ## tweened <blockquote class="tag deprecated note"> Use [`Tween`](/docs/svelte/svelte-motion#Tween) instead </blockquote> A tweened store in Svelte is a special type of store that provides smooth transitions between state values over time. <div class="ts-block"> ```dts function tweened<T>( value?: T | undefined, defaults?: TweenedOptions<T> | undefined ): Tweened<T>; ``` </div> ## Spring <div class="ts-block"> ```dts interface Spring<T> extends Readable<T> {/*…*/} ``` <div class="ts-block-property"> ```dts set(new_value: T, opts?: SpringUpdateOpts): Promise<void>; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts update: (fn: Updater<T>, opts?: SpringUpdateOpts) => Promise<void>; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag deprecated">deprecated</span> Only exists on the legacy `spring` store, not the `Spring` class </div> </div> </div> <div class="ts-block-property"> ```dts subscribe(fn: (value: T) => void): Unsubscriber; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag deprecated">deprecated</span> Only exists on the legacy `spring` store, not the `Spring` class </div> </div> </div> <div class="ts-block-property"> ```dts precision: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts damping: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts stiffness: number; ``` <div class="ts-block-property-details"></div> </div></div> ## Tweened <div class="ts-block"> ```dts interface Tweened<T> extends Readable<T> {/*…*/} ``` <div class="ts-block-property"> ```dts set(value: T, opts?: TweenedOptions<T>): Promise<void>; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts update(updater: Updater<T>, opts?: TweenedOptions<T>): Promise<void>; ``` <div class="ts-block-property-details"></div> </div></div>

## docs/svelte/98-reference/21-svelte-reactivity-window.md

--- title: svelte/reactivity/window --- 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. ```svelte <script> import { innerWidth, innerHeight } from 'svelte/reactivity/window'; </script> <p>{innerWidth.current}x{innerHeight.current}</p> ``` ```js // @noErrors import { devicePixelRatio, innerHeight, innerWidth, online, outerHeight, outerWidth, screenLeft, screenTop, scrollX, scrollY } from 'svelte/reactivity/window'; ``` ## devicePixelRatio <blockquote class="since note"> Available since 5.11.0 </blockquote> `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. <div class="ts-block"> ```dts const devicePixelRatio: { get current(): number | undefined; }; ``` </div> ## innerHeight <blockquote class="since note"> Available since 5.11.0 </blockquote> `innerHeight.current` is a reactive view of `window.innerHeight`. On the server it is `undefined`. <div class="ts-block"> ```dts const innerHeight: ReactiveValue<number | undefined>; ``` </div> ## innerWidth <blockquote class="since note"> Available since 5.11.0 </blockquote> `innerWidth.current` is a reactive view of `window.innerWidth`. On the server it is `undefined`. <div class="ts-block"> ```dts const innerWidth: ReactiveValue<number | undefined>; ``` </div> ## online <blockquote class="since note"> Available since 5.11.0 </blockquote> `online.current` is a reactive view of `navigator.onLine`. On the server it is `undefined`. <div class="ts-block"> ```dts const online: ReactiveValue<boolean | undefined>; ``` </div> ## outerHeight <blockquote class="since note"> Available since 5.11.0 </blockquote> `outerHeight.current` is a reactive view of `window.outerHeight`. On the server it is `undefined`. <div class="ts-block"> ```dts const outerHeight: ReactiveValue<number | undefined>; ``` </div> ## outerWidth <blockquote class="since note"> Available since 5.11.0 </blockquote> `outerWidth.current` is a reactive view of `window.outerWidth`. On the server it is `undefined`. <div class="ts-block"> ```dts const outerWidth: ReactiveValue<number | undefined>; ``` </div> ## screenLeft <blockquote class="since note"> Available since 5.11.0 </blockquote> `screenLeft.current` is a reactive view of `window.screenLeft`. It is updated inside a `requestAnimationFrame` callback. On the server it is `undefined`. <div class="ts-block"> ```dts const screenLeft: ReactiveValue<number | undefined>; ``` </div> ## screenTop <blockquote class="since note"> Available since 5.11.0 </blockquote> `screenTop.current` is a reactive view of `window.screenTop`. It is updated inside a `requestAnimationFrame` callback. On the server it is `undefined`. <div class="ts-block"> ```dts const screenTop: ReactiveValue<number | undefined>; ``` </div> ## scrollX <blockquote class="since note"> Available since 5.11.0 </blockquote> `scrollX.current` is a reactive view of `window.scrollX`. On the server it is `undefined`. <div class="ts-block"> ```dts const scrollX: ReactiveValue<number | undefined>; ``` </div> ## scrollY <blockquote class="since note"> Available since 5.11.0 </blockquote> `scrollY.current` is a reactive view of `window.scrollY`. On the server it is `undefined`. <div class="ts-block"> ```dts const scrollY: ReactiveValue<number | undefined>; ``` </div>

## docs/svelte/98-reference/21-svelte-reactivity.md

--- title: svelte/reactivity --- 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. ```js // @noErrors import { MediaQuery, SvelteDate, SvelteMap, SvelteSet, SvelteURL, SvelteURLSearchParams, createSubscriber } from 'svelte/reactivity'; ``` ## MediaQuery <blockquote class="since note"> Available since 5.7.0 </blockquote> 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. ```svelte <script> import { MediaQuery } from 'svelte/reactivity'; const large = new MediaQuery('min-width: 800px'); </script> <h1>{large.current ? 'large screen' : 'small screen'}</h1> ``` <div class="ts-block"> ```dts class MediaQuery extends ReactiveValue<boolean> {/*…*/} ``` <div class="ts-block-property"> ```dts constructor(query: string, fallback?: boolean | undefined); ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - `query` A media query string - `fallback` Fallback value for the server </div> </div> </div></div> ## 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](/docs/svelte/$effect) or [derived](/docs/svelte/$derived) will cause it to be re-evaluated when the value of the date changes. ```svelte <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> ``` <div class="ts-block"> ```dts class SvelteDate extends Date {/*…*/} ``` <div class="ts-block-property"> ```dts constructor(...params: any[]); ``` <div class="ts-block-property-details"></div> </div></div> ## 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](/REMOVED) below) in an [effect](/docs/svelte/$effect) or [derived](/docs/svelte/$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](/docs/svelte/$state#Deep-state). ```svelte <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} ``` <div class="ts-block"> ```dts class SvelteMap<K, V> extends Map<K, V> {/*…*/} ``` <div class="ts-block-property"> ```dts constructor(value?: Iterable<readonly [K, V]> | null | undefined); ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts set(key: K, value: V): this; ``` <div class="ts-block-property-details"></div> </div></div> ## 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](/REMOVED) below) in an [effect](/docs/svelte/$effect) or [derived](/docs/svelte/$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](/docs/svelte/$state#Deep-state). ```svelte <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} ``` <div class="ts-block"> ```dts class SvelteSet<T> extends Set<T> {/*…*/} ``` <div class="ts-block-property"> ```dts constructor(value?: Iterable<T> | null | undefined); ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts add(value: T): this; ``` <div class="ts-block-property-details"></div> </div></div> ## 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](/docs/svelte/$effect) or [derived](/docs/svelte/$derived) will cause it to be re-evaluated as necessary when the URL changes. The `searchParams` property is an instance of [SvelteURLSearchParams](/docs/svelte/svelte-reactivity#SvelteURLSearchParams). [Example](/REMOVED): ```svelte <script> import { SvelteURL } from 'svelte/reactivity'; const url = new SvelteURL('https://example.com/path'); </script> <input bind:value={url.protocol} /> <input bind:value={url.hostname} /> <input bind:value={url.pathname} /> <hr /> <input bind:value={url.href} size="65" /> ``` <div class="ts-block"> ```dts class SvelteURL extends URL {/*…*/} ``` <div class="ts-block-property"> ```dts get searchParams(): SvelteURLSearchParams; ``` <div class="ts-block-property-details"></div> </div></div> ## 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](/REMOVED) below) in an [effect](/docs/svelte/$effect) or [derived](/docs/svelte/$derived) will cause it to be re-evaluated as necessary when the params are updated. ```svelte <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} ``` <div class="ts-block"> ```dts class SvelteURLSearchParams extends URLSearchParams {/*…*/} ``` <div class="ts-block-property"> ```dts [REPLACE](params: URLSearchParams): void; ``` <div class="ts-block-property-details"></div> </div></div> ## createSubscriber <blockquote class="since note"> Available since 5.7.0 </blockquote> Returns a `subscribe` function that integrates external event-based systems with Svelte's reactivity. It's particularly useful for integrating with web APIs like `MediaQuery`, `IntersectionObserver`, or `WebSocket`. If `subscribe` is called inside an effect (including indirectly, for example inside a getter), the `start` callback will be called with an `update` function. Whenever `update` is called, the effect re-runs. If `start` returns a cleanup 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`](/docs/svelte/svelte-reactivity#MediaQuery): ```js // @errors: 7031 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 makes the getter reactive, if read in an effect this.#subscribe(); // Return the current state of the query, whether or not we're in an effect return this.#query.matches; } } ``` <div class="ts-block"> ```dts function createSubscriber( start: (update: () => void) => (() => void) | void ): () => void; ``` </div>

## docs/svelte/98-reference/21-svelte-server.md

--- title: svelte/server --- ```js // @noErrors 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. <div class="ts-block"> ```dts 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; csp?: Csp; transformError?: ( error: unknown ) => unknown | Promise<unknown>; } ] : [ component: Comp extends SvelteComponent<any> ? ComponentType<Comp> : Comp, options: { props: Omit<Props, '$$slots' | '$$events'>; context?: Map<any, any>; idPrefix?: string; csp?: Csp; transformError?: ( error: unknown ) => unknown | Promise<unknown>; } ] ): RenderOutput; ``` </div>

## docs/svelte/98-reference/21-svelte-store.md

--- title: svelte/store --- ```js // @noErrors 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. <div class="ts-block"> ```dts 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>; ``` </div> <div class="ts-block"> ```dts function derived<S extends Stores, T>( stores: S, fn: (values: StoresValues<S>) => T, initial_value?: T | undefined ): Readable<T>; ``` </div> ## fromStore <div class="ts-block"> ```dts function fromStore<V>(store: Writable<V>): { current: V; }; ``` </div> <div class="ts-block"> ```dts function fromStore<V>(store: Readable<V>): { readonly current: V; }; ``` </div> ## get Get the current value from a store by subscribing and immediately unsubscribing. <div class="ts-block"> ```dts function get<T>(store: Readable<T>): T; ``` </div> ## readable Creates a `Readable` store that allows reading by subscription. <div class="ts-block"> ```dts function readable<T>( value?: T | undefined, start?: StartStopNotifier<T> | undefined ): Readable<T>; ``` </div> ## readonly Takes a store and returns a new one derived from the old one that is readable. <div class="ts-block"> ```dts function readonly<T>(store: Readable<T>): Readable<T>; ``` </div> ## toStore <div class="ts-block"> ```dts function toStore<V>( get: () => V, set: (v: V) => void ): Writable<V>; ``` </div> <div class="ts-block"> ```dts function toStore<V>(get: () => V): Readable<V>; ``` </div> ## writable Create a `Writable` store that allows both updating and reading by subscription. <div class="ts-block"> ```dts function writable<T>( value?: T | undefined, start?: StartStopNotifier<T> | undefined ): Writable<T>; ``` </div> ## Readable Readable interface for subscribing. <div class="ts-block"> ```dts interface Readable<T> {/*…*/} ``` <div class="ts-block-property"> ```dts subscribe(this: void, run: Subscriber<T>, invalidate?: () => void): Unsubscriber; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - `run` subscription callback - `invalidate` cleanup callback </div> Subscribe on value changes. </div> </div></div> ## StartStopNotifier Start and stop notification callbacks. This function is called when the first subscriber subscribes. <div class="ts-block"> ```dts type StartStopNotifier<T> = ( set: (value: T) => void, update: (fn: Updater<T>) => void ) => void | (() => void); ``` </div> ## Subscriber Callback to inform of a value updates. <div class="ts-block"> ```dts type Subscriber<T> = (value: T) => void; ``` </div> ## Unsubscriber Unsubscribes from value updates. <div class="ts-block"> ```dts type Unsubscriber = () => void; ``` </div> ## Updater Callback to update a value. <div class="ts-block"> ```dts type Updater<T> = (value: T) => T; ``` </div> ## Writable Writable interface for both updating and subscribing. <div class="ts-block"> ```dts interface Writable<T> extends Readable<T> {/*…*/} ``` <div class="ts-block-property"> ```dts set(this: void, value: T): void; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - `value` to set </div> Set value and inform subscribers. </div> </div> <div class="ts-block-property"> ```dts update(this: void, updater: Updater<T>): void; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - `updater` callback </div> Update value using callback and inform subscribers. </div> </div></div>

## docs/svelte/98-reference/21-svelte-transition.md

--- title: svelte/transition tags: transitions --- ```js // @noErrors import { blur, crossfade, draw, fade, fly, scale, slide } from 'svelte/transition'; ``` ## blur Animates a `blur` filter alongside an element's opacity. <div class="ts-block"> ```dts function blur( node: Element, { delay, duration, easing, amount, opacity }?: BlurParams | undefined ): TransitionConfig; ``` </div> ## crossfade The `crossfade` function creates a pair of [transitions](/docs/svelte/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. <div class="ts-block"> ```dts 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 ]; ``` </div> ## 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>`. <div class="ts-block"> ```dts function draw( node: SVGElement & { getTotalLength(): number; }, { delay, speed, duration, easing }?: DrawParams | undefined ): TransitionConfig; ``` </div> ## 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. <div class="ts-block"> ```dts function fade( node: Element, { delay, duration, easing }?: FadeParams | undefined ): TransitionConfig; ``` </div> ## 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. <div class="ts-block"> ```dts function fly( node: Element, { delay, duration, easing, x, y, opacity }?: FlyParams | undefined ): TransitionConfig; ``` </div> ## 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. <div class="ts-block"> ```dts function scale( node: Element, { delay, duration, easing, start, opacity }?: ScaleParams | undefined ): TransitionConfig; ``` </div> ## slide Slides an element in and out. <div class="ts-block"> ```dts function slide( node: Element, { delay, duration, easing, axis }?: SlideParams | undefined ): TransitionConfig; ``` </div> ## BlurParams <div class="ts-block"> ```dts interface BlurParams {/*…*/} ``` <div class="ts-block-property"> ```dts delay?: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts duration?: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts easing?: EasingFunction; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts amount?: number | string; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts opacity?: number; ``` <div class="ts-block-property-details"></div> </div></div> ## CrossfadeParams <div class="ts-block"> ```dts interface CrossfadeParams {/*…*/} ``` <div class="ts-block-property"> ```dts delay?: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts duration?: number | ((len: number) => number); ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts easing?: EasingFunction; ``` <div class="ts-block-property-details"></div> </div></div> ## DrawParams <div class="ts-block"> ```dts interface DrawParams {/*…*/} ``` <div class="ts-block-property"> ```dts delay?: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts speed?: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts duration?: number | ((len: number) => number); ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts easing?: EasingFunction; ``` <div class="ts-block-property-details"></div> </div></div> ## EasingFunction <div class="ts-block"> ```dts type EasingFunction = (t: number) => number; ``` </div> ## FadeParams <div class="ts-block"> ```dts interface FadeParams {/*…*/} ``` <div class="ts-block-property"> ```dts delay?: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts duration?: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts easing?: EasingFunction; ``` <div class="ts-block-property-details"></div> </div></div> ## FlyParams <div class="ts-block"> ```dts interface FlyParams {/*…*/} ``` <div class="ts-block-property"> ```dts delay?: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts duration?: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts easing?: EasingFunction; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts x?: number | string; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts y?: number | string; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts opacity?: number; ``` <div class="ts-block-property-details"></div> </div></div> ## ScaleParams <div class="ts-block"> ```dts interface ScaleParams {/*…*/} ``` <div class="ts-block-property"> ```dts delay?: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts duration?: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts easing?: EasingFunction; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts start?: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts opacity?: number; ``` <div class="ts-block-property-details"></div> </div></div> ## SlideParams <div class="ts-block"> ```dts interface SlideParams {/*…*/} ``` <div class="ts-block-property"> ```dts delay?: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts duration?: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts easing?: EasingFunction; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts axis?: 'x' | 'y'; ``` <div class="ts-block-property-details"></div> </div></div> ## TransitionConfig <div class="ts-block"> ```dts interface TransitionConfig {/*…*/} ``` <div class="ts-block-property"> ```dts delay?: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts duration?: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts easing?: EasingFunction; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts css?: (t: number, u: number) => string; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts tick?: (t: number, u: number) => void; ``` <div class="ts-block-property-details"></div> </div></div>

Instructions for LLMs: <s>Always use Svelte 5 runes and Svelte 5 syntax. Runes do not need to be imported, they are globals. $state() runes are always declared using `let`, never with `const`. When passing a function to $derived, you must always use $derived.by(() => ...). Error boundaries can only catch errors during component rendering and at the top level of an $effect inside the error boundary. Error boundaries do not catch errors in onclick or other event handlers.</s>