## tutorial/index.md

--- title: Tutorial ---

## tutorial/01-svelte/index.md

--- title: Basic Svelte label: Part 1 scope: { 'prefix': '/src/lib/', 'name': 'src' } focus: /src/lib/App.svelte ---

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

--- title: Introduction scope: { 'prefix': '/src/lib/', 'name': 'src' } focus: /src/lib/App.svelte ---

## tutorial/01-svelte/01-introduction/01-welcome-to-svelte/index.md

--- title: Welcome to Svelte --- Welcome to the Svelte tutorial! This will teach you everything you need to know to easily build web applications of all sizes, with high performance and a small footprint. You can also consult the [API docs](https://svelte.dev/docs) and visit the [playground](https://svelte.dev/playground), or — if you're impatient to start hacking on your machine locally — create a project with `npx sv create`. ## What is Svelte? Svelte is a tool for building web applications. Like other user interface frameworks, it allows you to build your app _declaratively_ out of components that combine markup, styles and behaviours. These components are _compiled_ into small, efficient JavaScript modules that eliminate overhead traditionally associated with UI frameworks. You can build your entire app with Svelte (for example, using an application framework like [SvelteKit](/docs/kit), which this tutorial will cover), or you can add it incrementally to an existing codebase. You can also ship components as standalone packages that work anywhere. ## How to use this tutorial This tutorial is split into four main parts: - [Basic Svelte](/tutorial/svelte/welcome-to-svelte) (you are here) - [Advanced Svelte](/tutorial/svelte/tweens) - [Basic SvelteKit](/tutorial/kit/introducing-sveltekit) - [Advanced SvelteKit](/tutorial/kit/optional-params) Each section will present an exercise designed to illustrate a feature. Later exercises build on the knowledge gained in earlier ones, so it's recommended that you go from start to finish. If necessary, you can navigate via the menu above. If you get stuck, you can click the `solve` button in the top right of the screen. (The `solve` button is disabled on sections like this one that don't include an exercise.) Try not to rely on it too much; you will learn faster by figuring out where to put each suggested code block and manually typing it in to the editor.

## tutorial/01-svelte/01-introduction/02-your-first-component/index.md

--- title: Your first component --- In Svelte, an application is composed from one or more _components_. A component is a reusable self-contained block of code that encapsulates HTML, CSS and JavaScript that belong together, written into a `.svelte` file. The `App.svelte` file, open in the code editor to the right, is a simple component. ## Adding data A component that just renders some static markup isn't very interesting. Let's add some data. First, add a script tag to your component and declare a `name` variable: ```svelte /// file: App.svelte <script> let name = 'Svelte'; </script> <h1>Hello world!</h1> ``` Then, we can refer to `name` in the markup: ```svelte /// file: App.svelte <h1>Hello{name}!</h1> ``` Inside the curly braces, we can put any JavaScript we want. Try changing `name` to `name.toUpperCase()` for a shoutier greeting. ```svelte /// file: App.svelte <h1>Hello {name.toUpperCase()}!</h1> ```

## tutorial/01-svelte/01-introduction/03-dynamic-attributes/index.md

--- title: Dynamic attributes --- Just like you can use curly braces to control text, you can use them to control element attributes. Our image is missing a `src` — let's add one: ```svelte /// file: App.svelte <imgsrc={src}/> ``` That's better. But if you hover over the `<img>` in the editor, Svelte is giving us a warning: ``` `<img>` element should have an alt attribute ``` When building web apps, it's important to make sure that they're _accessible_ to the broadest possible userbase, including people with (for example) impaired vision or motion, or people without powerful hardware or good internet connections. Accessibility (shortened to a11y) isn't always easy to get right, but Svelte will help by warning you if you write inaccessible markup. In this case, we're missing the `alt` attribute that describes the image for people using screenreaders, or people with slow or flaky internet connections that can't download the image. Let's add one: ```svelte /// file: App.svelte <img src={src}alt="A man dances."/> ``` We can use curly braces _inside_ attributes. Try changing it to `"{name} dances."` — remember to declare a `name` variable in the `<script>` block. ## Shorthand attributes It's not uncommon to have an attribute where the name and value are the same, like `src={src}`. Svelte gives us a convenient shorthand for these cases: ```svelte /// file: App.svelte <img{src}alt="{name} dances." /> ```

## tutorial/01-svelte/01-introduction/04-styling/index.md

--- title: Styling --- Just like in HTML, you can add a `<style>` tag to your component. Let's add some styles to the `<p>` element: ```svelte /// file: App.svelte <p>This is a paragraph.</p> <style> p { color: goldenrod; font-family: 'Comic Sans MS', cursive; font-size: 2em; } </style> ``` Importantly, these rules are _scoped to the component_. You won't accidentally change the style of `<p>` elements elsewhere in your app, as we'll see in the next step.

## tutorial/01-svelte/01-introduction/05-nested-components/index.md

--- title: Nested components --- It would be impractical to put your entire app in a single component. Instead, we can import components from other files and include them in our markup. Add a `<script>` tag to the top of `App.svelte` that imports `Nested.svelte`... ```svelte /// file: App.svelte <script> import Nested from './Nested.svelte'; </script> ``` ...and include a `<Nested />` component: ```svelte /// file: App.svelte <p>This is a paragraph.</p> <Nested /> ``` Notice that even though `Nested.svelte` has a `<p>` element, the styles from `App.svelte` don't leak in.

## tutorial/01-svelte/01-introduction/06-html-tags/index.md

--- title: HTML tags --- Ordinarily, strings are inserted as plain text, meaning that characters like `<` and `>` have no special meaning. But sometimes you need to render HTML directly into a component. For example, the words you're reading right now exist in a markdown file that gets included on this page as a blob of HTML. In Svelte, you do this with the special `{@html ...}` tag: ```svelte /// file: App.svelte <p>{@htmlstring}</p> ```

## tutorial/01-svelte/02-reactivity/index.md

--- title: Reactivity scope: { 'prefix': '/src/lib/', 'name': 'src' } focus: /src/lib/App.svelte ---

## tutorial/01-svelte/02-reactivity/01-state/index.md

--- title: State --- At the heart of Svelte is a powerful system of _reactivity_ for keeping the DOM in sync with your application state — for example, in response to an event. Make the `count` declaration reactive by wrapping the value with `$state(...)`: ```js /// file: App.svelte let count =$state(0); ``` This is called a _rune_, and it's how you tell Svelte that `count` isn't an ordinary variable. Runes look like functions, but they're not — when you use Svelte, they're part of the language itself. All that's left is to implement `increment`: ```js /// file: App.svelte function increment() { count += 1; } ```

## tutorial/01-svelte/02-reactivity/02-deep-state/index.md

--- title: Deep state --- As we saw in the previous exercise, state reacts to _reassignments_. But it also reacts to _mutations_ — we call this _deep reactivity_. Make `numbers` a reactive array: ```js /// file: App.svelte let numbers =$state([1, 2, 3, 4]); ``` Now, when we change the array... ```js /// file: App.svelte function addNumber() { numbers[numbers.length] = numbers.length + 1; } ``` ...the component updates. Or better still, we can `push` to the array instead: ```js /// file: App.svelte function addNumber() { numbers.push(numbers.length + 1); } ```

## tutorial/01-svelte/02-reactivity/03-derived-state/index.md

--- title: Derived state --- Often, you will need to _derive_ state from other state. For this, we have the `$derived` rune: ```js /// file: App.svelte let numbers = $state([1, 2, 3, 4]); let total = $derived(numbers.reduce((t, n) => t + n, 0)); ``` We can now use this in our markup: ```svelte /// file: App.svelte <p>{numbers.join(' + ')} ={total}</p> ``` The expression inside the `$derived` declaration will be re-evaluated whenever its dependencies (in this case, just `numbers`) are updated. Unlike normal state, derived state is read-only.

## tutorial/01-svelte/02-reactivity/04-inspecting-state/index.md

--- title: Inspecting state --- It's often useful to be able to track the value of a piece of state as it changes over time. Inside the `addNumber` function, we've added a `console.log` statement. But if you click the button and open the console drawer (using the button to the right of the URL bar), you'll see a warning, and a message saying the message could not be cloned. That's because `numbers` is a reactive [proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy). There are a couple of things we can do. Firstly, we can create a non-reactive _snapshot_ of the state with `$state.snapshot(...)`: ```js /// file: App.svelte function addNumber() { numbers.push(numbers.length + 1); console.log($state.snapshot(numbers)); } ``` Alternatively, we can use the `$inspect` rune to automatically log a snapshot of the state whenever it changes. This code will automatically be stripped out of your production build: ```js /// file: App.svelte function addNumber() { numbers.push(numbers.length + 1); console.log($state.snapshot(numbers)); } $inspect(numbers); ``` You can customise how the information is displayed by using `$inspect(...).with(fn)` — for example, you can use `console.trace` to see where the state change originated from: ```js /// file: App.svelte $inspect(numbers).with(console.trace); ```

## tutorial/01-svelte/02-reactivity/05-effects/index.md

--- title: Effects --- So far we've talked about reactivity in terms of state. But that's only half of the equation — state is only reactive if something is _reacting_ to it, otherwise it's just a sparkling variable. The thing that reacts is called an _effect_. You've already encountered effects — the ones that Svelte creates on your behalf to update the DOM in response to state changes — but you can also create your own with the `$effect` rune. Let's say we want to use `setInterval` to keep track of how long the component has been mounted. Create the effect: ```svelte /// file: App.svelte <script> let elapsed = $state(0); let interval = $state(1000); $effect(() => { setInterval(() => { elapsed += 1; }, interval); }); </script> ``` Click the 'speed up' button a few times and notice that `elapsed` ticks up faster, because we're calling `setInterval` each time `interval` gets smaller. If we then click the 'slow down' button... well, it doesn't work. That's because we're not clearing out the old intervals when the effect updates. We can fix that by returning a cleanup function: ```js /// file: App.svelte $effect(() => { const id =setInterval(() => { elapsed += 1; }, interval); return () => { clearInterval(id); }; }); ``` The cleanup function is called immediately before the effect function re-runs when `interval` changes, and also when the component is destroyed. If the effect function doesn't read any state when it runs, it will only run once, when the component mounts.

## tutorial/01-svelte/02-reactivity/06-universal-reactivity/index.md

--- title: Universal reactivity --- In the preceding exercises, we used runes to add reactivity inside components. But we can also use runes _outside_ components, for example to share some global state. The `<Counter>` components in this exercise are all importing the `counter` object from `shared.js`. But it's a normal object, and as such nothing happens when you click the buttons. Wrap the object in `$state(...)`: ```js /// file: shared.js export const counter =$state({ count: 0 }); ``` This causes an error, because you can't use runes in normal `.js` files, only `.svelte.js` files. Let's fix that — rename the file to `shared.svelte.js`. Then, update the import declaration in `Counter.svelte`: ```svelte /// file: Counter.svelte <script> import { counter } from './shared.svelte.js'; </script> ``` Now, when you click any button, all three update simultaneously.

## tutorial/01-svelte/03-props/index.md

--- title: Props scope: { 'prefix': '/src/lib/', 'name': 'src' } focus: /src/lib/App.svelte ---

## tutorial/01-svelte/03-props/01-declaring-props/index.md

--- title: Declaring props --- So far, we've dealt exclusively with internal state — that is to say, the values are only accessible within a given component. In any real application, you'll need to pass data from one component down to its children. To do that, we need to declare _properties_, generally shortened to 'props'. In Svelte, we do that with the `$props` rune. Edit the `Nested.svelte` component: ```svelte /// file: Nested.svelte <script> let { answer } =$props(); </script> ```

## tutorial/01-svelte/03-props/02-default-values/index.md

--- title: Default values --- We can easily specify default values for props in `Nested.svelte`: ```svelte /// file: Nested.svelte <script> let { answer= 'a mystery'} = $props(); </script> ``` If we now add a second component _without_ an `answer` prop, it will fall back to the default: ```svelte /// file: App.svelte <Nested answer={42}/> <Nested /> ```

## tutorial/01-svelte/03-props/03-spread-props/index.md

--- title: Spread props --- In this exercise, in `App.svelte` we've forgotten to pass the `name` prop expected by `PackageInfo.svelte`, meaning the `<code>` element is empty and the npm link is broken. We _could_ fix it by adding the prop... ```svelte /// file: App.svelte <PackageInfo name={pkg.name} version={pkg.version} description={pkg.description} website={pkg.website} /> ``` ...but since the properties of `pkg` correspond to the component's expected props, we can 'spread' them onto the component instead: ```svelte /// file: App.svelte <PackageInfo{...pkg}/> ``` > > ```js > let { name, ...stuff } = $props(); > ``` > > ...or by skipping [destructuring](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) altogether: > > ```js > let stuff = $props(); > ``` > > ...in which case you can access the properties by their object paths: > > ```js > console.log(stuff.name, stuff.version, stuff.description, stuff.website); > ```

## tutorial/01-svelte/04-logic/index.md

--- title: Logic scope: { 'prefix': '/src/lib/', 'name': 'src' } focus: /src/lib/App.svelte ---

## tutorial/01-svelte/04-logic/01-if-blocks/index.md

--- title: If blocks --- HTML doesn't have a way of expressing _logic_, like conditionals and loops. Svelte does. To conditionally render some markup, we wrap it in an `if` block. Let's add some text that appears when `count` is greater than `10`: ```svelte /// file: App.svelte <button onclick={increment}> Clicked {count} {count === 1 ? 'time' : 'times'} </button> {#if count > 10} <p>{count} is greater than 10</p> {/if} ``` Try it — update the component, and click on the button a few times.

## tutorial/01-svelte/04-logic/02-else-blocks/index.md

--- title: Else blocks --- Just like in JavaScript, an `if` block can have an `else` block: ```svelte /// file: App.svelte {#if count > 10} <p>{count} is greater than 10</p> {:else} <p>{count} is between 0 and 10</p> {/if} ``` `{#...}` opens a block. `{/...}` closes a block. `{:...}` _continues_ a block. Congratulations — you've already learned almost all the syntax Svelte adds to HTML.

## tutorial/01-svelte/04-logic/03-else-if-blocks/index.md

--- title: Else-if blocks --- Multiple conditions can be 'chained' together with `else if`: ```svelte /// file: App.svelte {#if count > 10} <p>{count} is greater than 10</p> {:else if count < 5} <p>{count} is less than 5</p> {:else} <p>{count} is between5and 10</p> {/if} ```

## tutorial/01-svelte/04-logic/04-each-blocks/index.md

--- title: Each blocks --- When building user interfaces you'll often find yourself working with lists of data. In this exercise, we've repeated the `<button>` markup multiple times — changing the colour each time — but there's still more to add. Instead of laboriously copying, pasting and editing, we can get rid of all but the first button, then use an `each` block: ```svelte /// file: App.svelte <div> {#each colors as color} <button style="background: red" aria-label="red" aria-current={selected === 'red'} onclick={() => selected = 'red'} ></button> {/each} </div> ``` Now we need to use the `color` variable in place of `"red"`: ```svelte /// file: App.svelte <div> {#each colors as color} <button style="background:{color}" aria-label={color} aria-current={selected ===color} onclick={() => selected =color} ></button> {/each} </div> ``` You can get the current _index_ as a second argument, like so: ```svelte /// file: App.svelte <div> {#each colors as color,i} <button style="background: {color}" aria-label={color} aria-current={selected === color} onclick={() => selected = color} >{i + 1}</button> {/each} </div> ```

## tutorial/01-svelte/04-logic/05-keyed-each-blocks/index.md

--- title: Keyed each blocks --- By default, when you modify the value of an `each` block, it will add and remove DOM nodes at the _end_ of the block, and update any values that have changed. That might not be what you want. It's easier to show why than to explain. Inside `Thing.svelte`, `name` is a dynamic prop but `emoji` is a constant. Click the 'Remove first thing' button a few times, and notice what happens: 1. It removes the last component. 2. It then updates the `name` value in the remaining DOM nodes, but not the emoji. One way to fix it would be to make `emoji` a [`$derived`](derived-state) value. But it makes more sense to remove the first `<Thing>` component altogether than to remove the _last_ one and update all the others. To do that, we specify a unique _key_ for each iteration of the `each` block: ```svelte /// file: App.svelte {#each things as thing (thing.id)} <Thing name={thing.name}/> {/each} ```

## tutorial/01-svelte/04-logic/06-await-blocks/index.md

--- title: Await blocks --- Most web applications have to deal with asynchronous data at some point. Svelte makes it easy to _await_ the value of [promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises) directly in your markup: ```svelte /// file: App.svelte {#await promise} <p>...rolling</p> {:then number} <p>you rolled a {number}!</p> {:catch error} <p style="color: red">{error.message}</p> {/await} ``` If you know that your promise can't reject, you can omit the `catch` block. You can also omit the first block if you don't want to show anything until the promise resolves: ```svelte {#await promise then number} <p>you rolled a {number}!</p> {/await} ```

## tutorial/01-svelte/05-events/index.md

--- title: Events scope: { 'prefix': '/src/lib/', 'name': 'src' } focus: /src/lib/App.svelte ---

## tutorial/01-svelte/05-events/01-dom-events/index.md

--- title: DOM events --- As we've briefly seen already, you can listen to any DOM event on an element (such as click or [pointermove](https://developer.mozilla.org/en-US/docs/Web/API/Element/pointermove_event)) with an `on<name>` function: ```svelte /// file: App.svelte <divonpointermove={onpointermove}> The pointer is at {Math.round(m.x)} x {Math.round(m.y)} </div> ``` Like with any other property where the name matches the value, we can use the short form: ```svelte /// file: App.svelte <div{onpointermove}> The pointer is at {Math.round(m.x)} x {Math.round(m.y)} </div> ```

## tutorial/01-svelte/05-events/02-inline-handlers/index.md

--- title: Inline handlers --- You can also declare event handlers inline: ```svelte /// file: App.svelte <script> let m = $state({ x: 0, y: 0 }); function onpointermove(event) { m.x = event.clientX; m.y = event.clientY; } </script> <div onpointermove={(event) => { m.x = event.clientX; m.y = event.clientY; }} > The pointer is at {m.x} x {m.y} </div> ```

## tutorial/01-svelte/05-events/03-capturing/index.md

--- title: Capturing --- Normally, event handlers run during the [_bubbling_](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Event_bubbling) phase. Notice what happens if you type something into the `<input>` in this example — the inner handler runs first, as the event 'bubbles' from the target up to the document, followed by the outer handler. Sometimes, you want handlers to run during the _capture_ phase instead. Add `capture` to the end of the event name: ```svelte /// file: App.svelte <div onkeydowncapture={(e) => alert(`<div> ${e.key}`)} role="presentation"> <input onkeydowncapture={(e) => alert(`<input> ${e.key}`)} /> </div> ``` Now, the relative order is reversed. If both capturing and non-capturing handlers exist for a given event, the capturing handlers will run first.

## tutorial/01-svelte/05-events/04-component-events/index.md

--- title: Component events --- You can pass event handlers to components like any other prop. In `Stepper.svelte`, add `increment` and `decrement` props... ```svelte /// file: Stepper.svelte <script> let {increment, decrement} = $props(); </script> ``` ...and wire them up: ```svelte /// file: Stepper.svelte <buttononclick={decrement}>-1</button> <buttononclick={increment}>+1</button> ``` In `App.svelte`, define the handlers: ```svelte <Stepper increment={() => value += 1} decrement={() => value -= 1} /> ```

## tutorial/01-svelte/05-events/05-spreading-events/index.md

--- title: Spreading events --- We can also [spread](spread-props) event handlers directly onto elements. Here, we've defined an `onclick` handler in `App.svelte` — all we need to do is pass the props to the `<button>` in `BigRedButton.svelte`: ```svelte /// file: BigRedButton.svelte <button{...props}> Push </button> ```

## tutorial/01-svelte/06-bindings/index.md

--- title: Bindings scope: { 'prefix': '/src/lib/', 'name': 'src' } focus: /src/lib/App.svelte ---

## tutorial/01-svelte/06-bindings/01-text-inputs/index.md

--- title: Text inputs --- As a general rule, data flow in Svelte is _top down_ — a parent component can set props on a child component, and a component can set attributes on an element, but not the other way around. Sometimes it's useful to break that rule. Take the case of the `<input>` element in this component — we _could_ add an `oninput` event handler that sets the value of `name` to `event.target.value`, but it's a bit... boilerplatey. It gets even worse with other form elements, as we'll see. Instead, we can use the `bind:value` directive: ```svelte /// file: App.svelte <inputbind:value={name}> ``` This means that not only will changes to the value of `name` update the input value, but changes to the input value will update `name`.

## tutorial/01-svelte/06-bindings/02-numeric-inputs/index.md

--- title: Numeric inputs --- In the DOM, every input value is a string. That's unhelpful when you're dealing with numeric inputs — `type="number"` and `type="range"` — as it means you have to remember to coerce `input.value` before using it. With `bind:value`, Svelte takes care of it for you: ```svelte /// file: App.svelte <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> ```

## tutorial/01-svelte/06-bindings/03-checkbox-inputs/index.md

--- title: Checkbox inputs --- Checkboxes are used for toggling between states. Instead of binding to `input.value`, we bind to `input.checked`: ```svelte /// file: App.svelte <input type="checkbox"bind:checked={yes}> ```

## tutorial/01-svelte/06-bindings/04-select-bindings/index.md

--- title: Select bindings --- We can also use `bind:value` with `<select>` elements: ```svelte /// file: App.svelte <select bind:value={selected} onchange={() => answer = ''} > ``` Note that the `<option>` values are objects rather than strings. Svelte doesn't mind.

## tutorial/01-svelte/06-bindings/05-group-inputs/index.md

--- title: Group inputs --- If you have multiple `type="radio"` or `type="checkbox"` inputs relating to the same value, you can use `bind:group` along with the `value` attribute. Radio inputs in the same group are mutually exclusive; checkbox inputs in the same group form an array of selected values. Add `bind:group={scoops}` to the radio inputs... ```svelte /// file: App.svelte <input type="radio" name="scoops" value={number} bind:group={scoops} /> ``` ...and `bind:group={flavours}` to the checkbox inputs: ```svelte /// file: App.svelte <input type="checkbox" name="flavours" value={flavour} bind:group={flavours} /> ```

## tutorial/01-svelte/06-bindings/06-multiple-select-bindings/index.md

--- title: Select multiple --- A `<select>` element can have a `multiple` attribute, in which case it will populate an array rather than selecting a single value. Replace the checkboxes with a `<select multiple>`: ```svelte /// file: App.svelte <h2>Flavours</h2> <select multiple bind:value={flavours}> {#each ['cookies and cream', 'mint choc chip', 'raspberry ripple'] as flavour} <option>{flavour}</option> {/each} </select> ``` Note that we're able to omit the `value` attribute on the `<option>`, since the value is identical to the element's contents.

## tutorial/01-svelte/06-bindings/07-textarea-inputs/index.md

--- title: Textarea inputs --- The `<textarea>` element behaves similarly to a text input in Svelte — use `bind:value`: ```svelte /// file: App.svelte <textareabind:value={value}></textarea> ``` In cases like these, where the names match, we can also use a shorthand form: ```svelte /// file: App.svelte <textareabind:value></textarea> ``` This applies to all bindings, not just `<textarea>` bindings.

## tutorial/01-svelte/07-classes-and-styles/index.md

--- title: Classes and styles scope: { 'prefix': '/src/lib/', 'name': 'src' } focus: /src/lib/App.svelte ---

## tutorial/01-svelte/07-classes-and-styles/01-classes/index.md

--- title: The class directive --- Like any other attribute, you can specify classes with a JavaScript attribute. Here, we could add a `flipped` class to the card: ```svelte /// file: App.svelte <button class="card {flipped ? 'flipped' : ''}" onclick={() => flipped = !flipped} > ``` This works as expected — if you click on the card now, it'll flip. We can make it nicer though. Adding or removing a class based on some condition is such a common pattern in UI development that Svelte includes a special directive to simplify it: ```svelte /// file: App.svelte <button class="card" class:flipped={flipped} onclick={() => flipped = !flipped} > ``` This directive means 'add the `flipped` class whenever `flipped` is truthy'.

## tutorial/01-svelte/07-classes-and-styles/02-class-shorthand/index.md

--- title: Shorthand class directive --- Often, the name of the class will be the same as the name of the value it depends on: ```svelte <button class="card" class:flipped={flipped} onclick={() => flipped = !flipped} > ``` In those cases we can use a shorthand form: ```svelte /// file: App.svelte <button class="card" class:flipped onclick={() => flipped = !flipped} > ```

## tutorial/01-svelte/07-classes-and-styles/03-styles/index.md

--- title: The style directive --- As with `class`, you can write your inline `style` attributes literally, because Svelte is really just HTML with fancy bits: ```svelte /// file: App.svelte <button class="card" style="transform: {flipped ? 'rotateY(0)' : ''}; --bg-1: palegoldenrod; --bg-2: black; --bg-3: goldenrod" onclick={() => flipped = !flipped} > ``` When you have a lot of styles, it can start to look a bit wacky. We can tidy things up by using the `style:` directive: ```svelte /// file: App.svelte <button class="card" style:transform={flipped ? 'rotateY(0)' : ''} style:--bg-1="palegoldenrod" style:--bg-2="black" style:--bg-3="goldenrod" onclick={() => flipped = !flipped} > ```

## tutorial/01-svelte/07-classes-and-styles/04-component-styles/index.md

--- title: Component styles --- Often, you need to influence the styles inside a child component. Perhaps we want to make these boxes red, green and blue. One way to do this is with the `:global` CSS modifier, which allows you to indiscriminately target elements inside other components: ```svelte /// file: App.svelte <style> .boxes :global(.box:nth-child(1)) { background-color: red; } .boxes :global(.box:nth-child(2)) { background-color: green; } .boxes :global(.box:nth-child(3)) { background-color: blue; } </style> ``` But there are lots of reasons _not_ to do that. For one thing, it's extremely verbose. For another, it's brittle — any changes to the implementation details of `Box.svelte` could break the selector. Most of all though, it's rude. Components should be able to decide for themselves which styles can be controlled from 'outside', in the same way they decide which variables are exposed as props. `:global` should be used as an escape hatch — a last resort. Inside `Box.svelte`, change `background-color` so that it is determined by a [CSS custom property](https://developer.mozilla.org/en-US/docs/Web/CSS/--*): ```svelte /// file: Box.svelte <style> .box { width: 5em; height: 5em; border-radius: 0.5em; margin: 0 0 1em 0; background-color:var(--color, #ddd); } </style> ``` Any parent element (such as `<div class="boxes">`) can set the value of `--color`, but we can also set it on individual components: ```svelte /// file: App.svelte <div class="boxes"> <Box--color="red"/> <Box--color="green"/> <Box--color="blue"/> </div> ``` The values can be dynamic, like any other attribute. > > ```svelte > <svelte-css-wrapper style="display: contents; --color: red;"> > > </svelte-css-wrapper> > ``` > > Because of `display: contents` this won't affect your layout, but the extra element _can_ affect selectors like `.parent > .child`.

## tutorial/01-svelte/08-actions/index.md

--- title: Actions scope: { 'prefix': '/src/lib/', 'name': 'src' } focus: /src/lib/App.svelte ---

## tutorial/01-svelte/08-actions/01-actions/index.md

--- title: The use directive --- Actions are essentially element-level lifecycle functions. They're useful for things like: - interfacing with third-party libraries - lazy-loaded images - tooltips - adding custom event handlers In this app, you can scribble on the `<canvas>`, and change colours and brush size via the menu. But if you open the menu and cycle through the options with the Tab key, you'll soon find that the focus isn't _trapped_ inside the modal. We can fix that with an action. Import `trapFocus` from `actions.svelte.js`... ```svelte /// file: App.svelte <script> import Canvas from './Canvas.svelte'; import { trapFocus } from './actions.svelte.js'; const colors = ['red', 'orange', 'yellow', 'green', 'blue', 'indigo', 'violet', 'white', 'black']; let selected = $state(colors[0]); let size = $state(10); let showMenu = $state(true); </script> ``` ...then add it to the menu with the `use:` directive: ```svelte /// file: App.svelte <div class="menu"use:trapFocus> ``` Let's take a look at the `trapFocus` function in `actions.svelte.js`. An action function is called with a `node` — the `<div class="menu">` in our case — when the node is mounted to the DOM. Inside the action, we have an [effect](effects). First, we need to add an event listener that intercepts Tab key presses: ```js /// file: actions.svelte.js $effect(() => { focusable()[0]?.focus(); node.addEventListener('keydown', handleKeydown); }); ``` Second, we need to do some cleanup when the node is unmounted — removing the event listener, and restoring focus to where it was before the element mounted: ```js /// file: actions.svelte.js $effect(() => { focusable()[0]?.focus(); node.addEventListener('keydown', handleKeydown); return () => { node.removeEventListener('keydown', handleKeydown); previous?.focus(); }; }); ``` Now, when you open the menu, you can cycle through the options with the Tab key.

## tutorial/01-svelte/08-actions/02-adding-parameters-to-actions/index.md

--- title: Adding parameters --- Like transitions and animations, an action can take an argument, which the action function will be called with alongside the element it belongs to. In this exercise, we want to add a tooltip to the `<button>` using the [`Tippy.js`](https://atomiks.github.io/tippyjs/) library. The action is already wired up with `use:tooltip`, but if you hover over the button (or focus it with the keyboard) the tooltip contains no content. First, the action needs to accept a function that returns some options to pass to Tippy: ```js /// file: App.svelte function tooltip(node,fn) { $effect(() => { const tooltip = tippy(node,fn()); return tooltip.destroy; }); } ``` Then, we need to pass the options into the action: ```svelte /// file: App.svelte <button use:tooltip={() => ({ content })}> Hover me </button> ```

## tutorial/01-svelte/09-transitions/index.md

--- title: Transitions scope: { 'prefix': '/src/lib/', 'name': 'src' } focus: /src/lib/App.svelte ---

## tutorial/01-svelte/09-transitions/01-transition/index.md

--- title: The transition directive --- We can make more appealing user interfaces by gracefully transitioning elements into and out of the DOM. Svelte makes this very easy with the `transition` directive. First, import the `fade` function from `svelte/transition`... ```svelte /// file: App.svelte <script> import { fade } from 'svelte/transition'; let visible = $state(true); </script> ``` ...then add it to the `<p>` element: ```svelte /// file: App.svelte <ptransition:fade> Fades in and out </p> ```

## tutorial/01-svelte/09-transitions/02-adding-parameters-to-transitions/index.md

--- title: Adding parameters --- Transition functions can accept parameters. Replace the `fade` transition with `fly`... ```svelte /// file: App.svelte <script> import {fly} from 'svelte/transition'; let visible = $state(true); </script> ``` ...and apply it to the `<p>` along with some options: ```svelte /// file: App.svelte <p transition:fly={{ y: 200, duration: 2000 }}> Fliesin and out </p> ``` Note that the transition is _reversible_ — if you toggle the checkbox while the transition is ongoing, it transitions from the current point, rather than the beginning or the end.

## tutorial/01-svelte/09-transitions/03-in-and-out/index.md

--- title: In and out --- Instead of the `transition` directive, an element can have an `in` or an `out` directive, or both together. Import `fade` alongside `fly`... ```js /// file: App.svelte import {fade, fly } from 'svelte/transition'; ``` ...then replace the `transition` directive with separate `in` and `out` directives: ```svelte /// file: App.svelte <pin:fly={{ y: 200, duration: 2000 }}out:fade> Flies in,fades out </p> ``` In this case, the transitions are _not_ reversed.

## tutorial/01-svelte/09-transitions/04-custom-css-transitions/index.md

--- title: Custom CSS transitions --- The `svelte/transition` module has a handful of built-in transitions, but it's very easy to create your own. By way of example, this is the source of the `fade` transition: ```js function fade(node, { delay = 0, duration = 400 }) { const o = +getComputedStyle(node).opacity; return { delay, duration, css: (t) => `opacity: ${t * o}` }; } ``` The function takes two arguments — the node to which the transition is applied, and any parameters that were passed in — and returns a transition object which can have the following properties: - `delay` — milliseconds before the transition begins - `duration` — length of the transition in milliseconds - `easing` — a `p => t` easing function (see the chapter on [tweening](/tutorial/svelte/tweens)) - `css` — a `(t, u) => css` function, where `u === 1 - t` - `tick` — a `(t, u) => {...}` function that has some effect on the node The `t` value is `0` at the beginning of an intro or the end of an outro, and `1` at the end of an intro or beginning of an outro. Most of the time you should return the `css` property and _not_ the `tick` property, as CSS animations run off the main thread to prevent jank where possible. Svelte 'simulates' the transition and constructs a CSS animation, then lets it run. For example, the `fade` transition generates a CSS animation somewhat like this: ```css 0% { opacity: 0 } 10% { opacity: 0.1 } 20% { opacity: 0.2 } /* ... */ 100% { opacity: 1 } ``` We can get a lot more creative though. Let's make something truly gratuitous: ```svelte /// file: App.svelte <script> import { fade } from 'svelte/transition'; import { elasticOut } from 'svelte/easing'; let visible = $state(true); function spin(node, { duration }) { return { duration, css: t =>{ const eased = elasticOut(t); return ` transform: scale(${eased}) rotate(${eased * 1080}deg); color: hsl( ${Math.trunc(t * 360)}, ${Math.min(100, 1000 * (1 - t))}%, ${Math.min(50, 500 * (1 - t))}% );` } }; } </script> ``` Remember: with great power comes great responsibility.

## tutorial/01-svelte/09-transitions/05-custom-js-transitions/index.md

--- title: Custom JS transitions --- While you should generally use CSS for transitions as much as possible, there are some effects that can't be achieved without JavaScript, such as a typewriter effect: ```js /// file: App.svelte 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 = Math.trunc(text.length * t); node.textContent = text.slice(0, i); } }; } ```

## tutorial/01-svelte/09-transitions/06-transition-events/index.md

--- title: Transition events --- It can be useful to know when transitions are beginning and ending. Svelte dispatches events that you can listen to like any other DOM event: ```svelte /// file: App.svelte <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> ```

## tutorial/01-svelte/09-transitions/07-global-transitions/index.md

--- title: Global transitions --- Ordinarily, transitions will only play on elements when their direct containing block is added or destroyed. In the example here, toggling the visibility of the entire list does not apply transitions to individual list elements. Instead, we'd like transitions to not only play when individual items are added and removed with the slider but also when we toggle the checkbox. We can achieve this with a _global_ transition, which plays when _any_ block containing the transitions is added or removed: ```svelte /// file: App.svelte <div transition:slide|global> {item} </div> ```

## tutorial/01-svelte/09-transitions/08-key-blocks/index.md

--- title: Key blocks --- Key blocks destroy and recreate their contents when the value of an expression changes. This is useful if you want an element to play its transition whenever a value changes instead of only when the element enters or leaves the DOM. Here, for example, we'd like to play the `typewriter` transition from `transition.js` whenever the loading message, i.e. `i` changes. Wrap the `<p>` element in a key block: ```svelte /// file: App.svelte {#key i} <p in:typewriter={{ speed: 10 }}> {messages[i] || ''} </p> {/key} ```

## tutorial/02-advanced-svelte/index.md

--- title: Advanced Svelte label: Part 2 scope: { 'prefix': '/src/lib/', 'name': 'src' } focus: /src/lib/App.svelte ---

## tutorial/02-advanced-svelte/01-advanced-reactivity/index.md

--- title: Advanced reactivity scope: { 'prefix': '/src/lib/', 'name': 'src' } focus: /src/lib/App.svelte ---

## tutorial/02-advanced-svelte/01-advanced-reactivity/01-raw-state/index.md

--- title: Raw state --- In previous exercises, we learned that state is [deeply reactive](deep-state) — if you (for example) change a property of an object, or push to an array, it will cause the UI to update. This works by creating a [proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) that intercepts reads and writes. Occasionally, that's not what you want. If you're not changing individual properties, or if it's important to maintain referential equality, then you can use _raw state_ instead. In this example, we have a chart of Svelte's steadily increasing stock price. We want the chart to update when new data comes in, which we could achieve by turning `data` into state... ```js /// file: App.svelte let data =$state(poll()); ``` ...but there's no need to make it deeply reactive when it will be discarded a few milliseconds later. Instead, use `$state.raw`: ```js /// file: App.svelte let data =$state.raw(poll()); ```

## tutorial/02-advanced-svelte/01-advanced-reactivity/02-reactive-classes/index.md

--- title: Reactive classes --- It's not just variables that can be made reactive — in Svelte, we can also make properties of classes reactive. Let's make the `width` and `height` properties of our `Box` class reactive: ```js /// file: App.svelte class Box { width =$state(0); height =$state(0); area = 0; // ... } ``` Now, when we interact with the range inputs or click the 'embiggen' button, the box reacts. We can also use `$derived`, so that `box.area` updates reactively: ```js /// file: App.svelte class Box { width = $state(0); height = $state(0); area =$derived(this.width * this.height); // ... } ```

## tutorial/02-advanced-svelte/01-advanced-reactivity/03-getters-and-setters/index.md

--- title: Getters and setters --- Classes are particularly useful when you need to validate data. In the case of this `Box` class, it shouldn't be possible to keep embiggening past the maximum allowed by the sliders, but that's exactly what happens. We can fix that by replacing `width` and `height` with _getters_ and _setters_, otherwise known as _accessors_. First, convert them to [private properties](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Private_properties): ```js /// file: App.svelte class Box { #width= $state(0); #height= $state(0); area = $derived(this.#width* this.#height); constructor(width, height) { this.#width= width; this.#height= height; } // ... } ``` Then, create some getters and setters: ```js /// file: App.svelte class Box { // ... get width() { return this.#width; } get height() { return this.#height; } set width(value) { this.#width = value; } set height(value) { this.#height = value; } embiggen(amount) { this.width += amount; this.height += amount; } } ``` Finally, add the validation to the setters: ```js /// file: App.svelte set width(value) { this.#width =Math.max(0, Math.min(MAX_SIZE, value)); } set height(value) { this.#height =Math.max(0, Math.min(MAX_SIZE, value)); } ``` It's now impossible to increase the box size past safe limits, whether through the `bind:value` on the range inputs, or the `embiggen` method, no matter how hard you press the button.

## tutorial/02-advanced-svelte/01-advanced-reactivity/04-reactive-builtins/index.md

--- title: Reactive built-ins --- Svelte ships with several reactive classes that you can use in place of JavaScript built-in objects — namely `Map`, `Set`, `Date`, `URL` and `URLSearchParams`. In this exercise, we _could_ declare `date` using `$state(new Date())` and reassign it inside the `setInterval`. But a nicer alternative is to use `SvelteDate` from [`svelte/reactivity`](/docs/svelte/svelte-reactivity): ```svelte /// file: App.svelte <script> import { SvelteDate } from 'svelte/reactivity'; let date = newSvelteDate(); // ... </script> ```

## tutorial/02-advanced-svelte/01-advanced-reactivity/05-stores/index.md

--- title: Stores --- Prior to the introduction of runes in Svelte 5, stores were the idiomatic way to handle reactive state outside components. That's no longer the case, but you'll still encounter stores when using Svelte (including in SvelteKit, for now), so it's worth knowing how to use them. Let's revisit the example from the [universal reactivity](universal-reactivity) exercise, but this time implement the shared state using a store. In `shared.js` we're currently exporting `count`, which is a number. Turn it into a writable store: ```js /// file: shared.js import { writable } from 'svelte/store'; export const count =writable(0); ``` To reference the value of the store, we prefix it with a `$` symbol. In `Counter.svelte`, update the text inside the `<button>` so that it no longer says `[object Object]`: ```svelte /// file: Counter.svelte <button onclick={() => {}}> clicks: {$count} </button> ``` Finally, add the event handler. Because this is a writable store, we can update the value programmatically using its `set` or `update` method... ```js count.update((n) => n + 1); ``` ...but since we're in a component we can continue using the `$` prefix: ```svelte /// file: Counter.svelte <button onclick={() =>$count += 1}> clicks: {$count} </button> ```

## tutorial/02-advanced-svelte/02-snippets/index.md

--- title: Reusing content scope: { 'prefix': '/src/lib/', 'name': 'src' } focus: /src/lib/App.svelte ---

## tutorial/02-advanced-svelte/02-snippets/01-snippets-and-render-tags/index.md

--- title: Snippets and render tags --- Snippets allow you to reuse content within a component, without extracting it out into a separate file. In this exercise, we're creating a table of the [three wise monkeys](https://en.wikipedia.org/wiki/Three_wise_monkeys), along with their unicode escape sequences and HTML entities. So far, we have but a single monkey. We could duplicate the markup, of course. Or we could create an array of `{ emoji, description }` objects and pass it into an `{#each ...}` block. But a neater solution is to encapsulate the markup in a reusable block. Begin by _declaring a snippet_: ```svelte /// file: App.svelte {#snippet monkey()} <tr> <td>{emoji}</td> <td>{description}</td> <td>\u{emoji.charCodeAt(0).toString(16)}\u{emoji.charCodeAt(1).toString(16)}</td> <td>&amp#{emoji.codePointAt(0)}</td> </tr> {/snippet} ``` The monkey is no longer visible until we _render_ it. Let's do that: ```svelte /// file: App.svelte <tbody> {#snippet monkey()}...{/snippet} {@render monkey()} </tbody> ``` Before we can use the snippet for the rest of our monkeys, we need to pass data into the snippet. Snippets can have zero or more parameters: ```svelte /// file: App.svelte <tbody> {#snippet monkey(emoji, description)}...{/snippet} {@render monkey('🙈', 'see no evil')} </tbody> ``` Add the rest of the monkeys: - `'🙈', 'see no evil'` - `'🙉', 'hear no evil'` - `'🙊', 'speak no evil'` Finally, delete the `<script>` block we no longer need it: ```svelte /// file: App.svelte <script> let emoji = '🙈'; let description = 'see no evil'; </script> ```

## tutorial/02-advanced-svelte/02-snippets/02-passing-snippets/index.md

--- title: Passing snippets to components --- Since snippets — like functions — are just values, they can be passed to components as props. Take this `<FilteredList>` component. Its job is to filter the `data` that gets passed into it, but it has no opinions about how that data should be rendered — that's the responsibility of the parent component. We've already got some snippets defined. Begin by passing them into the `<FilteredList>`: ```svelte /// file: App.svelte <FilteredList data={colors} field="name" {header} {row} ></FilteredList> ``` Then, on the other side, declare `header` and `row` as props: ```svelte /// file: FilteredList.svelte <script> let { data, field,header, row} = $props(); // ... </script> ``` Finally, replace the placeholder content with render tags: ```svelte /// file: FilteredList.svelte <div class="header"> {@render header()} </div> <div class="content"> {#each filtered as d} {@render row(d)} {/each} </div> ``` Never again will you have to memorize the hex code for `MistyRose` or `PeachPuff`.

## tutorial/02-advanced-svelte/02-snippets/03-implicit-snippet-props/index.md

--- title: Implicit snippet props --- As an authoring convenience, snippets declared directly inside components become props _on_ those components. Take the `header` and `row` snippets and move them inside `<FilteredList>`: ```svelte /// file: App.svelte <FilteredList data={colors} field="name" {header} {row} > {#snippet header()}...{/snippet} {#snippet row(d)}...{/snippet} </FilteredList> {#snippet header()}...{/snippet} {#snippet row(d)}...{/snippet} ``` We can now remove them from the explicit props: ```svelte /// file: App.svelte <FilteredList data={colors} field="name"{header} {row}> {#snippet header()}...{/snippet} {#snippet row(d)}...{/snippet} </FilteredList> ``` Any content inside a component that is _not_ part of a declared snippet becomes a special `children` snippet. Since `header` has no parameters, we can turn it into `children` by removing the block tags... ```svelte /// file: App.svelte {#snippet header()} <header> <span class="color"></span> <span class="name">name</span> <span class="hex">hex</span> <span class="rgb">rgb</span> <span class="hsl">hsl</span> </header> {/snippet} ``` ...and renaming the `header` prop to `children` on the other side: ```svelte /// file: FilteredList.svelte <script> let { data, field,children, row } = $props(); // ... </script> ``` ```svelte /// file: FilteredList.svelte <div class="header"> {@render children()} </div> ```

## tutorial/02-advanced-svelte/03-motion/index.md

--- title: Motion scope: { 'prefix': '/src/lib/', 'name': 'src' } focus: /src/lib/App.svelte ---

## tutorial/02-advanced-svelte/03-motion/01-tweens/index.md

--- title: Tweened values --- Often, a good way to communicate that a value is changing is to use _motion_. Svelte ships classes for adding motion to your user interfaces. Import the `Tween` class from `svelte/motion`: ```svelte /// file: App.svelte <script> import { Tween } from 'svelte/motion'; let progress = $state(0); </script> ``` Turn `progress` into an instance of `Tween`: ```svelte /// file: App.svelte <script> import { Tween } from 'svelte/motion'; let progress =new Tween(0); </script> ``` The `Tween` class has a writable `target` property and a readonly `current` property — update the `<progress>` element... ```svelte <progress value={progress.current}></progress> ``` ...and each of the event handlers: ```svelte <button onclick={() => (progress.target= 0)}> 0% </button> ``` Clicking the buttons causes the progress bar to animate to its new value. It's a bit robotic and unsatisfying though. We need to add an easing function: ```svelte /// file: App.svelte <script> import { Tween } from 'svelte/motion'; import { cubicOut } from 'svelte/easing'; let progress = new Tween(0,{ duration: 400, easing: cubicOut }); </script> ``` The full set of options available to `Tween`: - `delay` — milliseconds before the tween starts - `duration` — either the duration of the tween in milliseconds, or a `(from, to) => milliseconds` function allowing you to (e.g.) specify longer tweens for larger changes in value - `easing` — a `p => t` function - `interpolate` — a custom `(from, to) => t => value` function for interpolating between arbitrary values. By default, Svelte will interpolate between numbers, dates, and identically-shaped arrays and objects (as long as they only contain numbers and dates or other valid arrays and objects). If you want to interpolate (for example) colour strings or transformation matrices, supply a custom interpolator You can also call `progress.set(value, options)` instead of assigning directly to `progress.target`, in which case `options` will override the defaults. The `set` method returns a promise that resolves when the tween completes.

## tutorial/02-advanced-svelte/03-motion/02-springs/index.md

--- title: Springs --- The `Spring` class is an alternative to `Tween` that often works better for values that are frequently changing. In this example we have a circle that follows the mouse, and two values — the circle's coordinates, and its size. Let's convert them to springs: ```svelte /// file: App.svelte <script> import { Spring } from 'svelte/motion'; let coords =new Spring({ x: 50, y: 50 }); let size =new Spring(10); </script> ``` As with `Tween`, springs have a writable `target` property and a readonly `current` property. Update the event handlers... ```svelte <svg onmousemove={(e) => { coords.target= { x: e.clientX, y: e.clientY }; }} onmousedown={() => (size.target= 30)} onmouseup={() => (size.target= 10)} role="presentation" > ``` ...and the `<circle>` attributes: ```svelte <circle cx={coords.current.x} cy={coords.current.y} r={size.current} ></circle> ``` Both springs have default `stiffness` and `damping` values, which control the spring's, well... springiness. We can specify our own initial values: ```js /// file: App.svelte let coords = new Spring({ x: 50, y: 50 },{ stiffness: 0.1, damping: 0.25 }); ``` Waggle your mouse around, and try dragging the sliders to get a feel for how they affect the spring's behaviour. Notice that you can adjust the values while the spring is still in motion.

## tutorial/02-advanced-svelte/04-advanced-bindings/index.md

--- title: Advanced bindings scope: { 'prefix': '/src/lib/', 'name': 'src' } focus: /src/lib/App.svelte ---

## tutorial/02-advanced-svelte/04-advanced-bindings/01-contenteditable-bindings/index.md

--- title: Contenteditable bindings --- Elements with a `contenteditable` attribute support `textContent` and `innerHTML` bindings: ```svelte /// file: App.svelte <divbind:innerHTML={html}contenteditable></div> ```

## tutorial/02-advanced-svelte/04-advanced-bindings/02-each-block-bindings/index.md

--- title: Each block bindings --- You can bind to properties inside an `each` block. ```svelte /// file: App.svelte {#each todos as todo} <li class:done={todo.done}> <input type="checkbox" bind:checked={todo.done} /> <input type="text" placeholder="What needs to be done?" bind:value={todo.text} /> </li> {/each} ```

## tutorial/02-advanced-svelte/04-advanced-bindings/03-media-elements/index.md

--- title: Media elements --- You can bind to properties of `<audio>` and `<video>` elements, making it easy to (for example) build custom player UI, like `AudioPlayer.svelte`. First, add the `<audio>` element along with its bindings (we'll use the shorthand form for `src`, `duration` and `paused`): ```svelte /// file: AudioPlayer.svelte <div class="player" class:paused> <audio {src} bind:currentTime={time} bind:duration bind:paused ></audio> <button class="play" aria-label={paused ? 'play' : 'pause'} ></button> ``` Next, add an event handler to the `<button>` that toggles `paused`: ```svelte /// file: AudioPlayer.svelte <button class="play" aria-label={paused ? 'play' : 'pause'} onclick={() => paused = !paused} ></button> ``` Our audio player now has basic functionality. Let's add the ability to seek to a specific part of a track by dragging the slider. Inside the slider's `pointerdown` handler there's a `seek` function, where we can update `time`: ```js /// file: AudioPlayer.svelte function seek(e) { const { left, width } = div.getBoundingClientRect(); let p = (e.clientX - left) / width; if (p < 0) p = 0; if (p > 1) p = 1; time = p * duration; } ``` When the track ends, be kind — rewind: ```svelte /// file: AudioPlayer.svelte <audio {src} bind:currentTime={time} bind:duration bind:paused onended={() => { time = 0; }} ></audio> ``` The complete set of bindings for `<audio>` and `<video>` is as follows — seven _readonly_ bindings... - `duration` — the total duration, in seconds - `buffered` — an array of `{start, end}` objects - `seekable` — ditto - `played` — ditto - `seeking` — boolean - `ended` — boolean - `readyState` — number between (and including) 0 and 4 ...and five _two-way_ bindings: - `currentTime` — the current position of the playhead, in seconds - `playbackRate` — speed up or slow down (`1` is 'normal') - `paused` — this one should be self-explanatory - `volume` — a value between 0 and 1 - `muted` — a boolean value where true is muted Videos additionally have readonly `videoWidth` and `videoHeight` bindings.

## tutorial/02-advanced-svelte/04-advanced-bindings/04-dimensions/index.md

--- title: Dimensions --- You can add `clientWidth`, `clientHeight`, `offsetWidth` and `offsetHeight` bindings to any element, and Svelte will update the bound values using a [`ResizeObserver`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver): ```svelte /// file: App.svelte <divbind:clientWidth={w} bind:clientHeight={h}> <span style="font-size: {size}px" contenteditable>{text}</span> <span class="size">{w} x {h}px</span> </div> ``` These bindings are readonly — changing the values of `w` and `h` won't have any effect on the element.

## tutorial/02-advanced-svelte/04-advanced-bindings/05-bind-this/index.md

--- title: This --- You can use the special `bind:this` directive to get a readonly binding to an element in your component. The `$effect` in this exercise attempts to create a canvas context, but `canvas` is `undefined`. Begin by declaring it at the top level of the component... ```svelte /// file: App.svelte <script> import { paint } from './gradient.js'; let canvas; $effect(() => { // ... }); </script> ``` ...then add the directive to the `<canvas>` element: ```svelte /// file: App.svelte <canvasbind:this={canvas}width={32} height={32}></canvas> ``` Note that the value of `canvas` will remain `undefined` until the component has mounted — in other words you can't access it until the `$effect` runs.

## tutorial/02-advanced-svelte/04-advanced-bindings/06-component-bindings/index.md

--- title: Component bindings --- Just as you can bind to properties of DOM elements, you can bind to component props. For example, we can bind to the `value` prop of this `<Keypad>` component as though it were a form element. First, we need to mark the prop as _bindable_. Inside `Keypad.svelte`, update the `$props()` declaration to use the `$bindable` rune: ```js /// file: Keypad.svelte let { value= $bindable(''), onsubmit } = $props(); ``` Then, in `App.svelte`, add a `bind:` directive: ```svelte /// file: App.svelte <Keypadbind:value={pin}{onsubmit} /> ``` Now, when the user interacts with the keypad, the value of `pin` in the parent component is immediately updated.

## tutorial/02-advanced-svelte/04-advanced-bindings/07-component-this/index.md

--- title: Binding to component instances --- Just as you can bind to DOM elements, you can bind to component instances themselves with `bind:this`. This is useful in the rare cases that you need to interact with a component programmatically (rather than by providing it with updated props). Revisiting our canvas app from [a few exercises ago](actions), it would be nice to add a button to clear the screen. First, let's export a function from `Canvas.svelte`: ```svelte /// file: Canvas.svelte let canvas = $state(); let context = $state(); let coords = $state(); export function clear() { context.clearRect(0, 0, canvas.width, canvas.height); } ``` Then, create a reference to the component instance: ```js /// file: App.svelte let selected = $state(colors[0]); let size = $state(10); let showMenu = $state(true); let canvas; ``` ```svelte /// file: App.svelte <Canvasbind:this={canvas}color={selected} size={size} /> ``` Finally, add a button that calls the `clear` function: ```svelte /// file: App.svelte <div class="controls"> <button class="show-menu" onclick={() => showMenu = !showMenu}> {showMenu ? 'close' : 'menu'} </button> <button onclick={() => canvas.clear()}> clear </button> </div> ```

## tutorial/02-advanced-svelte/05-advanced-transitions/index.md

--- title: Advanced transitions scope: { 'prefix': '/src/lib/', 'name': 'src' } focus: /src/lib/App.svelte ---

## tutorial/02-advanced-svelte/05-advanced-transitions/01-deferred-transitions/index.md

--- title: Deferred transitions --- A particularly powerful feature of Svelte's transition engine is the ability to _defer_ transitions, so that they can be coordinated between multiple elements. Take this pair of todo lists, in which toggling a todo sends it to the opposite list. In the real world, objects don't behave like that — instead of disappearing and reappearing in another place, they move through a series of intermediate positions. Using motion can go a long way towards helping users understand what's happening in your app. We can achieve this effect using the `crossfade` function, as seen in `transition.js`, which creates a pair of transitions 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. Open `TodoList.svelte`. First, import the `send` and `receive` transitions from transition.js: ```svelte /// file: TodoList.svelte <script> import { send, receive } from './transition.js'; let { todos, remove } = $props(); </script> ``` Then, add them to the `<li>` element, using the `todo.id` property as a key to match the elements: ```svelte /// file: TodoList.svelte <li class:done={todo.done} in:receive={{ key: todo.id }} out:send={{ key: todo.id }} > ``` Now, when you toggle items, they move smoothly to their new location. The non-transitioning items still jump around awkwardly — we can fix that in the next exercise.

## tutorial/02-advanced-svelte/05-advanced-transitions/02-animations/index.md

--- title: Animations --- In the [previous chapter](/tutorial/svelte/deferred-transitions), we used deferred transitions to create the illusion of motion as elements move from one todo list to the other. To complete the illusion, we also need to apply motion to the elements that _aren't_ transitioning. For this, we use the `animate` directive. First, import the `flip` function — flip stands for ['First, Last, Invert, Play'](https://aerotwist.com/blog/flip-your-animations/) — from `svelte/animate` into `TodoList.svelte`: ```svelte /// file: TodoList.svelte <script> import { flip } from 'svelte/animate'; import { send, receive } from './transition.js'; let { todos, remove } = $props(); </script> ``` Then add it to the `<li>` elements: ```svelte /// file: TodoList.svelte <li class:done={todo.done} in:receive={{ key: todo.id }} out:send={{ key: todo.id }} animate:flip > ``` The movement is a little slow in this case, so we can add a `duration` parameter: ```svelte /// file: TodoList.svelte <li class:done={todo.done} in:receive={{ key: todo.id }} out:send={{ key: todo.id }} animate:flip={{ duration: 200 }} > ``` Note that all the transitions and animations are being applied with CSS, rather than JavaScript, meaning they won't block (or be blocked by) the main thread.

## tutorial/02-advanced-svelte/06-context/index.md

--- title: Context API scope: { 'prefix': '/src/lib/', 'name': 'src' } focus: /src/lib/App.svelte ---

## tutorial/02-advanced-svelte/06-context/01-context-api/index.md

--- title: setContext and getContext --- The context API provides a mechanism for components to 'talk' to each other without passing around data and functions as props, or dispatching lots of events. It's an advanced feature, but a useful one. In this exercise, we're going to recreate [Schotter](https://collections.vam.ac.uk/item/O221321/schotter-print-nees-georg/) by George Nees — one of the pioneers of generative art — using the context API. Inside `Canvas.svelte`, there's an `addItem` function that adds an item to the canvas. We can make it available to components inside `<Canvas>`, like `<Square>`, with `setContext`: ```js /// file: Canvas.svelte import { setContext } from 'svelte'; import { SvelteSet } from 'svelte/reactivity'; let { width = 100, height = 100, children } = $props(); let canvas; let items = new SvelteSet(); setContext('canvas', { addItem }); function addItem(fn) { $effect(() => { items.add(fn); return () => items.delete(fn); }); } ``` Inside child components, we can now get the context with, well, `getContext`: ```js /// file: Square.svelte import { getContext } from 'svelte'; let { x, y, size, rotate } = $props(); getContext('canvas').addItem(draw); ``` So far, so... boring. Let's add some randomness to the grid: ```svelte /// file: App.svelte <div class="container"> <Canvas width={800} height={1200}> {#each Array(12) as _, c} {#each Array(22) as _, r} <Square x={180 + c * 40+ jitter(r * 2)} y={180 + r * 40+ jitter(r * 2)} size={40} rotate={jitter(r * 0.05)} /> {/each} {/each} </Canvas> </div> ``` `setContext` and `getContext` must be called during component initialisation, so that the context can be correctly bound. The key — `'canvas'` in this case — can be anything you like, including non-strings, which is useful for controlling who can access the context. > > ```js > // in a parent component > import { setContext } from 'svelte'; > > let context = $state({...}); > setContext('my-context', context); > ``` > > ```js > // in a child component > import { getContext } from 'svelte'; > > const context = getContext('my-context'); > ```

## tutorial/02-advanced-svelte/07-special-elements/index.md

--- title: Special elements scope: { 'prefix': '/src/lib/', 'name': 'src' } focus: /src/lib/App.svelte ---

## tutorial/02-advanced-svelte/07-special-elements/01-svelte-window/index.md

--- title: <svelte:window> --- Just as you can add event listeners to any DOM element, you can add event listeners to the `window` object with `<svelte:window>`. We've already got an `onkeydown` function declared — now all we need to do is wire it up: ```svelte /// file: App.svelte <svelte:window{onkeydown}/> ```

## tutorial/02-advanced-svelte/07-special-elements/02-svelte-window-bindings/index.md

--- title: <svelte:window> bindings --- We can also bind to certain properties of `window`, such as `scrollY`: ```svelte /// file: App.svelte <svelte:windowbind:scrollY={y}/> ``` The list of properties you can bind to is as follows: - `innerWidth` - `innerHeight` - `outerWidth` - `outerHeight` - `scrollX` - `scrollY` - `online` — an alias for `window.navigator.onLine` All except `scrollX` and `scrollY` are readonly.

## tutorial/02-advanced-svelte/07-special-elements/03-svelte-document/index.md

--- title: <svelte:document> --- The `<svelte:document>` element allows you to listen for events that fire on `document`. This is useful with events like `selectionchange`, which doesn't fire on `window`. Add the `onselectionchange` handler to the `<svelte:document>` tag: ```svelte /// file: App.svelte <svelte:document{onselectionchange}/> ```

## tutorial/02-advanced-svelte/07-special-elements/04-svelte-body/index.md

--- title: <svelte:body> --- Similar to `<svelte:window>` and `<svelte:document>`, the `<svelte:body>` element allows you to listen for events that fire on `document.body`. This is useful with the `mouseenter` and `mouseleave` events, which don't fire on `window`. Add `onmouseenter` and `onmouseleave` handlers to the `<svelte:body>` tag... ```svelte /// file: App.svelte <svelte:body onmouseenter={() => hereKitty = true} onmouseleave={() => hereKitty = false} /> ``` ...and hover over the `<body>`.

## tutorial/02-advanced-svelte/07-special-elements/05-svelte-head/index.md

--- title: <svelte:head> --- The `<svelte:head>` element allows you to insert elements inside the `<head>` of your document. This is useful for things like `<title>` and `<meta>` tags, which are critical for good SEO. Since those are quite hard to show in the context of this tutorial, we'll use it for a different purpose — loading stylesheets. ```svelte /// file: App.svelte <script> const themes = ['margaritaville', 'retrowave', 'spaaaaace', 'halloween']; let selected = $state(themes[0]); </script> <svelte:head> <link rel="stylesheet" href="/tutorial/stylesheets/{selected}.css" /> </svelte:head> <h1>Welcome to my site!</h1> ```

## tutorial/02-advanced-svelte/07-special-elements/06-svelte-element/index.md

--- title: <svelte:element> --- Sometimes you don't know in advance which element needs to be rendered. Rather than having a long list of `{#if ...}` blocks... ```svelte /// file: App.svelte {#if selected === 'h1'} <h1>I'm a <code>&lt;h1&gt;</code> element</h1> {:else} <p>TODO others</p> {/if} ``` ...we can use `<svelte:element>`: ```svelte /// file: App.svelte <svelte:element this={selected}> I'm a <code>&lt;{selected}&gt;</code> element </svelte:element> ``` The `this` value can be any string, or a falsy value — if it's falsy, no element is rendered.

## tutorial/02-advanced-svelte/07-special-elements/07-svelte-boundary/index.md

--- title: <svelte:boundary> --- To prevent errors from leaving your app in a broken state, you can contain them inside an _error boundary_ using the `<svelte:boundary>` element. In this example, `<FlakyComponent>` contains a bug — clicking the button will set `mouse` to `null`, meaning that the `{mouse.x}` and `{mouse.y}` expressions in the template will fail to render. In an ideal world we'd simply fix the bug. But that's not always an option — sometimes the component belongs to someone else, and sometimes you just need to guard against the unexpected. Begin by wrapping `<FlakyComponent />` with `<svelte:boundary>`: ```svelte <!file: App.svelte> <svelte:boundary> <FlakyComponent /> </svelte:boundary> ``` So far, nothing has changed, because the boundary doesn't specify a handler. Add a `failed` [snippet](snippets-and-render-tags) to provide some UI to show when an error occurs: ```svelte <!file: App.svelte> <svelte:boundary> <FlakyComponent /> {#snippet failed(error)} <p>Oops! {error.message}</p> {/snippet} </svelte:boundary> ``` Now, when we click the button, the contents of the boundary are replaced with the snippet. We can attempt to reset things by making use of the second argument passed to `failed`: ```svelte <!file: App.svelte> <svelte:boundary> <FlakyComponent /> {#snippet failed(error, reset)} <p>Oops! {error.message}</p> <button onclick={reset}>Reset</button> {/snippet} </svelte:boundary> ``` We can also specify an `onerror` handler, which is called with the same arguments passed to the `failed` snippet: ```svelte <!file: App.svelte> <svelte:boundaryonerror={(e) => console.error(e)}> <FlakyComponent /> {#snippet failed(error, reset)} <p>Oops! {error.message}</p> <button onclick={reset}>Reset</button> {/snippet} </svelte:boundary> ``` This is useful for sending information about the error to a reporting service, or adding UI outside the error boundary itself.

## tutorial/02-advanced-svelte/08-script-module/index.md

--- title: <script module> scope: { 'prefix': '/src/lib/', 'name': 'src' } focus: /src/lib/App.svelte ---

## tutorial/02-advanced-svelte/08-script-module/01-sharing-code/index.md

--- title: Sharing code --- In all the examples we've seen so far, the `<script>` block contains code that runs when each component instance is initialised. For the vast majority of components, that's all you'll ever need. Very occasionally, you'll need to run some code outside of an individual component instance. For example: returning to our custom audio player from a [previous exercise](media-elements), you can play all four tracks simultaneously. It would be better if playing one stopped all the others. We can do that by declaring a `<script module>` block. Code contained inside it will run once, when the module first evaluates, rather than when a component is instantiated. Place this at the top of `AudioPlayer.svelte` (note that this is a _separate_ script tag): ```svelte /// file: AudioPlayer.svelte <script module> let current; </script> ``` It's now possible for the components to 'talk' to each other without any state management: ```svelte /// file: AudioPlayer.svelte <audio src={src} bind:currentTime={time} bind:duration bind:paused onplay={(e) => { const audio = e.currentTarget; if (audio !== current) { current?.pause(); current = audio; } }} onended={() => { time = 0; }} /> ```

## tutorial/02-advanced-svelte/08-script-module/02-module-exports/index.md

--- title: Exports --- Anything exported from a `module` script block becomes an export from the module itself. Let's export a `stopAll` function: ```svelte /// file: AudioPlayer.svelte <script module> let current; export function stopAll() { current?.pause(); } </script> ``` We can now import `stopAll` in `App.svelte`... ```svelte /// file: App.svelte <script> import AudioPlayer,{ stopAll }from './AudioPlayer.svelte'; import { tracks } from './tracks.js'; </script> ``` ...and use it in an event handler: ```svelte /// file: App.svelte <div class="centered"> {#each tracks as track} <AudioPlayer {...track} /> {/each} <button onclick={stopAll}> stop all </button> </div> ```

## tutorial/02-advanced-svelte/09-next-steps/index.md

--- title: Next steps scope: { 'prefix': '/src/lib/', 'name': 'src' } focus: /src/lib/App.svelte ---

## tutorial/02-advanced-svelte/09-next-steps/01-congratulations/index.md

--- title: Congratulations! --- You've now finished the Svelte tutorial and are ready to start building. The next two parts of the tutorial will focus on SvelteKit, a full-fledged framework for creating apps of all shapes and sizes. If you're suffering from information overload and aren't ready to go through the SvelteKit tutorial yet, don't worry! You can use your existing Svelte knowledge without learning all of SvelteKit. Just run this in your terminal and follow the prompts... ```bash npx sv create ``` ...and start editing `src/routes/+page.svelte`. When you're ready, click the link below to continue your journey.

## tutorial/02-advanced-svelte/xx-currently-unused/01-debug/index.md

--- title: The @debug tag --- Occasionally, it's useful to inspect a piece of data as it flows through your app. One approach is to use `console.log(...)` inside your markup. If you want to pause execution, though, you can use the `{@debug ...}` tag with a comma-separated list of values you want to inspect: ```svelte /// file: App.svelte {@debug user} <h1>Hello {user.firstname}!</h1> ``` If you now open your devtools and start interacting with the `<input>` elements, you'll trigger the debugger as the value of `user` changes. (Note that the call stack and local variables will be hidden in this tutorial, because of iframe security restrictions.)

## tutorial/02-advanced-svelte/xx-currently-unused/01-svelte-self/index.md

--- title: <svelte:self> --- Svelte provides a variety of built-in elements. The first, `<svelte:self>`, allows a component to contain itself recursively. It's useful for things like this folder tree view, where folders can contain _other_ folders. In `Folder.svelte` we want to be able to do this... ```svelte /// file: Folder.svelte {#if file.files} <Folder {...file}/> {:else} <File {...file}/> {/if} ``` ...but that's impossible, because a module can't import itself. Instead, we use `<svelte:self>`: ```svelte /// file: Folder.svelte {#if file.files} <svelte:self {...file} /> {:else} <File {...file} /> {/if} ```

## tutorial/03-sveltekit/index.md

--- title: Basic SvelteKit label: Part 3 scope: { 'prefix': '/', 'name': 'project' } focus: /src/routes/+page.svelte ---

## tutorial/03-sveltekit/01-concepts/index.md

--- title: Introduction ---

## tutorial/03-sveltekit/01-concepts/01-introducing-sveltekit/index.md

--- title: What is SvelteKit? --- Whereas Svelte is a _component framework_, SvelteKit is an _app framework_ (or 'metaframework', depending on who you ask) that solves the tricky problems of building something production-ready: - Routing - Server-side rendering - Data fetching - Service workers - TypeScript integration - Prerendering - Single-page apps - Library packaging - Optimised production builds - Deploying to different hosting providers - ...and so on SvelteKit apps are server-rendered by default (like traditional 'multi-page apps' or MPAs) for excellent first load performance and SEO characteristics, but can then transition to client-side navigation (like modern 'single-page apps' or SPAs) to avoid jankily reloading everything (including things like third-party analytics code) when the user navigates. They can run anywhere JavaScript runs, though — as we'll see — your users may not need to run any JavaScript at all. If that sounds complicated, worry not: SvelteKit is the framework that grows with you! Start simple and add new features as you need them. ## Project structure On the right, in the file tree viewer, you'll see a handful of files that SvelteKit expects to find in a project. `package.json` will be familiar if you've worked with Node.js before. It lists the project's dependencies — including `svelte` and `@sveltejs/kit` — and a variety of `scripts` for interacting with the SvelteKit CLI. (We're currently running `npm run dev` in the bottom window.) `svelte.config.js` contains your project configuration. We don't need to worry about this file for now, but if you're curious, [visit the documentation](/docs/kit/configuration). `vite.config.js` contains the [Vite](https://vitejs.dev/) configuration. Because SvelteKit uses Vite, you can use [Vite features](https://vitejs.dev/guide/features.html) like hot module replacement, TypeScript support, static asset handling and so on. `src` is where your app's source code goes. `src/app.html` is your page template (SvelteKit replaces the `%sveltekit.head%` and `%sveltekit.body%` as appropriate), and `src/routes` defines the [routes](/tutorial/kit/pages) of your app. Finally, `static` contains any assets (like a `favicon.png` or a `robots.txt`) that should be included when your app is deployed.

## tutorial/03-sveltekit/02-routing/index.md

--- title: Routing ---

## tutorial/03-sveltekit/02-routing/01-pages/index.md

--- title: Pages --- SvelteKit uses filesystem-based routing, which means that the _routes_ of your app — in other words, what the app should do when a user navigates to a particular URL — are defined by the directories in your codebase. Every `+page.svelte` file inside `src/routes` creates a page in your app. In this app we currently have one page — `src/routes/+page.svelte`, which maps to `/`. If we navigate to `/about`, we'll see a 404 Not Found error. Let's fix that. Add a second page, `src/routes/about/+page.svelte`, copy the contents of `src/routes/+page.svelte`, and update it: ```svelte /// file: src/routes/about/+page.svelte <nav> <a href="/">home</a> <a href="/about">about</a> </nav> <h1>about</h1> <p>this is theaboutpage.</p> ``` We can now navigate between `/` and `/about`.

## tutorial/03-sveltekit/02-routing/02-layouts/index.md

--- title: Layouts --- Different routes of your app will often share common UI. Instead of repeating it in each `+page.svelte` component, we can use a `+layout.svelte` component that applies to all routes in the same directory. In this app we have two routes, `src/routes/+page.svelte` and `src/routes/about/+page.svelte`, that contain the same navigation UI. Let's create a new file, `src/routes/+layout.svelte`... ``` src/routes/ ├ about/ │ └ +page.svelte ├ +layout.svelte └ +page.svelte ``` ...and move the duplicated content from the `+page.svelte` files into the new `+layout.svelte` file. The `{@render children()}` tag is where the page content will be rendered: ```svelte /// file: src/routes/+layout.svelte <script> let { children } = $props(); </script> <nav> <a href="/">home</a> <a href="/about">about</a> </nav> {@render children()} ``` A `+layout.svelte` file applies to every child route, including the sibling `+page.svelte` (if it exists). You can nest layouts to arbitrary depth.

## tutorial/03-sveltekit/02-routing/03-params/index.md

--- title: Route parameters path: /blog --- To create routes with dynamic parameters, use square brackets around a valid variable name. For example, a file like `src/routes/blog/[slug]/+page.svelte` will create a route that matches `/blog/one`, `/blog/two`, `/blog/three` and so on. Let's create that file: ```svelte /// file: src/routes/blog/[slug]/+page.svelte <h1>blog post</h1> ``` We can now navigate from the `/blog` page to individual blog posts. In the next chapter, we'll see how to load their content.

## tutorial/03-sveltekit/03-loading-data/index.md

--- title: Loading data ---

## tutorial/03-sveltekit/03-loading-data/01-page-data/index.md

--- title: Page data path: /blog --- At its core, SvelteKit's job boils down to three things: 1. **Routing** — figure out which route matches an incoming request 2. **Loading** — get the data needed by the route 3. **Rendering** — generate some HTML (on the server) or update the DOM (in the browser) We've seen how routing and rendering work. Let's talk about the middle part — loading. Every page of your app can declare a `load` function in a `+page.server.js` file alongside the `+page.svelte` file. As the file name suggests, this module only ever runs on the server, including for client-side navigations. Let's add a `src/routes/blog/+page.server.js` file so that we can replace the hard-coded links in `src/routes/blog/+page.svelte` with actual blog post data: ```js /// file: src/routes/blog/+page.server.js import { posts } from './data.js'; export function load() { return { summaries: posts.map((post) => ({ slug: post.slug, title: post.title })) }; } ``` We can access this data in `src/routes/blog/+page.svelte` via the `data` prop: ```svelte /// file: src/routes/blog/+page.svelte <script> let { data } = $props(); </script> <h1>blog</h1> <ul> <li><a href="/blog/one">one</a></li> <li><a href="/blog/two">two</a></li> <li><a href="/blog/three">three</a></li> {#each data.summaries as { slug, title }} <li><a href="/blog/{slug}">{title}</a></li> {/each} </ul> ``` Now, let's do the same for the post page: ```js /// file: src/routes/blog/[slug]/+page.server.js import { posts } from '../data.js'; export function load({ params }) { const post = posts.find((post) => post.slug === params.slug); return { post }; } ``` ```svelte /// file: src/routes/blog/[slug]/+page.svelte <script> let { data } = $props(); </script> <h1>blog post</h1> <h1>{data.post.title}</h1> <div>{@html data.post.content}</div> ``` There's one last detail we need to take care of — the user might visit an invalid pathname like `/blog/nope`, in which case we'd like to respond with a 404 page: ```js /// file: src/routes/blog/[slug]/+page.server.js import { error } from '@sveltejs/kit'; import { posts } from '../data.js'; export function load({ params }) { const post = posts.find((post) => post.slug === params.slug); if (!post) error(404); return { post }; } ``` We'll learn more about error handling in later chapters.

## tutorial/03-sveltekit/03-loading-data/02-layout-data/index.md

--- title: Layout data path: /blog --- Just as `+layout.svelte` files create UI for every child route, `+layout.server.js` files load data for every child route. Suppose we'd like to add a 'more posts' sidebar to our blog post page. We _could_ return `summaries` from the `load` function in `src/routes/blog/[slug]/+page.server.js`, like we do in `src/routes/blog/+page.server.js`, but that would be repetitive. Instead, let's rename `src/routes/blog/+page.server.js` to `src/routes/blog/+layout.server.js`. Notice that the `/blog` route continues to work — `data.summaries` is still available to the page. Now, add a sidebar in the layout for the post page: ```svelte /// file: src/routes/blog/[slug]/+layout.svelte <script> let { data, children } = $props(); </script> <div class="layout"> <main> {@render children()} </main> <aside> <h2>More posts</h2> <ul> {#each data.summaries as { slug, title }} <li> <a href="/blog/{slug}">{title}</a> </li> {/each} </ul> </aside> </div> <style> @media (min-width: 640px) { .layout { display: grid; gap: 2em; grid-template-columns: 1fr 16em; } } </style> ``` The layout (and any page below it) inherits `data.summaries` from the parent `+layout.server.js`. When we navigate from one post to another, we only need to load the data for the post itself — the layout data is still valid. See the documentation on [invalidation](/docs/kit/load#Rerunning-load-functions) to learn more.

## tutorial/03-sveltekit/04-headers-and-cookies/index.md

--- title: Headers and cookies ---

## tutorial/03-sveltekit/04-headers-and-cookies/01-headers/index.md

--- title: Setting headers --- Inside a `load` function (as well as in [form actions](the-form-element), [hooks](handle) and [API routes](get-handlers), which we'll learn about later) you have access to a `setHeaders` function, which — unsurprisingly — can be used to set headers on the response. Most commonly, you'd use it to customise caching behaviour with the [`Cache-Control`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) response header, but for the sake of this tutorial we'll do something less advisable and more dramatic: ```js /// file: src/routes/+page.server.js export function load({ setHeaders }) { setHeaders({ 'Content-Type': 'text/plain' }); } ``` (You may need to reload the iframe to see the effect.)

## tutorial/03-sveltekit/04-headers-and-cookies/02-cookies/index.md

--- title: Reading and writing cookies --- The [`setHeaders`](headers) function can't be used with the `Set-Cookie` header. Instead, you should use the `cookies` API. In your `load` functions, you can read a cookie with `cookies.get(name, options)`: ```js /// file: src/routes/+page.server.js export function load({ cookies }) { const visited = cookies.get('visited'); return { visited: visited === 'true' }; } ``` To set a cookie, use `cookies.set(name, value, options)`. It's strongly recommended that you explicitly configure the `path` when setting a cookie, since browsers' default behaviour — somewhat uselessly — is to set the cookie on the parent of the current path. ```js /// file: src/routes/+page.server.js export function load({ cookies }) { const visited = cookies.get('visited'); cookies.set('visited', 'true', { path: '/' }); return { visited: visited === 'true' }; } ``` Now, if you reload the iframe, `Hello stranger!` becomes `Hello friend!`. Calling `cookies.set(name, ...)` causes a `Set-Cookie` header to be written, but it _also_ updates the internal map of cookies, meaning any subsequent calls to `cookies.get(name)` during the same request will return the updated value. Under the hood, the `cookies` API uses the popular `cookie` package — the options passed to `cookies.get` and `cookies.set` correspond to the `parse` and `serialize` options from the `cookie` [documentation](https://github.com/jshttp/cookie#api). SvelteKit sets the following defaults to make your cookies more secure: ```js { httpOnly: true, secure: true, sameSite: 'lax' } ```

## tutorial/03-sveltekit/05-shared-modules/index.md

--- title: Shared modules ---

## tutorial/03-sveltekit/05-shared-modules/01-lib/index.md

--- title: The $lib alias --- Because SvelteKit uses directory-based routing, it's easy to place modules and components alongside the routes that use them. A good rule of thumb is 'put code close to where it's used'. Sometimes, code is used in multiple places. When this happens, it's useful to have a place to put them that can be accessed by all routes without needing to prefix imports with `../../../../`. In SvelteKit, that place is the `src/lib` directory. Anything inside this directory can be accessed by any module in `src` via the `$lib` alias. Both `+page.svelte` files in this exercise import `src/lib/message.js`. But if you navigate to `/a/deeply/nested/route`, the app breaks, because we got the prefix wrong. Update it to use `$lib/message.js` instead: ```svelte /// file: src/routes/a/deeply/nested/route/+page.svelte <script> import { message } from'$lib/message.js'; </script> <h1>a deeply nested route</h1> <p>{message}</p> ``` Do the same for `src/routes/+page.svelte`: ```svelte /// file: src/routes/+page.svelte <script> import { message } from'$lib/message.js'; </script> <h1>home</h1> <p>{message}</p> ```

## tutorial/03-sveltekit/06-forms/index.md

--- title: Forms ---

## tutorial/03-sveltekit/06-forms/01-the-form-element/index.md

--- title: The <form> element --- In the chapter on [loading data](page-data), we saw how to get data from the server to the browser. Sometimes you need to send data in the opposite direction, and that's where `<form>` — the web platform's way of submitting data — comes in. Let's build a todo app. We've already got an in-memory database set up in `src/lib/server/database.js`, and our `load` function in `src/routes/+page.server.js` uses the [`cookies`](/docs/kit/load#Cookies) API so that we can have a per-user todo list, but we need to add a `<form>` to create new todos: ```svelte /// file: src/routes/+page.svelte <h1>todos</h1> <form method="POST"> <label> add a todo: <input name="description" autocomplete="off" /> </label> </form> <ul class="todos"> ``` If we type something into the `<input>` and hit Enter, the browser makes a POST request (because of the `method="POST"` attribute) to the current page. But that results in an error, because we haven't created a server-side _action_ to handle the POST request. Let's do that now: ```js /// file: src/routes/+page.server.js import * as db from '$lib/server/database.js'; export function load({ cookies }) { // ... } export const actions = { default: async ({ cookies, request }) => { const data = await request.formData(); db.createTodo(cookies.get('userid'), data.get('description')); } }; ``` The `request` is a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object; `await request.formData()` returns a [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) instance. When we hit Enter, the database is updated and the page reloads with the new data. Notice that we haven't had to write any `fetch` code or anything like that — data updates automatically. And because we're using a `<form>` element, this app would work even if JavaScript was disabled or unavailable.

## tutorial/03-sveltekit/06-forms/02-named-form-actions/index.md

--- title: Named form actions --- A page that only has a single action is, in practice, quite rare. Most of the time you'll need to have multiple actions on a page. In this app, creating a todo isn't enough — we'd like to delete them once they're complete. Begin by replacing our `default` action with named `create` and `delete` actions: ```js /// file: src/routes/+page.server.js export const actions = { create: async ({ cookies, request }) => { const data = await request.formData(); db.createTodo(cookies.get('userid'), data.get('description')); }, delete: async ({ cookies, request }) => { const data = await request.formData(); db.deleteTodo(cookies.get('userid'), data.get('id')); } }; ``` The `<form>` element has an optional `action` attribute, which is similar to an `<a>` element's `href` attribute. Update the existing form so that it points to the new `create` action: ```svelte /// file: src/routes/+page.svelte <form method="POST"action="?/create"> <label> add a todo: <input name="description" autocomplete="off" /> </label> </form> ``` Next, we want to create a form for each todo, complete with a hidden `<input>` that uniquely identifies it: ```svelte /// file: src/routes/+page.svelte <ul class="todos"> {#each data.todos as todo (todo.id)} <li> <form method="POST" action="?/delete"> <input type="hidden" name="id" value={todo.id} /> <span>{todo.description}</span> <button aria-label="Mark as complete"></button> </form> </li> {/each} </ul> ```

## tutorial/03-sveltekit/06-forms/03-form-validation/index.md

--- title: Validation --- Users are a mischievous bunch, who will submit all kinds of nonsensical data if given the chance. To prevent them from causing chaos, it's important to validate form data. The first line of defense is the browser's [built-in form validation](https://developer.mozilla.org/en-US/docs/Learn/Forms/Form_validation#using_built-in_form_validation), which makes it easy to, for example, mark an `<input>` as required: ```svelte /// file: src/routes/+page.svelte <form method="POST" action="?/create"> <label> add a todo <input name="description" autocomplete="off" required /> </label> </form> ``` Try hitting Enter while the `<input>` is empty. This kind of validation is helpful, but insufficient. Some validation rules (e.g. uniqueness) can't be expressed using `<input>` attributes, and in any case, if the user is an elite hacker they might simply delete the attributes using the browser's devtools. To guard against these sorts of shenanigans, you should always use server-side validation. In `src/lib/server/database.js`, validate that the description exists and is unique: ```js /// file: src/lib/server/database.js export function createTodo(userid, description) { if (description === '') { throw new Error('todo must have a description'); } const todos = db.get(userid); if (todos.find((todo) => todo.description === description)) { throw new Error('todos must be unique'); } todos.push({ id: crypto.randomUUID(), description, done: false }); } ``` Try submitting a duplicate todo. Yikes! SvelteKit takes us to an unfriendly-looking error page. On the server, we see a 'todos must be unique' error, but SvelteKit hides unexpected error messages from users because they often contain sensitive data. It would be much better to stay on the same page and provide an indication of what went wrong so that the user can fix it. To do this, we can use the `fail` function to return data from the action along with an appropriate HTTP status code: ```js /// file: src/routes/+page.server.js import { fail } from '@sveltejs/kit'; import * as db from '$lib/server/database.js'; export function load({ cookies }) {...} export const actions = { create: async ({ cookies, request }) => { const data = await request.formData(); try { db.createTodo(cookies.get('userid'), data.get('description')); } catch (error) { return fail(422, { description: data.get('description'), error: error.message }); } } ``` In `src/routes/+page.svelte`, we can access the returned value via the `form` prop, which is only ever populated after a form submission: ```svelte /// file: src/routes/+page.svelte <script> let { data,form} = $props(); </script> <div class="centered"> <h1>todos</h1> {#if form?.error} <p class="error">{form.error}</p> {/if} <form method="POST" action="?/create"> <label> add a todo: <input name="description" value={form?.description ?? ''} autocomplete="off" required /> </label> </form> ```

## tutorial/03-sveltekit/06-forms/04-progressive-enhancement/index.md

--- title: Progressive enhancement --- Because we're using `<form>`, our app works even if the user doesn't have JavaScript ([which happens more often than you probably think](https://kryogenix.org/code/browser/everyonehasjs.html)). That's great, because it means our app is resilient. Most of the time, users _do_ have JavaScript. In those cases, we can _progressively enhance_ the experience, the same way SvelteKit progressively enhances `<a>` elements by using client-side routing. Import the `enhance` function from `$app/forms`... ```svelte /// file: src/routes/+page.svelte <script> import { enhance } from '$app/forms'; let { data, form } = $props(); </script> ``` ...and add the `use:enhance` directive to the `<form>` elements: ```svelte /// file: src/routes/+page.svelte <form method="POST" action="?/create"use:enhance> ``` ```svelte /// file: src/routes/+page.svelte <form method="POST" action="?/delete"use:enhance> ``` And that's all it takes! Now, when JavaScript is enabled, `use:enhance` will emulate the browser-native behaviour except for the full-page reloads. It will: - update the `form` prop - invalidate all data on a successful response, causing `load` functions to re-run - navigate to the new page on a redirect response - render the nearest error page if an error occurs Now that we're updating the page rather than reloading it, we can get fancy with things like transitions: ```svelte /// file: src/routes/+page.svelte <script> import { fly, slide } from 'svelte/transition'; import { enhance } from '$app/forms'; let { data, form } = $props(); </script> ``` ```svelte /// file: src/routes/+page.svelte <liin:fly={{ y: 20 }} out:slide>...</li> ```

## tutorial/03-sveltekit/06-forms/05-customizing-use-enhance/index.md

--- title: Customizing use:enhance --- With `use:enhance`, we can go further than just emulating the browser's native behaviour. By providing a callback, we can add things like **pending states** and **optimistic UI**. Let's simulate a slow network by adding an artificial delay to our two actions: ```js /// file: src/routes/+page.server.js export const actions = { create: async ({ cookies, request }) => { await new Promise((fulfil) => setTimeout(fulfil, 1000)); ... }, delete: async ({ cookies, request }) => { await new Promise((fulfil) => setTimeout(fulfil, 1000)); ... } }; ``` When we create or delete items, it now takes a full second before the UI updates, leaving the user wondering if they messed up somehow. To solve that, add some local state... ```svelte /// file: src/routes/+page.svelte <script> import { fly, slide } from 'svelte/transition'; import { enhance } from '$app/forms'; let { data, form } = $props(); let creating = $state(false); let deleting = $state([]); </script> ``` ...and toggle `creating` inside the first `use:enhance`: ```svelte /// file: src/routes/+page.svelte <form method="POST" action="?/create" use:enhance={() => { creating = true; return async ({ update }) => { await update(); creating = false; }; }} > <label> add a todo: <input disabled={creating} name="description" value={form?.description ?? ''} autocomplete="off" required /> </label> </form> ``` We can then show a message while we're saving data: ```svelte /// file: src/routes/+page.svelte <ul class="todos"> </ul> {#if creating} <span class="saving">saving...</span> {/if} ``` In the case of deletions, we don't really need to wait for the server to validate anything — we can just update the UI immediately: ```svelte /// file: src/routes/+page.svelte <ul class="todos"> {#eachdata.todos.filter((todo) => !deleting.includes(todo.id))as todo (todo.id)} <li in:fly={{ y: 20 }} out:slide> <form method="POST" action="?/delete" use:enhance={() => { deleting = [...deleting, todo.id]; return async ({ update }) => { await update(); deleting = deleting.filter((id) => id !== todo.id); }; }} > <input type="hidden" name="id" value={todo.id} /> <button aria-label="Mark as complete">✔</button> {todo.description} </form> </li> {/each} </ul> ```

## tutorial/03-sveltekit/07-api-routes/index.md

--- title: API routes ---

## tutorial/03-sveltekit/07-api-routes/01-get-handlers/index.md

--- title: GET handlers --- SvelteKit allows you to create more than just pages. We can also create _API routes_ by adding a `+server.js` file that exports functions corresponding to HTTP methods: `GET`, `PUT`, `POST`, `PATCH` and `DELETE`. This app fetches data from a `/roll` API route when you click the button. Create that route by adding a `src/routes/roll/+server.js` file: ```js /// file: src/routes/roll/+server.js export function GET() { const number = Math.floor(Math.random() * 6) + 1; return new Response(number, { headers: { 'Content-Type': 'application/json' } }); } ``` Clicking the button now works. Request handlers must return a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response) object. Since it's common to return JSON from an API route, SvelteKit provides a convenience function for generating these responses: ```js /// file: src/routes/roll/+server.js import { json } from '@sveltejs/kit'; export function GET() { const number = Math.floor(Math.random() * 6) + 1; return new Response(number, { headers: { 'Content-Type': 'application/json' } }); return json(number); } ```

## tutorial/03-sveltekit/07-api-routes/02-post-handlers/index.md

--- title: POST handlers --- You can also add handlers that mutate data, such as `POST`. In most cases, you should use [form actions](the-form-element) instead — you'll end up writing less code, and it'll work without JavaScript, making it more resilient. Inside the `keydown` event handler of the 'add a todo' `<input>`, let's post some data to the server: ```svelte /// file: src/routes/+page.svelte <input type="text" autocomplete="off" onkeydown={async (e) => { if (e.key !== 'Enter') return; const input = e.currentTarget; const description = input.value; const response = await fetch('/todo', { method: 'POST', body: JSON.stringify({ description }), headers: { 'Content-Type': 'application/json' } }); input.value = ''; }} /> ``` Here, we're posting some JSON to the `/todo` API route — using a `userid` from the user's cookies — and receiving the `id` of the newly created todo in response. Create the `/todo` route by adding a `src/routes/todo/+server.js` file with a `POST` handler that calls `createTodo` in `src/lib/server/database.js`: ```js /// file: src/routes/todo/+server.js import { json } from '@sveltejs/kit'; import * as database from '$lib/server/database.js'; export async function POST({ request, cookies }) { const { description } = await request.json(); const userid = cookies.get('userid'); const { id } = await database.createTodo({ userid, description }); return json({ id }, { status: 201 }); } ``` As with `load` functions and form actions, the `request` is a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object; `await request.json()` returns the data that we posted from the event handler. We're returning a response with a [201 Created](https://http.dog/201) status and the `id` of the newly generated todo in our database. Back in the event handler, we can use this to update the page: ```svelte /// file: src/routes/+page.svelte <input type="text" autocomplete="off" onkeydown={async (e) => { if (e.key !== 'Enter') return; const input = e.currentTarget; const description = input.value; const response = await fetch('/todo', { method: 'POST', body: JSON.stringify({ description }), headers: { 'Content-Type': 'application/json' } }); const { id } = await response.json(); data.todos = [...data.todos, { id, description }]; input.value = ''; }} /> ```

## tutorial/03-sveltekit/07-api-routes/03-other-handlers/index.md

--- title: Other handlers --- Similarly, we can add handlers for other HTTP verbs. Add a `/todo/[id]` route by creating a `src/routes/todo/[id]/+server.js` file with `PUT` and `DELETE` handlers for toggling and removing todos, using the `toggleTodo` and `deleteTodo` functions in `src/lib/server/database.js`: ```js /// file: src/routes/todo/[id]/+server.js import * as database from '$lib/server/database.js'; export async function PUT({ params, request, cookies }) { const { done } = await request.json(); const userid = cookies.get('userid'); await database.toggleTodo({ userid, id: params.id, done }); return new Response(null, { status: 204 }); } export async function DELETE({ params, cookies }) { const userid = cookies.get('userid'); await database.deleteTodo({ userid, id: params.id }); return new Response(null, { status: 204 }); } ``` Since we don't need to return any actual data to the browser, we're returning an empty [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) with a [204 No Content](https://http.dog/204) status. We can now interact with this endpoint inside our event handlers: ```svelte /// file: src/routes/+page.svelte <label> <input type="checkbox" checked={todo.done} onchange={async (e) => { const done = e.currentTarget.checked; await fetch(`/todo/${todo.id}`, { method: 'PUT', body: JSON.stringify({ done }), headers: { 'Content-Type': 'application/json' } }); }} /> <span>{todo.description}</span> <button aria-label="Mark as complete" onclick={async (e) => { await fetch(`/todo/${todo.id}`, { method: 'DELETE' }); data.todos = data.todos.filter((t) => t !== todo); }} ></button> </label> ```

## tutorial/03-sveltekit/08-stores/index.md

--- title: Stores ---

## tutorial/03-sveltekit/08-stores/01-page-store/index.md

--- title: page --- > TODO link to stores exercise As we learned earlier, Svelte stores are a place to put data that doesn't belong to an individual component. SvelteKit makes three readonly stores available via the `$app/stores` module — `page`, `navigating` and `updated`. The one you'll use most often is [`page`](/docs/kit/@sveltejs-kit#Page), which provides information about the current page: - `url` — the [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) of the current page - `params` — the current page's [parameters](params) - `route` — an object with an `id` property representing the current route - `status` — the HTTP status code of the current page - `error` — the error object of the current page, if any (you'll learn more about error handling in [later](error-basics) [exercises](handleerror)) - `data` — the data for the current page, combining the return values of all `load` functions - `form` — the data returned from a [form action](the-form-element) As with any other store, you can reference its value in a component by prefixing its name with the `$` symbol. For example, we can access the current pathname as `$page.url.pathname`: ```svelte /// file: src/routes/+layout.svelte <script> import { page } from '$app/stores'; let { children } = $props(); </script> <nav> <a href="/"aria-current={$page.url.pathname === '/'}> home </a> <a href="/about"aria-current={$page.url.pathname === '/about'}> about </a> </nav> {@render children()} ```

## tutorial/03-sveltekit/08-stores/02-navigating-store/index.md

--- title: navigating --- The `navigating` store represents the current navigation. When a navigation starts — because of a link click, or a back/forward navigation, or a programmatic `goto` — the value of `navigating` will become an object with the following properties: - `from` and `to` — objects with `params`, `route` and `url` properties - `type` — the type of navigation, e.g. `link`, `popstate` or `goto` It can be used to show a loading indicator for long-running navigations. In this exercise, `src/routes/+page.server.js` and `src/routes/about/+page.server.js` both have an artificial delay. Inside `src/routes/+layout.svelte`, import the `navigating` store and add a message to the nav bar: ```svelte /// file: src/routes/+layout.svelte <script> import { page,navigating} from '$app/stores'; let { children } = $props(); </script> <nav> <a href="/" aria-current={$page.url.pathname === '/'}> home </a> <a href="/about" aria-current={$page.url.pathname === '/about'}> about </a> {#if $navigating} navigating to {$navigating.to.url.pathname} {/if} </nav> {@render children()} ```

## tutorial/03-sveltekit/08-stores/03-updated-store/index.md

--- title: updated --- The `updated` store contains `true` or `false` depending on whether a new version of the app has been deployed since the page was first opened. For this to work, your `svelte.config.js` must specify `kit.version.pollInterval`. ```svelte /// file: src/routes/+layout.svelte <script> import { page, navigating,updated} from '$app/stores'; </script> ``` Version changes only happen in production, not during development. For that reason, `$updated` will always be `false` in this tutorial. You can manually check for new versions, regardless of `pollInterval`, by calling `updated.check()`. ```svelte /// file: src/routes/+layout.svelte {#if $updated} <div class="toast"> <p> A new version of the app is available <button onclick={() => location.reload()}> reload the page </button> </p> </div> {/if} ```

## tutorial/03-sveltekit/09-errors-and-redirects/index.md

--- title: Errors and redirects ---

## tutorial/03-sveltekit/09-errors-and-redirects/01-error-basics/index.md

--- title: Basics --- There are two types of errors in SvelteKit — _expected_ errors and _unexpected_ errors. An expected error is one that was thrown via the [`error`](/docs/kit/@sveltejs-kit#error) helper from `@sveltejs/kit`, as in `src/routes/expected/+page.server.js`: ```js /// file: src/routes/expected/+page.server.js import { error } from '@sveltejs/kit'; export function load() { error(420, 'Enhance your calm'); } ``` Any other error — such as the one in `src/routes/unexpected/+page.server.js` — is treated as unexpected: ```js /// file: src/routes/unexpected/+page.server.js export function load() { throw new Error('Kaboom!'); } ``` When you throw an expected error, you're telling SvelteKit 'don't worry, I know what I'm doing here'. An unexpected error, by contrast, is assumed to be a bug in your app. When an unexpected error is thrown, its message and stack trace will be logged to the console. If you click the links in this app, you'll notice an important difference: the expected error message is shown to the user, whereas the unexpected error message is redacted and replaced with a generic 'Internal Error' message and a 500 status code. That's because error messages can contain sensitive data.

## tutorial/03-sveltekit/09-errors-and-redirects/02-error-pages/index.md

--- title: Error pages --- When something goes wrong inside a `load` function, SvelteKit renders an error page. The default error page is somewhat bland. We can customize it by creating a `src/routes/+error.svelte` component: ```svelte /// file: src/routes/+error.svelte <script> import { page } from '$app/stores'; import { emojis } from './emojis.js'; </script> <h1>{$page.status} {$page.error.message}</h1> <span style="font-size: 10em"> {emojis[$page.status] ?? emojis[500]} </span> ``` Notice that the `+error.svelte` component is rendered inside the root `+layout.svelte`. We can create more granular `+error.svelte` boundaries: ```svelte /// file: src/routes/expected/+error.svelte <h1>this error was expected</h1> ``` This component will be rendered for `/expected`, while the root `src/routes/+error.svelte` page will be rendered for any other errors that occur.

## tutorial/03-sveltekit/09-errors-and-redirects/03-fallback-errors/index.md

--- title: Fallback errors --- If things go _really_ wrong — an error occurs while loading the root layout data, or while rendering the error page — SvelteKit will fall back to a static error page. Add a new `src/routes/+layout.server.js` file to see this in action: ```js /// file: src/routes/+layout.server.js export function load() { throw new Error('yikes'); } ``` You can customise the fallback error page. Create a `src/error.html` file: ```html /// file: src/error.html <h1>Game over</h1> <p>Code %sveltekit.status%</p> <p>%sveltekit.error.message%</p> ``` This file can include the following: - `%sveltekit.status%` — the HTTP status code - `%sveltekit.error.message%` — the error message

## tutorial/03-sveltekit/09-errors-and-redirects/04-redirects/index.md

--- title: Redirects --- We can also use the `throw` mechanism to redirect from one page to another. Create a new `load` function in `src/routes/a/+page.server.js`: ```js /// file: src/routes/a/+page.server.js import { redirect } from '@sveltejs/kit'; export function load() { redirect(307, '/b'); } ``` Navigating to `/a` will now take us straight to `/b`. You can `redirect(...)` inside `load` functions, form actions, API routes and the `handle` hook, which we'll discuss in a later chapter. The most common status codes you'll use: - `303` — for form actions, following a successful submission - `307` — for temporary redirects - `308` — for permanent redirects

## tutorial/03-sveltekit/09-errors-and-redirects/xx-custom-error-messages/index.md

--- title: Customizing the error message --- The error page in the previous exercise is rather static. Maybe you want to show the error message so you can help people turning up in your support channels faster. For this, SvelteKit provides you with `$page.error` and `$page.status`, which contain information about the error and the status code. Let's add it to `+error.svelte`: ```svelte /// file: src/routes/+error.svelte <script> import { page } from '$app/stores'; let online = typeof navigator !== 'undefined' ? navigator.onLine : true; </script> {#if $page.status === 404} <h1>Not found</h1> {:elseif !online} <h1>You're offline</h1> {:else} <h1>Oops!</h1> <p>Something went wrong</p> <p>{$page.error.message}</p> {/if} ``` That's better, but `$page.error.message` always contains "Internal Error" - how so? This is because SvelteKit plays it safe and prevents you from accidentally showing sensitive information as part of the error message. To customize it, implement the `handleError` hook in `hooks.server.js` and `hooks.client.js` which run when an unexpected error is thrown during data loads on the server or client respectively. ```js // hooks.server.js export function handleError({ error }) { return { message: 'Internal Error' }; // the default implementation of this hook return { message: error instanceof Error ? error.message : 'Internal Error' }; } ``` ```js // hooks.client.js export function handleError({ error }) { return { message: 'Internal Error' }; // the default implementation of this hook return { message: error instanceof Error ? error.message : 'Internal Error' }; } ``` You could also call your error reporting service in these hooks. Note that you can return more than an error message if you like. Whatever object shape you return will be available in `$page.error`, the only requirement is a `message` property. You can read more about this (and how to make it type-safe!) in the [error docs](/docs/kit/errors).

## tutorial/04-advanced-sveltekit/index.md

--- title: Advanced SvelteKit label: Part 4 scope: { 'prefix': '/', 'name': 'project' } focus: /src/routes/+page.svelte ---

## tutorial/04-advanced-sveltekit/01-hooks/index.md

--- title: Hooks ---

## tutorial/04-advanced-sveltekit/01-hooks/01-handle/index.md

--- title: handle --- SvelteKit provides several _hooks_ — ways to intercept and override the framework's default behaviour. The most elementary hook is `handle`, which lives in `src/hooks.server.js`. It receives an `event` object along with a `resolve` function, and returns a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response). `resolve` is where the magic happens: SvelteKit matches the incoming request URL to a route of your app, imports the relevant code (`+page.server.js` and `+page.svelte` files and so on), loads the data needed by the route, and generates the response. The default `handle` hook looks like this: ```js /// file: src/hooks.server.js export async function handle({ event, resolve }) { return await resolve(event); } ``` For pages (as opposed to [API routes](get-handlers)), you can modify the generated HTML with `transformPageChunk`: ```js /// file: src/hooks.server.js export async function handle({ event, resolve }) { return await resolve(event, { transformPageChunk: ({ html }) => html.replace( '<body', '<body style="color: hotpink"' ) }); } ``` You can also create entirely new routes: ```js /// file: src/hooks.server.js export async function handle({ event, resolve }) { if (event.url.pathname === '/ping') { return new Response('pong'); } return await resolve(event, { transformPageChunk: ({ html }) => html.replace( '<body', '<body style="color: hotpink"' ) }); } ```

## tutorial/04-advanced-sveltekit/01-hooks/02-event/index.md

--- title: The RequestEvent object --- The `event` object passed into `handle` is the same object — an instance of a [`RequestEvent`](/docs/kit/@sveltejs-kit#RequestEvent) — that is passed into [API routes](get-handlers) in `+server.js` files, [form actions](the-form-element) in `+page.server.js` files, and `load` functions in `+page.server.js` and `+layout.server.js`. It contains a number of useful properties and methods, some of which we've already encountered: - `cookies` — the [cookies API](cookies) - `fetch` — the standard [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API), with additional powers - `getClientAddress()` — a function to get the client's IP address - `isDataRequest` — `true` if the browser is requesting data for a page during client-side navigation, `false` if a page/route is being requested directly - `locals` — a place to put arbitrary data - `params` — the route parameters - `request` — the [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object - `route` — an object with an `id` property representing the route that was matched - `setHeaders(...)` — a function for [setting HTTP headers](headers) on the response - `url` — a [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) object representing the current request A useful pattern is to add some data to `event.locals` in `handle` so that it can be read in subsequent `load` functions: ```js /// file: src/hooks.server.js export async function handle({ event, resolve }) { event.locals.answer = 42; return await resolve(event); } ``` ```js /// file: src/routes/+page.server.js export function load(event) { return { message: `the answer is ${event.locals.answer}` }; } ```

## tutorial/04-advanced-sveltekit/01-hooks/03-handlefetch/index.md

--- title: handleFetch --- The `event` object has a `fetch` method that behaves like the standard [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API), but with superpowers: - it can be used to make credentialed requests on the server, as it inherits the `cookie` and `authorization` headers from the incoming request - it can make relative requests on the server (ordinarily, `fetch` requires a URL with an origin when used in a server context) - internal requests (e.g. for `+server.js` routes) go directly to the handler function when running on the server, without the overhead of an HTTP call Its behaviour can be modified with the `handleFetch` hook, which by default looks like this: ```js /// file: src/hooks.server.js export async function handleFetch({ event, request, fetch }) { return await fetch(request); } ``` For example, we could respond to requests for `src/routes/a/+server.js` with responses from `src/routes/b/+server.js` instead: ```js /// file: src/hooks.server.js export async function handleFetch({ event, request, fetch }) { const url = new URL(request.url); if (url.pathname === '/a') { return await fetch('/b'); } return await fetch(request); } ``` Later, when we cover [universal `load` functions](universal-load-functions), we'll see that `event.fetch` can also be called from the browser. In that scenario, `handleFetch` is useful if you have requests to a public URL like `https://api.yourapp.com` from the browser, that should be redirected to an internal URL (bypassing whatever proxies and load balancers sit between the API server and the public internet) when running on the server.

## tutorial/04-advanced-sveltekit/01-hooks/04-handleerror/index.md

--- title: handleError --- The `handleError` hook lets you intercept unexpected errors and trigger some behaviour, like pinging a Slack channel or sending data to an error logging service. As you'll recall from an [earlier exercise](error-basics), an error is _unexpected_ if it wasn't created with the `error` helper from `@sveltejs/kit`. It generally means something in your app needs fixing. The default behaviour is to log the error: ```js /// file: src/hooks.server.js export function handleError({ event, error }) { console.error(error.stack); } ``` If you navigate to `/the-bad-place`, you'll see this in action — the error page is shown, and if you open the terminal (using the button to the right of the URL bar), you'll see the message from `src/routes/the-bad-place/+page.server.js`. Notice that we're _not_ showing the error message to the user. That's because error messages can include sensitive information that at best will confuse your users, and at worst could benefit evildoers. Instead, the error object available to your application — represented as `$page.error` in your `+error.svelte` pages, or `%sveltekit.error%` in your `src/error.html` fallback — is just this: ```js { message: 'Internal Error' // or 'Not Found' for a 404 } ``` In some situations you may want to customise this object. To do so, you can return an object from `handleError`: ```js /// file: src/hooks.server.js export function handleError({ event, error }) { console.error(error.stack); return { message: 'everything is fine', code: 'JEREMYBEARIMY' }; } ``` You can now reference properties other than `message` in a custom error page. Create `src/routes/+error.svelte`: ```svelte /// file: src/routes/+error.svelte <script> import { page } from '$app/stores'; </script> <h1>{$page.status}</h1> <p>{$page.error.message}</p> <p>error code: {$page.error.code}</p> ```

## tutorial/04-advanced-sveltekit/02-page-options/index.md

--- title: Page options ---

## tutorial/04-advanced-sveltekit/02-page-options/01-page-options/index.md

--- title: Basics --- In the chapter on [loading data](/tutorial/kit/page-data), we saw how you can export `load` functions from `+page.js`, `+page.server.js`, `+layout.js` and `+layout.server.js` files. We can also export various **page options** from these modules: - `ssr` — whether or not pages should be server-rendered - `csr` — whether to load the SvelteKit client - `prerender` — whether to prerender pages at build time, instead of per-request - `trailingSlash` — whether to strip, add, or ignore trailing slashes in URLs In the following exercises, we'll learn about each of these in turn. Page options can apply to individual pages (if exported from `+page.js` or `+page.server.js`), or groups of pages (if exported from `+layout.js` or `+layout.server.js`). To define an option for the whole app, export it from the root layout. Child layouts and pages override values set in parent layouts, so — for example — you can enable prerendering for your entire app then disable it for pages that need to be dynamically rendered. You can mix and match these options in different areas of your app — you could prerender your marketing pages, dynamically server-render your data-driven pages, and treat your admin pages as a client-rendered SPA. This makes SvelteKit very versatile.

## tutorial/04-advanced-sveltekit/02-page-options/02-ssr/index.md

--- title: ssr --- Server-side rendering (SSR) is the process of generating HTML on the server, and is what SvelteKit does by default. It's important for performance and [resilience](https://kryogenix.org/code/browser/everyonehasjs.html), and is very beneficial for search engine optimization (SEO) — while some search engines can index content that is rendered in the browser with JavaScript, it happens less frequently and reliably. That said, some components _can't_ be rendered on the server, perhaps because they expect to be able to access browser globals like `window` immediately. If you can, you should change those components so that they _can_ render on the server, but if you can't then you can disable SSR: ```js /// file: src/routes/+page.server.js export const ssr = false; ```

## tutorial/04-advanced-sveltekit/02-page-options/03-csr/index.md

--- title: csr --- Client-side rendering is what makes the page interactive — such as incrementing the counter when you click the button in this app — and enables SvelteKit to update the page upon navigation without a full-page reload. As with `ssr`, you can disable client-side rendering altogether: ```js /// file: src/routes/+page.server.js export const csr = false; ``` This means that no JavaScript is served to the client, but it also means that your components are no longer interactive. It can be a useful way to check whether or not your application is usable for people who — for whatever reason — cannot use JavaScript.

## tutorial/04-advanced-sveltekit/02-page-options/04-prerender/index.md

--- title: prerender --- Prerendering means generating HTML for a page once, at build time, rather than dynamically for each request. The advantage is that serving static data is extremely cheap and performant, allowing you to easily serve large numbers of users without worrying about cache-control headers (which are easy to get wrong). The tradeoff is that the build process takes longer, and prerendered content can only be updated by building and deploying a new version of the application. To prerender a page, set `prerender` to `true`: ```js /// file: src/routes/+page.server.js export const prerender = true; ``` Here in the tutorial, this won't have any observable effect, since the application is running in `dev` mode. Not all pages can be prerendered. The basic rule is this: for content to be prerenderable, any two users hitting it directly must get the same content from the server, and the page must not contain form actions. Pages with dynamic route parameters can be prerendered as long as they are specified in the [`prerender.entries`](/docs/kit/configuration#prerender) configuration or can be reached by following links from pages that _are_ in `prerender.entries`.

## tutorial/04-advanced-sveltekit/02-page-options/05-trailingslash/index.md

--- title: trailingSlash --- Two URLs like `/foo` and `/foo/` might look the same, but they're actually different. A relative URL like `./bar` will resolve to `/bar` in the first case and `/foo/bar` in the second, and search engines will treat them as separate entries, harming your SEO. In short, being loosey-goosey about trailing slashes is a bad idea. By default, SvelteKit strips trailing slashes, meaning that a request for `/foo/` will result in a redirect to `/foo`. If you instead want to ensure that a trailing slash is always present, you can specify the `trailingSlash` option accordingly: ```js /// file: src/routes/always/+page.server.js export const trailingSlash = 'always'; ``` To accommodate both cases (this is not recommended!), use `'ignore'`: ```js /// file: src/routes/ignore/+page.server.js export const trailingSlash = 'ignore'; ``` The default value is `'never'`. Whether or not trailing slashes are applied affects prerendering. A URL like `/always/` will be saved to disk as `always/index.html` whereas a URL like `/never` will be saved as `never.html`.

## tutorial/04-advanced-sveltekit/03-link-options/index.md

--- title: Link options ---

## tutorial/04-advanced-sveltekit/03-link-options/01-preload/index.md

--- title: Preloading --- In this exercise, the `/slow-a` and `/slow-b` routes both have artificial delays in their `load` functions, meaning it takes a long time to navigate to them. You can't always make your data load more quickly — sometimes it's out of your control — but SvelteKit can speed up navigations by _anticipating_ them. When an `<a>` element has a `data-sveltekit-preload-data` attribute, SvelteKit will begin the navigation as soon as the user hovers over the link (on desktop) or taps it (on mobile). Try adding it to the first link: ```svelte /// file: src/routes/+layout.svelte <nav> <a href="/">home</a> <a href="/slow-a"data-sveltekit-preload-data>slow-a</a> <a href="/slow-b">slow-b</a> </nav> ``` Navigating to `/slow-a` will now be noticeably faster. Starting navigation on hover or tap (rather than waiting for a `click` event to be registered) might not sound like it makes much difference, but in practice it typically saves 200ms or more. That's enough to be the difference between sluggish and snappy. You can put the attribute on individual links, or on any element that _contains_ links. The default project template includes the attribute on the `<body>` element: ```html <body data-sveltekit-preload-data> %sveltekit.body% </body> ``` You can customise the behaviour further by specifying one of the following values for the attribute: - `"hover"` (default, falls back to `"tap"` on mobile) - `"tap"` — only begin preloading on tap - `"off"` — disable preloading Using `data-sveltekit-preload-data` may sometimes result in false positives - i.e. loading data in anticipation of a navigation that doesn't then happen — which might be undesirable. As an alternative, `data-sveltekit-preload-code` allows you to preload the JavaScript needed by a given route without eagerly loading its data. This attribute can have the following values: - `"eager"` — preload everything on the page following a navigation - `"viewport"` — preload everything as it appears in the viewport - `"hover"` (default) as above - `"tap"` — as above - `"off"` — as above You can also initiate preloading programmatically with `preloadCode` and `preloadData` imported from `$app/navigation`: ```js import { preloadCode, preloadData } from '$app/navigation'; // preload the code and data needed to navigate to /foo preloadData('/foo'); // preload the code needed to navigate to /bar, but not the data preloadCode('/bar'); ```

## tutorial/04-advanced-sveltekit/03-link-options/02-reload/index.md

--- title: Reloading the page --- Ordinarily, SvelteKit will navigate between pages without refreshing the page. In this exercise, if we navigate between `/` and `/about`, the timer keeps on ticking. In rare cases, you might want to disable this behaviour. You can do so by adding the `data-sveltekit-reload` attribute on an individual link, or any element that contains links: ```svelte /// file: src/routes/+layout.svelte <navdata-sveltekit-reload> <a href="/">home</a> <a href="/about">about</a> </nav> ``` For more information on available link options and their values, consult the [link options documentation](/docs/kit/link-options).

## tutorial/04-advanced-sveltekit/04-advanced-routing/index.md

--- title: Advanced routing ---

## tutorial/04-advanced-sveltekit/04-advanced-routing/01-optional-params/index.md

--- title: Optional parameters --- In the first chapter on [routing](/tutorial/kit/pages), we learned how to create routes with [dynamic parameters](/tutorial/kit/params). Sometimes it's helpful to make a parameter optional. A classic example is when you use the pathname to determine the locale — `/fr/...`, `/de/...` and so on — but you also want to have a default locale. To do that, we use double brackets. Rename the `[lang]` directory to `[[lang]]`. The app now fails to build, because `src/routes/+page.svelte` and `src/routes/[[lang]]/+page.svelte` would both match `/`. Delete `src/routes/+page.svelte`. (You may need to reload the app to recover from the error page). Lastly, edit `src/routes/[[lang]]/+page.server.js` to specify the default locale: ```js /// file: src/routes/[[lang]]/+page.server.js const greetings = { en: 'hello!', de: 'hallo!', fr: 'bonjour!' }; export function load({ params }) { return { greeting: greetings[params.lang?? 'en'] }; } ```

## tutorial/04-advanced-sveltekit/04-advanced-routing/02-rest-params/index.md

--- title: Rest parameters path: /how focus: /src/routes/[path]/+page.svelte --- To match an unknown number of path segments, use a `[...rest]` parameter, so named for its resemblance to [rest parameters in JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters). Rename `src/routes/[path]` to `src/routes/[...path]`. The route now matches any path. > > ```tree > src/routes/ > ├ categories/ > │ ├ animal/ > │ ├ mineral/ > │ ├ vegetable/ > +++│ ├ [...catchall]/ > │ │ ├ +error.svelte > │ │ └ +page.server.js+++ > ``` > > Inside the `+page.server.js` file, `error(404)` inside `load`. Rest parameters do _not_ need to go at the end — a route like `/items/[...path]/edit` or `/items/[...path].json` is totally valid.

## tutorial/04-advanced-sveltekit/04-advanced-routing/03-param-matchers/index.md

--- title: Param matchers path: /colors/ff3e00 --- To prevent the router from matching on invalid input, you can specify a _matcher_. For example, you might want a route like `/colors/[value]` to match hex values like `/colors/ff3e00` but not named colors like `/colors/octarine` or any other arbitrary input. First, create a new file called `src/params/hex.js` and export a `match` function from it: ```js /// file: src/params/hex.js export function match(value) { return /^[0-9a-f]{6}$/.test(value); } ``` Then, to use the new matcher, rename `src/routes/colors/[color]` to `src/routes/colors/[color=hex]`. Now, whenever someone navigates to that route, SvelteKit will verify that `color` is a valid `hex` value. If not, SvelteKit will try to match other routes, before eventually returning a 404.

## tutorial/04-advanced-sveltekit/04-advanced-routing/04-route-groups/index.md

--- title: Route groups --- As we saw in the [routing introduction](/tutorial/kit/layouts), layouts are a way to share UI and data loading logic between different routes. Sometimes it's useful to use layouts without affecting the route — for example, you might need your `/app` and `/account` routes to be behind authentication, while your `/about` page is open to the world. We can do this with a _route group_, which is a directory in parentheses. Create an `(authed)` group by renaming `account` to `(authed)/account` then renaming `app` to `(authed)/app`. Now we can control access to these routes by creating `src/routes/(authed)/+layout.server.js`: ```js /// file: src/routes/(authed)/+layout.server.js import { redirect } from '@sveltejs/kit'; export function load({ cookies, url }) { if (!cookies.get('logged_in')) { redirect(303, `/login?redirectTo=${url.pathname}`); } } ``` If you try to visit these pages, you'll be redirected to the `/login` route, which has a form action in `src/routes/login/+page.server.js` that sets the `logged_in` cookie. We can also add some UI to these two routes by adding a `src/routes/(authed)/+layout.svelte` file: ```svelte /// file: src/routes/(authed)/+layout.svelte <script> let { children } = $props(); </script> <form method="POST" action="/logout"> <button>log out</button> </form> ```

## tutorial/04-advanced-sveltekit/04-advanced-routing/05-breaking-out-of-layouts/index.md

--- title: Breaking out of layouts editing_constraints: { 'create': ['/src/routes/a/b/c/+page@b.svelte', '/src/routes/a/b/c/+page@a.svelte'] } --- Ordinarily, a page inherits every layout above it, meaning that `src/routes/a/b/c/+page.svelte` inherits four layouts: - `src/routes/+layout.svelte` - `src/routes/a/+layout.svelte` - `src/routes/a/b/+layout.svelte` - `src/routes/a/b/c/+layout.svelte` Occasionally, it's useful to break out of the current layout hierarchy. We can do that by adding the `@` sign followed by the name of the parent segment to 'reset' to — for example `+page@b.svelte` would put `/a/b/c` inside `src/routes/a/b/+layout.svelte`, while `+page@a.svelte` would put it inside `src/routes/a/+layout.svelte`. Let's reset it all the way to the root layout, by renaming it to `+page@.svelte`.

## tutorial/04-advanced-sveltekit/05-advanced-loading/index.md

--- title: Advanced loading ---

## tutorial/04-advanced-sveltekit/05-advanced-loading/01-universal-load-functions/index.md

--- title: Universal load functions --- In the [previous section on loading](page-data) we loaded data from the server using `+page.server.js` and `+layout.server.js` files. This is very convenient if you need to do things like getting data directly from a database, or reading cookies. Sometimes it doesn't make sense to load data from the server when doing a client-side navigation. For example: - You're loading data from an external API - You want to use in-memory data if it's available - You want to delay navigation until an image has been preloaded, to avoid pop-in - You need to return something from `load` that can't be serialized (SvelteKit uses [devalue](https://github.com/Rich-Harris/devalue) to turn server data into JSON), such as a component or a store In this exercise, we're dealing with the latter case. The server `load` functions in `src/routes/red/+page.server.js`, `src/routes/green/+page.server.js` and `src/routes/blue/+page.server.js` return a `component` constructor, which can't be serialized like data. If you navigate to `/red`, `/green` or `/blue`, you'll see a 'Data returned from `load` ... is not serializable' error in the terminal. To turn the server `load` functions into universal `load` functions, rename each `+page.server.js` file to `+page.js`. Now, the functions will run on the server during server-side rendering, but will also run in the browser when the app hydrates or the user performs a client-side navigation. We can now use the `component` returned from these `load` functions like any other value, including in `src/routes/+layout.svelte`: ```svelte /// file: src/routes/+layout.svelte <nav class:has-color={!!$page.data.color} style:background={$page.data.color ?? 'var(--bg-2)'} > <a href="/">home</a> <a href="/red">red</a> <a href="/green">green</a> <a href="/blue">blue</a> {#if $page.data.component} {@const Component = $page.data.component} <Component /> {/if} </nav> ``` Read the [documentation](/docs/kit/load#Universal-vs-server) to learn more about the distinction between server `load` functions and universal `load` functions, and when to use which.

## tutorial/04-advanced-sveltekit/05-advanced-loading/02-using-both-load-functions/index.md

--- title: Using both load functions --- Occasionally, you might need to use a server load function and a universal load function together. For example, you might need to return data from the server, but also return a value that can't be serialized as server data. In this example we want to return a different component from `load` depending on whether the data we got from `src/routes/+page.server.js` is `cool` or not. We can access server data in `src/routes/+page.js` via the `data` property: ```js /// file: src/routes/+page.js export async function load({ data }) { const module =data.cool ? await import('./CoolComponent.svelte') : await import('./BoringComponent.svelte'); return { component: module.default, message:data.message }; } ```

## tutorial/04-advanced-sveltekit/05-advanced-loading/03-await-parent/index.md

--- title: Using parent data --- As we saw in the introduction to [layout data](/tutorial/kit/layout-data), `+page.svelte` and `+layout.svelte` components have access to everything returned from their parent `load` functions. Occasionally it's useful for the `load` functions themselves to access data from their parents. This can be done with `await parent()`. To show how it works, we'll sum two numbers that come from different `load` functions. First, return some data from `src/routes/+layout.server.js`: ```js /// file: src/routes/+layout.server.js export function load() { return {a: 1}; } ``` Then, get that data in `src/routes/sum/+layout.js`: ```js /// file: src/routes/sum/+layout.js export async function load({ parent }) { const { a } = await parent(); return {b: a + 1}; } ``` Finally, in `src/routes/sum/+page.js`, get parent data from both `load` functions: ```js /// file: src/routes/sum/+page.js export async function load({ parent }) { const { a, b } = await parent(); return {c: a + b}; } ```

## tutorial/04-advanced-sveltekit/05-advanced-loading/04-invalidation/index.md

--- title: Invalidation path: /Europe/London --- When the user navigates from one page to another, SvelteKit calls your `load` functions, but only if it thinks something has changed. In this example, navigating between timezones causes the `load` function in `src/routes/[...timezone]/+page.js` to re-run because `params.timezone` is invalid. But the `load` function in `src/routes/+layout.js` does _not_ re-run, because as far as SvelteKit is concerned it wasn't invalidated by the navigation. We can fix that by manually invalidating it using the [`invalidate(...)`](/docs/kit/$app-navigation#invalidate) function, which takes a URL and re-runs any `load` functions that depend on it. Because the `load` function in `src/routes/+layout.js` calls `fetch('/api/now')`, it depends on `/api/now`. In `src/routes/[...timezone]/+page.svelte`, add an `onMount` callback that calls `invalidate('/api/now')` once a second: ```svelte /// file: src/routes/[...timezone]/+page.svelte <script> import { onMount } from 'svelte'; import { invalidate } from '$app/navigation'; let { data } = $props(); onMount(() => { const interval = setInterval(() => { invalidate('/api/now'); }, 1000); return () => { clearInterval(interval); }; }); </script> <h1> {new Intl.DateTimeFormat([], { timeStyle: 'full', timeZone: data.timezone }).format(new Date(data.now))} </h1> ```

## tutorial/04-advanced-sveltekit/05-advanced-loading/05-custom-dependencies/index.md

--- title: Custom dependencies path: /Europe/London --- Calling `fetch(url)` inside a `load` function registers `url` as a dependency. Sometimes it's not appropriate to use `fetch`, in which case you can specify a dependency manually with the [`depends(url)`](/docs/kit/load#Rerunning-load-functions-Manual-invalidation) function. Since any string that begins with an `[a-z]+:` pattern is a valid URL, we can create custom invalidation keys like `data:now`. Update `src/routes/+layout.js` to return a value directly rather than making a `fetch` call, and add the `depends`: ```js /// file: src/routes/+layout.js export async function load({depends}) { depends('data:now'); return { now:Date.now() }; } ``` Now, update the `invalidate` call in `src/routes/[...timezone]/+page.svelte`: ```svelte /// file: src/routes/[...timezone]/+page.svelte <script> import { onMount } from 'svelte'; import { invalidate } from '$app/navigation'; let { data } = $props(); onMount(() => { const interval = setInterval(() => { invalidate('data:now'); }, 1000); return () => { clearInterval(interval); }; }); </script> ```

## tutorial/04-advanced-sveltekit/05-advanced-loading/06-invalidate-all/index.md

--- title: invalidateAll path: /Europe/London --- Finally, there's the nuclear option — `invalidateAll()`. This will indiscriminately re-run all `load` functions for the current page, regardless of what they depend on. Update `src/routes/[...timezone]/+page.svelte` from the previous exercise: ```svelte /// file: src/routes/[...timezone]/+page.svelte <script> import { onMount } from 'svelte'; import {invalidateAll} from '$app/navigation'; let { data } = $props(); onMount(() => { const interval = setInterval(() => { invalidateAll(); }, 1000); return () => { clearInterval(interval); }; }); </script> ``` The `depends` call in `src/routes/+layout.js` is no longer necessary: ```js /// file: src/routes/+layout.js export async function load({ depends }) { depends('data:now'); return { now: Date.now() }; } ```

## tutorial/04-advanced-sveltekit/06-environment-variables/index.md

--- title: Environment variables ---

## tutorial/04-advanced-sveltekit/06-environment-variables/01-env-static-private/index.md

--- title: $env/static/private --- Environment variables — like API keys and database credentials — can be added to a `.env` file, and they will be made available to your application. > > Environment variables in `process.env` are also available via `$env/static/private`. In this exercise, we want to allow the user to enter the website if they know the correct passphrase, using an environment variable. First, in `.env`, add a new environment variable: ```env /// file: .env PASSPHRASE="open sesame" ``` Open `src/routes/+page.server.js`. Import `PASSPHRASE` from `$env/static/private` and use it inside the [form action](/tutorial/kit/the-form-element): ```js /// file: src/routes/+page.server.js import { redirect, fail } from '@sveltejs/kit'; import { PASSPHRASE } from '$env/static/private'; export function load({ cookies }) { if (cookies.get('allowed')) { redirect(307, '/welcome'); } } export const actions = { default: async ({ request, cookies }) => { const data = await request.formData(); if (data.get('passphrase') ===PASSPHRASE) { cookies.set('allowed', 'true', { path: '/' }); redirect(303, '/welcome'); } return fail(403, { incorrect: true }); } }; ``` The website is now accessible to anyone who knows the correct passphrase. ## Keeping secrets It's important that sensitive data doesn't accidentally end up being sent to the browser, where it could easily be stolen by hackers and scoundrels. SvelteKit makes it easy to prevent this from happening. Notice what happens if we try to import `PASSPHRASE` into `src/routes/+page.svelte`: ```svelte /// file: src/routes/+page.svelte <script> import { PASSPHRASE } from '$env/static/private'; let { form } = $props(); </script> ``` An error overlay pops up, telling us that `$env/static/private` cannot be imported into client-side code. It can only be imported into server modules: - `+page.server.js` - `+layout.server.js` - `+server.js` - any modules ending with `.server.js` - any modules inside `src/lib/server` In turn, these modules can only be imported by _other_ server modules. ## Static vs dynamic The `static` in `$env/static/private` indicates that these values are known at build time, and can be _statically replaced_. This enables useful optimisations: ```js import { FEATURE_FLAG_X } from '$env/static/private'; if (FEATURE_FLAG_X === 'enabled') { // code in here will be removed from the build output // if FEATURE_FLAG_X is not enabled } ``` In some cases you might need to refer to environment variables that are _dynamic_ — in other words, not known until we run the app. We'll cover this case in the next exercise.

## tutorial/04-advanced-sveltekit/06-environment-variables/02-env-dynamic-private/index.md

--- title: $env/dynamic/private --- If you need to read the values of environment variables when the app runs, as opposed to when the app is built, you can use `$env/dynamic/private` instead of `$env/static/private`: ```js /// file: src/routes/+page.server.js import { redirect, fail } from '@sveltejs/kit'; import {env} from '$env/dynamic/private'; export function load({ cookies }) { if (cookies.get('allowed')) { redirect(307, '/welcome'); } } export const actions = { default: async ({ request, cookies }) => { const data = await request.formData(); if (data.get('passphrase') ===env.PASSPHRASE) { cookies.set('allowed', 'true', { path: '/' }); redirect(303, '/welcome'); } return fail(403, { incorrect: true }); } }; ```

## tutorial/04-advanced-sveltekit/06-environment-variables/03-env-static-public/index.md

--- title: $env/static/public --- Some environment variables _can_ be safely exposed to the browser. These are distinguished from private environment variables with a `PUBLIC_` prefix. Add values to the two public environment variables in `.env`: ```env /// file: .env PUBLIC_THEME_BACKGROUND="steelblue" PUBLIC_THEME_FOREGROUND="bisque" ``` Then, import them into `src/routes/+page.svelte`: ```svelte /// file: src/routes/+page.svelte <script> const PUBLIC_THEME_BACKGROUND = 'white'; const PUBLIC_THEME_FOREGROUND = 'black'; import { PUBLIC_THEME_BACKGROUND, PUBLIC_THEME_FOREGROUND } from '$env/static/public'; </script> ```

## tutorial/04-advanced-sveltekit/06-environment-variables/04-env-dynamic-public/index.md

--- title: $env/dynamic/public --- As with [private environment variables](/tutorial/kit/env-static-private), it's preferable to use static values if possible, but if necessary we can use dynamic values instead: ```svelte /// file: src/routes/+page.svelte <script> import {env} from '$env/dynamic/public'; </script> <main style:background={env.PUBLIC_THEME_BACKGROUND} style:color={env.PUBLIC_THEME_FOREGROUND} > {env.PUBLIC_THEME_FOREGROUND} on {env.PUBLIC_THEME_BACKGROUND} </main> ```

## tutorial/04-advanced-sveltekit/07-conclusion/index.md

--- title: Conclusion ---

## tutorial/04-advanced-sveltekit/07-conclusion/01-next-steps/index.md

--- title: Next steps --- Congratulations! If you've made it the entire way through this tutorial, you can now consider yourself a Svelte and SvelteKit expert. You can start building apps on your own machine with [Svelte CLI](https://www.npmjs.com/package/sv): ```bash npx sv create ``` Svelte and SvelteKit will continue to evolve, and so will this tutorial. Check back periodically for updates. To keep up with developments in the Svelte world, join our Discord server at [svelte.dev/chat](https://svelte.dev/chat) and follow [Svelte Society](https://twitter.com/sveltesociety) on Twitter. We're so happy to welcome you to the Svelte community!

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

--- NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-docs/index.ts title: Runes ---

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

--- NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-docs/index.ts 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

--- NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-docs/index.ts title: $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. 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 // @filename: ambient.d.ts declare global { const todos: Array<{ done: boolean, text: string }> } // @filename: index.js //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 You can also use `$state` in class fields (whether public or private): ```js // @errors: 7006 2554 class Todo { done = $state(false); text = $state(); constructor(text) { this.text = 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); text = $state(); constructor(text) { this.text = text; } reset = () => { this.text = ''; this.done = false; } } ``` ## `$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). ## `$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`. ## 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.

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

--- NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-docs/index.ts title: $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).

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

--- NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-docs/index.ts title: $effect --- Effects are what make your application _do things_. 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. Most of the effects in a Svelte app are created by Svelte itself — they're the bits that update the text in `<h1>hello {name}!</h1>` when `name` changes, for example. But you can also create your own effects with the `$effect` rune, which is useful when you need to synchronize an external system (whether that's a library, or a `<canvas>` element, or something across a network) with state inside your Svelte app. 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 ([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" /> ``` 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 place `$effect` anywhere, not just at the top level of a component, as long as it is called during component initialization (or while a parent effect is active). It is then tied to the lifecycle of the component (or parent effect) and will therefore destroy itself when the component unmounts (or the parent effect is destroyed). You can return a function from `$effect`, which will run immediately before the effect re-runs, and before it is destroyed ([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 callback 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> ``` ### Understanding dependencies `$effect` automatically picks up any reactive values (`$state`, `$derived`, `$props`) that are _synchronously_ read inside its function body and registers them as dependencies. When those dependencies change, the `$effect` schedules a rerun. 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. If `a` is true, changes to `b` will [not cause this effect to rerun](/REMOVED): ```ts let a = false; let b = false; //cut $effect(() => { console.log('running'); if (a || b) { console.log('inside if block'); } }); ``` ## `$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> ``` This allows you to (for example) add things like subscriptions without causing memory leaks, by putting them in child effects. Here's a `readable` function that listens to changes from a callback function as long as it's inside a tracking context: ```ts import { tick } from 'svelte'; export default function readable<T>( initial_value: T, start: (callback: (update: (v: T) => T) => T) => () => void ) { let value = $state(initial_value); let subscribers = 0; let stop: null | (() => void) = null; return { get value() { // If in a tracking context ... if ($effect.tracking()) { $effect(() => { // ...and there's no subscribers yet... if (subscribers === 0) { // ...invoke the function and listen to changes to update state stop = start((fn) => (value = fn(value))); } subscribers++; // The return callback is called once a listener unlistens return () => { tick().then(() => { subscribers--; // If it was the last subscriber... if (subscribers === 0) { // ...stop listening to changes stop?.(); stop = null; } }); }; }); } return value; } }; } ``` ## `$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. ```svelte <script> let count = $state(0); const cleanup = $effect.root(() => { $effect(() => { console.log(count); }); return () => { console.log('effect root cleanup'); }; }); </script> ``` ## 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> ``` 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> let 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 callbacks where possible ([demo](/REMOVED)): ```svelte <script> let total = 100; let spent = $state(0); let left = $state(total); function updateSpent(e) { spent = +e.target.value; left = total - spent; } function updateLeft(e) { left = +e.target.value; spent = total - left; } </script> <label> <input type="range" value={spent} oninput={updateSpent} max={total} /> {spent}/{total} spent </label> <label> <input type="range" value={left} oninput={updateLeft} max={total} /> {left}/{total} left </label> ``` If you need to use bindings, for whatever reason (for example when you want some kind of "writable `$derived`"), consider using getters and setters to synchronise state ([demo](/REMOVED)): ```svelte <script> let total = 100; let spent = $state(0); let left = { get value() { return total - spent; }, set value(v) { spent = total - v; } }; </script> <label> <input type="range" bind:value={spent} max={total} /> {spent}/{total} spent </label> <label> <input type="range" bind:value={left.value} max={total} /> {left.value}/{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

--- NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-docs/index.ts title: $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: ```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> ``` Adding types is recommended, as it ensures that people using your component can easily discover which props they should provide.

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

--- NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-docs/index.ts 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, 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 /// 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

--- NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-docs/index.ts title: $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} /> ``` ## $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> ``` A convenient way to find the origin of some change is to pass `console.trace` to `with`: ```js // @errors: 2304 $inspect(stuff).with(console.trace); ```

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

--- NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-docs/index.ts title: $host --- When compiling a component as a custom element, 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> ```

Instructions for LLMs: <SYSTEM>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.</SYSTEM>