hirogakatageri/svelte-core

Svelte 5 — Core Knowledge

Authoritative reference for writing modern Svelte 5 components and reactive modules. Read this in full before touching any .svelte / .svelte.ts / .svelte.js file.

File Types

• .svelte — a component. Has <script>, markup, and <style> blocks.
• .svelte.ts / .svelte.js — a reactive module. The compiler transforms runes here too. Use these for shared reactive state and reusable reactive logic.
• .ts / .js — plain modules. Runes are NOT transformed here. Don't use $state etc. in plain .ts files; rename to .svelte.ts if you need reactivity.

Component Anatomy

<script lang="ts">
  // imports, props, state, derived, effects, functions
  let { name = 'world' }: { name?: string } = $props();
  let count = $state(0);
  let doubled = $derived(count * 2);
</script>

<h1>Hello {name}</h1>
<button onclick={() => count++}>{doubled}</button>

<style>
  h1 { color: tomato; }
</style>

A component is its file. Each .svelte file exports one component as the default export. To export named values, use <script module>:

<script module lang="ts">
  export const VERSION = '1.0';
</script>
<script lang="ts">
  // instance script
</script>

<script module> runs once when the module is first evaluated. The instance <script> runs per component instance.

Runes

Runes are compiler primitives. They look like functions but are syntax — don't import them. Always use parentheses ($state(0), not $state 0).

$state

Creates reactive state.

<script>
  let count = $state(0);
  let todos = $state([{ done: false, text: 'add more todos' }]);
</script>

• Objects and arrays are made into deeply-reactive proxies. Mutating nested properties (todos[0].done = true) and array methods (push, splice) trigger updates.
• Class instances are NOT proxied. Use $state on class fields instead:

  class Todo {
    done = $state(false);
    text = $state('');
  }
  

• Destructuring loses reactivity: let { done } = todos[0] captures the value at that moment.
• $state.raw(value) — non-reactive container. Mutations are ignored; only reassignment triggers updates. Use for large arrays/objects you replace wholesale.
• $state.snapshot(proxy) — returns a plain (non-proxy) deep clone. Use when passing state to libraries that don't expect proxies (structuredClone, JSON.stringify works without it but some APIs choke).

$derived

Computed reactive values.

<script>
  let count = $state(0);
  let doubled = $derived(count * 2);
  let total = $derived.by(() => {
    let sum = 0;
    for (const n of items) sum += n;
    return sum;
  });
</script>

• Expression must be side-effect-free. Don't mutate state inside.
• Dependencies are auto-tracked: any state read synchronously inside the expression.
• Use $derived.by(() => { ... }) when you need statements (loops, conditionals, multiple lines).
• Deriveds can be temporarily overridden by reassignment (Svelte 5.25+). Useful for optimistic UI:

  let likes = $derived(post.likes);
  async function like() {
    likes += 1;            // optimistic
    try { await api.like(); } catch { likes -= 1; }
  }
  

• Push-pull reactivity: deriveds re-evaluate lazily when read; downstream updates skip if the result is referentially identical.

$effect

Side effects that run after the DOM updates.

<script>
  let canvas = $state();
  let color = $state('red');

  $effect(() => {
    const ctx = canvas.getContext('2d');
    ctx.fillStyle = color;
    ctx.fillRect(0, 0, 100, 100);

    return () => ctx.clearRect(0, 0, 100, 100); // optional cleanup
  });
</script>

• Tracks any state read synchronously inside the function.
• Re-runs on dependency change. Cleanup function runs before next run and on destroy.
• $effect.pre(...) — runs before DOM updates. Useful for measuring layout pre-mutation.
• $effect.tracking() — boolean, true if currently inside a tracked context.
• $effect.root(() => { ... }) — escape the parent effect's lifecycle; returns a manual disposer.
• Don't use $effect to derive state. If you find yourself doing $effect(() => { other = base * 2 }), use $derived instead.
• Effects are component-scoped. Top-level $effect outside a component or .svelte.* module errors.

$props

Reads component inputs.

<script lang="ts">
  let { adjective = 'cool', children, ...rest }: {
    adjective?: string;
    children?: import('svelte').Snippet;
  } = $props();
</script>

• Always destructure with defaults inline. Renaming works ({ super: trouper } = $props()).
• Rest props (...rest) capture everything else.
• Don't mutate props. Pass callback props for changes, or use $bindable for shared state.
• $props.id() — stable ID unique per component instance, SSR-safe. Use for for/aria-labelledby.

$bindable

Marks a prop as two-way bindable from the parent.

<!-- Input.svelte -->
<script lang="ts">
  let { value = $bindable('') }: { value?: string } = $props();
</script>
<input bind:value />

<!-- Parent.svelte -->
<script>
  let name = $state('');
</script>
<Input bind:value={name} />

Only mark props bindable when two-way binding is genuinely needed; default to one-way + callbacks.

$inspect

Dev-time debugging — logs when tracked values change.

$inspect(count);                     // logs on every change
$inspect(count).with(console.trace); // custom logger

Stripped from production builds.

$host

Inside a custom element, returns the host element. Use for dispatching CustomEvents in Svelte custom elements.

Sharing State Across Modules

In .svelte.ts / .svelte.js:

// counter.svelte.ts — DON'T export reassigned state
export let count = $state(0);   // wrong — reads on the importing side won't be reactive

Two correct patterns:

// 1. Export an object whose properties you mutate
export const counter = $state({ count: 0 });
export function increment() { counter.count += 1; }

// 2. Export getters/functions, keep state private
let count = $state(0);
export function getCount() { return count; }
export function increment() { count += 1; }

Pass-by-value also applies inside the same module — passing count to a function passes the current value, not a live reference. For "pass a live state", pass a getter () => count or an object whose property you read.

Markup

Text expressions

<p>Hello {name}!</p>
<p>{a + b} = {a} + {b}</p>

Attributes

<button disabled={busy} class={['btn', { active: isActive }]}>Go</button>
<input {value} />                 <!-- shorthand: same as value={value} -->
<div {...attrs}></div>            <!-- spread -->

Events

Use HTML event attributes, not the legacy on: directive:

<button onclick={handleClick}>Click</button>
<input oninput={(e) => value = e.currentTarget.value} />

There are no event modifiers in runes mode. Implement preventDefault, stopPropagation, once etc. inside the handler:

<form onsubmit={(e) => { e.preventDefault(); save(); }}>

For capture phase, suffix the attribute: onclickcapture.

Control flow

{#if user}
  <p>Hi {user.name}</p>
{:else if guest}
  <p>Welcome guest</p>
{:else}
  <p>Sign in</p>
{/if}

{#each items as item, i (item.id)}
  <li>{i}: {item.text}</li>
{:else}
  <li>Empty</li>
{/each}

{#await promise}
  <p>Loading…</p>
{:then value}
  <p>{value}</p>
{:catch err}
  <p>Error: {err.message}</p>
{/await}

{#key id}
  <Component />          <!-- destroyed and re-created when `id` changes -->
{/key}

The keyed each ((item.id)) is important — without a key, Svelte uses index-based diffing, which animations and transitions need to track identity.

Snippets and {@render}

Snippets are reusable markup chunks. They replace slots in Svelte 5.

<!-- Define -->
{#snippet row(item)}
  <tr><td>{item.name}</td><td>{item.price}</td></tr>
{/snippet}

<!-- Render -->
<table>
  {#each items as item}
    {@render row(item)}
  {/each}
</table>

Children of a component become a snippet named children:

<!-- Card.svelte -->
<script>
  let { children } = $props();
</script>
<div class="card">{@render children?.()}</div>

<!-- Usage -->
<Card>Hello</Card>

Pass named snippet props by writing them as children with #snippet:

<DataTable {items}>
  {#snippet header()}<tr><th>Name</th></tr>{/snippet}
  {#snippet row(item)}<tr><td>{item.name}</td></tr>{/snippet}
</DataTable>

Type a snippet prop with import type { Snippet } from 'svelte':

let { row }: { row: Snippet<[Item]> } = $props();

Other markup tags

• {@html string} — inject raw HTML. Sanitize first; XSS risk.
• {@const name = expr} — declare a constant inside a block (e.g., inside {#each}).
• {@debug var1, var2} — pause in devtools when listed values change.
• {@attach fn} — attach an action-like function to an element (see svelte-advanced).

Bindings

<input bind:value={name} />
<input type="checkbox" bind:checked={agreed} />
<input type="number" bind:valueAsNumber={age} />
<input type="file" bind:files />
<select bind:value={selected}>...</select>
<textarea bind:value={text} />

<video bind:duration bind:currentTime bind:paused>...</video>

<div bind:clientWidth={w} bind:clientHeight={h}>...</div>
<div bind:this={el}>...</div>

Function bindings (Svelte 5):

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

class and style directives

<div class={['btn', { active, large: size === 'lg' }]}>...</div>
<div style:color={theme.primary} style:--gap="8px">...</div>

class accepts strings, arrays, or objects (truthy keys become classes) — same convention as clsx.

use: actions and {@attach}

<div use:tooltip={'Hello'}>...</div>

In Svelte 5, prefer attachments via {@attach} for new code (see svelte-advanced). Existing use: actions still work.

Scoped Styles

Styles in <style> are scoped to the component — Svelte adds a hash class.

<style>
  p { color: tomato; }            /* only this component's <p> */
  :global(body) { margin: 0; }    /* escape hatch */
  :global(.theme-dark) p { color: #ddd; }
</style>

• :global(selector) opts out of scoping.
• Custom CSS properties pass naturally through scoped styles, so they're the right tool for theming.
• Nested <style> rules (CSS nesting) work.
• Keyframes are scoped by default; use -global- prefix to expose: @keyframes -global-spin {}.

To pass styles into a component, use CSS custom properties:

<!-- Slider.svelte -->
<style>
  .track { background: var(--slider-bg, #eee); }
</style>
<!-- Usage -->
<Slider --slider-bg="lightblue" />

Lifecycle

In runes mode, the lifecycle is mostly expressed through $effect. The classic helpers from svelte still exist:

• onMount(fn) — runs once after first render (client-only). Returning a function gives a teardown that runs on destroy.
• onDestroy(fn) — runs when the component is destroyed (server and client).
• tick() — returns a promise that resolves once pending state changes have applied to the DOM.
• untrack(fn) — read state without registering it as a dependency.

Prefer $effect(() => { ... return () => cleanup(); }) for new code; reach for onMount only when you need the "mounted exactly once on the client" semantics specifically.

Context

For passing values down the component tree without prop-drilling.

import { setContext, getContext } from 'svelte';

// Parent
const theme = $state({ mode: 'dark' });
setContext('theme', theme);

// Child (any depth)
const theme = getContext<{ mode: string }>('theme');

Use a unique key (a Symbol is safest) for non-public contexts. Context is set at component init time — once set, it can't be changed by the same component (but the value can be a reactive object, which is the usual pattern for shared state).

Stores (legacy)

Pre-runes stores from svelte/store (writable, readable, derived) still work and integrate with runes via the $store auto-subscription syntax. Use them when:

• The codebase already uses them and you're matching the pattern.
• You need RxJS-style observables or manual subscription control.

For new code in a Svelte 5 project, prefer $state in .svelte.ts modules over writable.

Common Mistakes to Avoid

1. Reassigning a class field decorated with $state from outside the class — use methods instead.
2. Using $: reactive statements in runes mode — they're a Svelte 4 feature. Use $derived or $effect.
3. Using export let in runes mode — use $props().
4. Using on:click in runes mode — use onclick.
5. Mutating a non-$state object expecting reactivity — only state declared with $state is reactive.
6. Effects deriving state — that's what $derived is for.
7. Putting runes in .ts files — rename to .svelte.ts.
8. Destructuring reactive state and expecting the locals to update — destructuring captures values; keep the access path (obj.prop) instead.