{data.post.title}
{@html data.post.content}
Loading {pending} items...
{/if} ``` #### `$props` — Component Props ```svelte{greeting}, {name}!
``` Usage: ```svelteYou typed: {text}
``` #### `$inspect` — Development Debugging `$inspect` logs any reactive value changes in development mode. Has no effect in production builds. ```svelte ``` ##### `$inspect.trace` — Effect Dependency Tracing ```svelte ``` #### `$host` — Custom Element Access For components compiled as custom elements, `$host()` returns the host element (`this`): ```svelteThemed content
Hello, {name}!
The answer is {40 + 2}
Hover me
``` #### Conditionals — `{#if}` ```svelte {#if user.loggedIn}Welcome back, {user.name}!
{:else if user.pending}Verifying your account...
{:else} Please log in {/if} ``` #### Loops — `{#each}` ```svelte {#each items as item}Loading...
{:then user}Hello, {user.name}!
{:catch error}Error: {error.message}
{/await} {#await promise then user}{user.name}
{/await} {#await promise catch error}{error.message}
{/await} ``` #### Snippets — `{#snippet}` and `{@render}` Snippets are reusable template fragments — the Svelte 5 replacement for slots: ```svelte {#snippet greeting(name, formal = false)} {#if formal}Good day, {name}.
{:else}Hey {name}!
{/if} {/snippet} {@render greeting('Alice')} {@render greeting('Dr. Smith', true)} ``` ##### Passing Snippets as Props ```svelte| Name | Score | {/snippet} {#snippet row(r)}{r.name} | {r.score} | {/snippet}
|---|
{title}
{@render children()}This is the card body.
{box.id}: {area}px² ({label})
{/each} ``` #### `{@html}` — Raw HTML ```svelte{@html safe}
```
> [!CAUTION]
> `{@html}` bypasses Svelte's XSS protection. **Never** use it with unsanitized user input. Always use a library like DOMPurify to sanitize HTML before rendering.
#### `{@debug}` — Template Debugging
```svelte
{@debug user}
{user.name}
``` ### 4.6 Directives #### Event Handling Svelte 5 uses standard HTML event attributes: ```svelte hovered = true}
onmouseleave={() => hovered = false}
>Hover me
```
> [!NOTE]
> Svelte 5 uses **direct event attributes** (`onclick`, `oninput`) rather than the legacy `on:click`, `on:input` syntax. Both work during the migration period, but new code should use the native attribute form.
##### Delegated Events
Svelte automatically delegates these events for performance (one listener on the document root instead of per-element):
`beforeinput`, `click`, `change`, `dblclick`, `contextmenu`, `focusin`, `focusout`, `input`, `keydown`, `keyup`, `mousedown`, `mousemove`, `mouseout`, `mouseover`, `mouseup`, `pointerdown`, `pointermove`, `pointerout`, `pointerover`, `pointerup`, `touchend`, `touchmove`, `touchstart`
`touchstart` and `touchmove` are passive by default.
##### Event Modifiers (Legacy)
In legacy mode, `on:event|modifier` syntax is supported:
```svelte
```
#### `bind:` — Two-Way Binding
```svelte
{#each ['apple', 'banana', 'cherry'] as fruit}
{/each}
Content
Content
Content
```
#### `style:` — Dynamic Styles
```svelte
Red text
Sized text
Important!
Mixed
``` #### `use:` — Actions Actions are functions applied to DOM elements. They receive the element and optional parameters, and can return an object with `update` and `destroy` methods: ```javascript // actions.js export function tooltip(element, text) { let tip; function show() { tip = document.createElement('div'); tip.textContent = text; tip.className = 'tooltip'; document.body.appendChild(tip); // position relative to element... } function hide() { tip?.remove(); } element.addEventListener('mouseenter', show); element.addEventListener('mouseleave', hide); return { update(newText) { text = newText; if (tip) tip.textContent = newText; }, destroy() { element.removeEventListener('mouseenter', show); element.removeEventListener('mouseleave', hide); tip?.remove(); } }; } ``` ```svelte ``` #### `transition:`, `in:`, `out:` — Transitions ```svelteFades in and out
Different transitions
Slides
Local only
{#if visible}
Toggle me
{/if} ``` #### `animate:` — List Animations ```svelte {#each items as item (item)}
{item}
{/each}
```
### 4.7 Scoped Styles
CSS inside `
```
#### The `style` attribute on component tags
Pass CSS variables to child components:
```svelte
Styled via CSS variable
``` ### 4.8 Special Elements #### `-
{#each node.children as child}
Title
Subtitle
Something went wrong: {error.message}
{$count}
``` ```javascript // In non-component code import { get } from 'svelte/store'; import { count } from './stores.js'; // Manual subscribe const unsubscribe = count.subscribe(value => { console.log(value); }); unsubscribe(); // clean up // Get current value without subscribing const current = get(count); ``` #### Readable Store ```javascript import { readable } from 'svelte/store'; export const time = readable(new Date(), (set) => { const interval = setInterval(() => set(new Date()), 1000); return () => clearInterval(interval); // cleanup }); ``` #### Derived Store ```javascript import { derived, readable } from 'svelte/store'; const time = readable(new Date(), /* ... */); export const hours = derived(time, $time => $time.getHours()); // Multiple source stores export const summary = derived( [firstName, lastName], ([$first, $last]) => `${$first} ${$last}` ); // Async derived export const data = derived(url, ($url, set) => { fetch($url) .then(r => r.json()) .then(set); }); ``` #### Custom Stores ```javascript import { writable } from 'svelte/store'; function createCart() { const { subscribe, set, update } = writable([]); return { subscribe, add: (item) => update(items => [...items, item]), remove: (id) => update(items => items.filter(i => i.id !== id)), clear: () => set([]), get total() { // Note: this doesn't work reactively as a getter on the store object // Use a derived store for reactive totals } }; } export const cart = createCart(); ``` #### Stores in Runes Mode Stores and runes compose naturally: ```svelte{$local}
``` ### 4.10 Motion (`svelte/motion`) #### `tweened` — Interpolated Values ```svelte ``` Tweened supports numbers, arrays, and objects with numeric values: ```javascript const coords = tweened({ x: 0, y: 0 }, { duration: 300 }); await coords.set({ x: 100, y: 200 }); ``` Options: - `duration` — ms (or function `(from, to) => ms`) - `easing` — easing function from `svelte/easing` - `interpolate` — custom `(from, to) => (t) => value` function - `delay` — ms before starting #### `spring` — Physics-Based Animation ```svelte
🐼
```
You can update spring properties reactively:
```javascript
coords.stiffness = 0.3;
coords.damping = 0.5;
```
### 4.11 Transitions (`svelte/transition`)
#### `fade`
```svelte
Fades
```
Parameters: `delay`, `duration`, `easing`
#### `blur`
```svelte
Blurs
```
Parameters: `delay`, `duration`, `easing`, `opacity`, `amount`
#### `fly`
```svelte
Flies in from above
```
Parameters: `delay`, `duration`, `easing`, `x`, `y`, `opacity`
#### `slide`
```svelte
Slides open/close
```
Parameters: `delay`, `duration`, `easing`, `axis` (`'x'` or `'y'`)
#### `scale`
```svelte
Scales in
```
Parameters: `delay`, `duration`, `easing`, `start`, `opacity`
#### `draw` (SVG only)
```svelte
```
Parameters: `delay`, `speed`, `duration`, `easing`
#### `crossfade` — Shared Element Transitions
```svelte
{#each todoItems as item (item.id)}
Hello, world!
``` #### Transition Events ```svelte console.log('intro started')}
onintroend={() => console.log('intro ended')}
onoutrostart={() => console.log('outro started')}
onoutroend={() => console.log('outro ended')}
>
Content
```
### 4.12 Animation (`svelte/animate`)
#### `flip` — First, Last, Invert, Play
FLIP animations automatically animate list items when they reorder:
```svelte
-
{#each items as item (item)}
- {item} {/each}
Elastic fade
```
### 4.14 Reactive Utilities (`svelte/reactivity`)
Reactive wrappers for built-in JavaScript objects:
```svelte
Now: {now.toLocaleTimeString()}
Map size: {map.size}
URL: {url.href}
``` #### Window Reactive Values (`svelte/reactivity/window`) ```svelteWindow: {$innerWidth} × {$innerHeight} (DPR: {$devicePixelRatio})
``` ### 4.15 Rendering API #### `mount` — Client-Side Rendering ```javascript import { mount } from 'svelte'; import App from './App.svelte'; const app = mount(App, { target: document.getElementById('app'), // required props: { name: 'world' }, // optional anchor: null, // insert before this element context: new Map([['key', 'value']]), // initial context intro: false // animate on initial render }); ``` #### `unmount` — Remove a Component ```javascript import { unmount } from 'svelte'; // Later, when done: unmount(app); ``` #### `hydrate` — SSR Hydration ```javascript import { hydrate } from 'svelte'; import App from './App.svelte'; // Attaches event listeners to server-rendered HTML const app = hydrate(App, { target: document.getElementById('app'), props: { /* must match SSR props */ } }); ``` ### 4.16 Utilities #### `tick()` — Await DOM Updates ```svelte ``` #### `untrack()` — Opt Out of Tracking ```svelte ``` #### `flushSync()` — Synchronous State Flush Force all pending state updates to apply synchronously (useful for testing): ```javascript import { flushSync } from 'svelte'; count++; flushSync(); // DOM is now updated expect(document.querySelector('p').textContent).toBe('1'); ``` #### `fork()` — Off-Screen Preloading (since 5.42) Create a detached copy of the current reactive context for preloading: ```javascript import { fork, mount, unmount } from 'svelte'; const branch = fork(); // Run computations without affecting the main tree const result = await branch.run(() => expensiveComputation()); ``` #### `settled()` — Await All Async Work ```javascript import { settled } from 'svelte'; // After triggering async updates await settled(); // All async operations and state updates are now complete ``` #### `getAbortSignal()` — Reactive AbortSignal Returns an `AbortSignal` that aborts when the current derived value or effect re-runs — perfect for cancelling fetch requests: ```svelte ``` --- ## 5. Common Tasks ### 5.1 Building a Form ```svelte {#if submitted}Thank you! We'll be in touch.
{:else} {/if} ``` ### 5.2 Fetching Data ```svelte {#await userPromise}Loading user {userId}...
{:then user}{user.name}
{user.email}
{:catch error}Failed: {error.message}
{/await} ``` #### Fetch with Cancellation ```svelte {#await results}Searching...
{:then items} {#each items as item}{item.title}
{/each}
{/await}
```
### 5.3 Global State with Runes (`.svelte.js` modules)
Create shared reactive state that works across components:
```javascript
// state/cart.svelte.js
let items = $state([]);
let discount = $state(0);
const total = $derived(
items.reduce((sum, item) => sum + item.price * item.qty, 0) * (1 - discount)
);
export function useCart() {
return {
get items() { return items; },
get total() { return total; },
addItem(item) {
const existing = items.find(i => i.id === item.id);
if (existing) existing.qty++;
else items.push({ ...item, qty: 1 });
},
removeItem(id) {
items = items.filter(i => i.id !== id);
},
applyDiscount(pct) {
discount = pct / 100;
},
clear() {
items = [];
discount = 0;
}
};
}
```
```svelte
{cart.items.length} items
${cart.total.toFixed(2)}
```
### 5.4 Modal Dialog
```svelte
{title}
{@render children()}
Are you sure you want to proceed?
{#each toasts.list as toast (toast.id)}
```
### 5.6 Infinite Scroll
```svelte
{#each items as item (item.id)}
{toast.message}
{/each}
{item.title}
{/each}
{#if loading}
```
### 5.7 Drag and Drop
```svelte
Loading...
{:else if !hasMore}All items loaded.
{/if}-
{#each items as item, i (item)}
- dragstart(e, i)} ondragover={(e) => dragover(e, i)} ondragend={dragend} > {item} {/each}
{#each tabs as tab}
{/each}
{#each tabs as tab}
{#if tab.id === 'overview'}
{/each}
```
### 5.9 Debounced Input
```svelte
Overview content...
{:else if tab.id === 'details'}Details content...
{:else}History content...
{/if}Searching for: {debouncedQuery}
``` ### 5.10 Accordion Component ```svelte {#each items as item, i}
{#if openIndex === i}
{/each}
```
### 5.11 Virtual List (Windowing)
For very large lists, render only visible items:
```svelte
{item.body}
{/if}
scrollTop = e.target.scrollTop}
>
```
### 5.12 Custom Store Pattern — User Session
```javascript
// session.svelte.js
import { writable, derived, get } from 'svelte/store';
const _user = writable(null);
const _token = writable(localStorage.getItem('token'));
export const user = { subscribe: _user.subscribe };
export const isLoggedIn = derived(_user, $u => $u !== null);
export async function login(email, password) {
const res = await fetch('/api/auth/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ email, password })
});
if (!res.ok) throw new Error('Login failed');
const { user: userData, token } = await res.json();
_user.set(userData);
_token.set(token);
localStorage.setItem('token', token);
}
export function logout() {
_user.set(null);
_token.set(null);
localStorage.removeItem('token');
}
export function getAuthHeader() {
const token = get(_token);
return token ? { Authorization: `Bearer ${token}` } : {};
}
```
### 5.13 Routing with SvelteKit
SvelteKit uses a file-based router. Files in `src/routes/` define pages:
```
src/routes/
+page.svelte → /
+layout.svelte → shared layout wrapper
about/
+page.svelte → /about
blog/
+page.svelte → /blog
+page.ts → data loading for /blog
[slug]/
+page.svelte → /blog/my-post
+page.ts → data loading with slug param
api/
users/
+server.ts → /api/users (REST endpoint)
```
Page with data loading:
```typescript
// src/routes/blog/[slug]/+page.ts
import type { PageLoad } from './$types';
export const load: PageLoad = async ({ params, fetch }) => {
const post = await fetch(`/api/posts/${params.slug}`).then(r => r.json());
return { post };
};
```
```svelte
{#each visibleItems as item (item.id)}
{item.text}
{/each}
Count: {counter.count} (Doubled: {counter.doubled})
``` ### 5.15 Server-Side Rendering (SSR) For standalone Svelte (not SvelteKit), use `svelte/server`: ```javascript // server.js import { render } from 'svelte/server'; import App from './App.svelte'; const { head, body } = render(App, { props: { name: 'World' } }); const html = ` ${head} ${body} `; ``` Then hydrate on the client: ```javascript // client.js import { hydrate } from 'svelte'; import App from './App.svelte'; hydrate(App, { target: document.body, props: { name: 'World' } }); ``` ### 5.16 Custom Elements (Web Components) ```svelteHello, {name}!
``` Build it: ```javascript // vite.config.js import { svelte } from '@sveltejs/vite-plugin-svelte'; export default { plugins: [svelte({ compilerOptions: { customElement: true } })], build: { lib: { entry: 'src/my-greeting.svelte', formats: ['es'] } } }; ``` Usage in plain HTML: ```html| {col.label} | {/each} {#if actions}Actions | {/if}
|---|---|
| {row[col.key]} | {/each} {#if actions}{@render actions(row)} | {/if}
| {emptyMessage} |
{@render children()}
{/key}
```
### 5.19 Binding to Media Elements
```svelte
currentTime = e.target.value * duration}
/>
{Math.floor(currentTime)}s / {Math.floor(duration)}s
```
### 5.20 Keyboard Shortcuts
```svelte
visible = isVisible }}
class:visible
>
{visible ? 'I am visible!' : 'Scroll to see me'}
```
### 5.24 Persistent State (localStorage)
```javascript
// persisted.svelte.js
export function persisted(key, initialValue) {
let stored;
try {
const raw = localStorage.getItem(key);
stored = raw ? JSON.parse(raw) : initialValue;
} catch {
stored = initialValue;
}
let value = $state(stored);
$effect(() => {
try {
localStorage.setItem(key, JSON.stringify(value));
} catch {
// Storage full or unavailable
}
});
return {
get value() { return value; },
set value(v) { value = v; }
};
}
```
```svelte
```
### 5.25 Composable Reactive Logic (Custom Hooks)
```javascript
// hooks/useWindowSize.svelte.js
export function useWindowSize() {
let width = $state(window.innerWidth);
let height = $state(window.innerHeight);
function update() {
width = window.innerWidth;
height = window.innerHeight;
}
$effect(() => {
window.addEventListener('resize', update);
return () => window.removeEventListener('resize', update);
});
return {
get width() { return width; },
get height() { return height; }
};
}
```
```svelte
Window: {size.width} × {size.height}
``` ### 5.26 Animation Recipe: Staggered List Entry ```svelte {#each items as item, i (item.id)}
{item.name}
{/each}
```
### 5.27 Optimistic UI Updates
```svelte
{#each todos as todo (todo.id)}
{/each}
```
### 5.28 Accessibility: Focus Management
```svelte
{#if dialogOpen}
e.key === 'Escape' && closeDialog()}
>
{/if}
```
---
## 6. Troubleshooting
### Error: `lifecycle_outside_component`
**Cause:** Calling `onMount`, `onDestroy`, `setContext`, or `getContext` outside of a component's initialization phase. Common in SSR bundlers like Rollup/Rolldown (issue #17027).
**Solution:**
1. Ensure lifecycle calls are at the top level of a `
```
**Prevention:** Always use `bind:muted` rather than the static `muted` attribute on video elements.
---
### Error: `{@const}` with `let:` slot prop causes initialization error (issue #18119)
**Cause:** Using `{@const}` to reference a `let:` slot prop in legacy slot mode causes an initialization ordering error in 5.55.4.
**Solution:**
1. Migrate to the snippets API (`{#snippet}` / `{@render}`) which does not have this issue.
2. If you must use legacy slots, compute the value inline without `{@const}`.
**Prevention:** Prefer the snippets API for all new components.
---
### Style leak with hashed filenames (issue #18092)
**Cause:** When Svelte hashes component styles using filenames and two files have the same name in different directories, their style hashes can collide, causing style leaks between components.
**Solution:**
1. Ensure component filenames are unique across the project.
2. Configure your build tool to use full path-based hashing if supported.
**Prevention:** Avoid naming multiple components identically even in different directories.
---
### `a11y-mouse-events-have-key-events` false positive with focusin/focusout (issue #8089)
**Cause:** Svelte's accessibility linter incorrectly triggers this warning when using `focusin`/`focusout` handlers, even though these are already keyboard-accessible equivalents of `mouseenter`/`mouseleave`.
**Solution:**
Suppress the warning per-component:
```javascript
// svelte.config.js
const config = {
compilerOptions: {
warningFilter: (w) => w.code !== 'a11y_mouse_events_have_key_events'
}
};
```
**Prevention:** This is a known false positive — safe to suppress globally.
---
### Error: `Cannot destructure property 'x' of undefined`
**Cause:** Trying to destructure reactive state before it is initialized, often in a `$derived` that runs before async data loads.
**Solution:**
1. Provide a default value: `let data = $state({ items: [] })`.
2. Use optional chaining: `data?.items ?? []`.
3. Guard with `{#if data}` in the template.
---
### Transition not playing on initial render
**Cause:** By default, `transition:fn` does not play when an element enters on first render (only on subsequent `{#if}` changes).
**Solution:**
Use `in:fn` instead of `transition:fn`, and set `intro: true` in the `mount()` options:
```javascript
mount(App, { target, intro: true });
```
**Prevention:** Use `in:` for entrance-only transitions; set `intro: true` when mount-time animations are needed.
---
### Components not updating after store mutation
**Cause:** Directly mutating an object or array inside a `writable` store without calling `.set()` or `.update()` — stores require explicit notification.
**Solution:**
```javascript
// WRONG — no notification
items.update(v => { v.push(newItem); return v; }); // same reference
// CORRECT — return new reference or use .set
items.update(v => [...v, newItem]); // new array
// or
const current = get(items);
current.push(newItem);
items.set(current); // explicit notification
```
**Prevention:** For deeply reactive objects, prefer `$state` in `.svelte.js` modules over writable stores.
---
### SSR: `window is not defined`
**Cause:** Code that references browser globals (`window`, `document`, `navigator`) running during server-side rendering.
**Solution:**
1. Move browser-only code into `onMount` (which never runs on the server).
2. Guard with `if (typeof window !== 'undefined')`.
3. Use SvelteKit's `browser` check:
```javascript
import { browser } from '$app/environment';
if (browser) { /* browser-only code */ }
```
**Prevention:** Always guard browser-specific APIs behind `onMount` or `browser` checks.
---
### TypeScript: `Type 'X' is not assignable to type 'Y'` on props
**Cause:** Svelte's type inference for `$props()` requires explicit type annotations or the TypeScript inference cannot determine prop types.
**Solution:**
```svelte
```
**Prevention:** Always type-annotate `$props()` in TypeScript components.
---
### `bind:this` returns `undefined` at first render
**Cause:** The element reference is only available after the component mounts. Accessing it synchronously in `
```
**Prevention:** Always access `bind:this` references inside `onMount` or lifecycle functions.
---
### `$effect` does not track all dependencies
**Cause:** Dependencies accessed via `untrack()` or accessed inside a non-tracking callback (like a `setTimeout` callback) are not tracked.
**Solution:**
1. Read all needed reactive values synchronously at the top of the `$effect` body.
2. Avoid accessing reactive state inside `setTimeout`, `Promise.then`, etc.
---
### Hydration mismatch: `hydration_attribute_changed` / `hydration_html_changed`
**Cause:** The server-rendered HTML does not match what the client-side component would render. Common causes: date/time values, random IDs, or different data on client vs. server.
**Solution:**
1. Ensure SSR and client render with identical data.
2. For truly client-only content, wrap in `{#if browser}` or use `onMount`.
3. For unavoidable mismatches, these warnings are ignorable — listed in the suppression table.
**Prevention:** Never generate random values during render. Generate them in `onMount` instead.
---
### `await_waterfall` warning
**Cause:** An `{#await}` block is nested inside another `{#await}` block, creating a sequential waterfall instead of parallel fetches.
**Solution:**
Fetch in parallel using `Promise.all`:
```svelte
```
**Prevention:** Use `Promise.all()` for independent async operations.
---
### Components fail to tree-shake
**Cause:** Using `export { MyComponent }` from a barrel file combined with module-level `
```
**Prevention:** Capture all reactive reads at the beginning of async derived functions.
---
### CSS not applying to child components
**Cause:** Svelte's scoped CSS only applies to elements within the same component file. Child component elements are not styled from the parent's `