Svelte 5 Patterns

Svelte 5 runes and patterns used across the Fuz ecosystem.

Contents

- State Runes - Derived Values - Reactive Collections - Schema-Driven Reactive Classes - Context Patterns - Snippet Patterns - Effect Patterns - Attachment Patterns - Props Patterns - Event Handling - Component Composition - Runes in .svelte.ts Files - Debugging - Each Blocks - CSS in Components - Legacy Features to Avoid - Quick Reference

State Runes

Only use $state for variables that should be reactive — variables that cause an $effect, $derived, or template expression to update. Everything else can be a normal variable.

$state.raw() vs $state() — opt into mutation reactivity, raw otherwise

Principle: be explicit about when you're opting into mutation reactivity. For primitives the two are equivalent (one extra typeof check on set). For objects and arrays, $state() proxies the value so in-place mutations trigger updates; $state.raw() stores the value directly and only tracks reassignment.

Use $state() when you want in-place mutation to trigger reactivity:

- Arrays you push, splice, pop, sort, or index-assign - Objects with individual property mutations - bind:value={obj.field} — binding writes to a property on the object, which needs deep proxy reactivity (binding to a primitive let works either way, since the binding reassigns the variable)

Use $state.raw() for everything else — primitives, values replaced wholesale (filter/spread/reassignment), API responses, data passed to APIs that compare object identity, anything where property-level reactivity isn't wanted.

This is a fuz-stack stylistic preference, not a technical requirement, and diverges from Svelte's official guidance — which defaults to $state() and treats $state.raw as a perf opt-out for large values that are only ever reassigned (API responses and similar). The benefit here is explicit intent — reading a state class tells you which fields are designed to mutate in place. The cost is friction with idiomatic-Svelte reviewers and AI assistants that default to $state().

structuredClone, JSON.stringify, and postMessage all walk through $state() proxies cleanly — proxy traps return the target's own keys. JSON.stringify also calls toJSON() through the proxy.

Watch for const objects: A const object declared with $state.raw() has no way to trigger reactivity — it can't be reassigned and property mutations aren't tracked. If the object's properties are mutated (directly or via bind:), use $state().

Check consumer files, not just the declaring file. A class field may be mutated in place by external code that accesses it — e.g., a component importing a state class and calling thing.items.splice(i, 1). Grep the entire src/ directory for mutation patterns on the field name before deciding.

The $state.raw()! Non-null Assertion Pattern

Class properties initialized by constructor or init() use $state.raw()!:

Used across fuz_ui state classes and zzz Cell subclasses. Use $state()! only for arrays/objects that are mutated in place (see above).

$state.snapshot()

Deep-cloned plain copy of a reactive value. Per Svelte's source: recurses into plain objects and arrays; for class instances with toJSON(), calls it and clones the result; otherwise falls through to structuredClone (which strips class prototypes).

Use it when handing a $state() proxy structure to code that does reference-identity checks on members and would otherwise see proxy identities. $state.raw() values holding plain data don't need it at all. For serialization, JSON.stringify and structuredClone walk through proxies on their own.

Observed quirk (Svelte 5.55 + vite-plugin-svelte): const r = $state.snapshot(x) is silently elided to const r = x somewhere in the toolchain (Svelte's compileModule output is correct, so it's a downstream pass). return $state.snapshot(x) and inline expression use work correctly. zzz Cell's encode_property is the direct-return form, so to_json() is unaffected. If you write const r = $state.snapshot(x) and the snapshot semantics seem missing, this is the cause.

Derived Values

Use $derived to compute from state — never $effect with assignment. Deriveds are writable (assign to override, but the expression re-evaluates on dependency change). Derived objects/arrays are not made deeply reactive.

$derived vs $derived.by()

$derived takes an expression (not a function). $derived.by() for loops, conditionals, or multi-step logic.

$derived in Classes

Class properties use readonly $derived and readonly $derived.by(). Always mark $derived class properties as readonly unless you explicitly need reassignment (which Svelte 5 does allow):

Derived from Props

Treat props as though they will change — use $derived for values that depend on props:

Reactive Collections

SvelteMap and SvelteSet

From svelte/reactivity — reactive Map/Set that trigger updates on mutations:

Standard Map/Set are not tracked by Svelte's reactivity.

For entity streams where the same data is consumed by different lookups, maintain multiple SvelteMap indexes over it — rebuild on snapshot events, update incrementally on delta events. Deriveds then use .get() lookups instead of array scans.

Schema-Driven Reactive Classes

Zod schemas paired with Svelte 5 runes classes — the schema defines the JSON shape, the class adds reactivity and behavior. See ./zod-schemas.

Simple Pattern (fuz_ui)

Cell Pattern (zzz)

Advanced version with a Cell base class that automates JSON hydration from Zod schemas. Same rune conventions ($state.raw()! by default, $state()! for in-place mutations, readonly $derived for computed values). See ./zod-schemas for the full schema/class pattern.

Context Patterns

Creating Context

create_context<T>() from @fuzdev/fuz_ui/context_helpers.js. Two overloads: without fallback, get() throws if unset and get_maybe() returns undefined; with fallback, get() uses it and set() value is optional:

Using Context

Getter Function Context Pattern

Some contexts wrap values in () => T so the context reference stays stable while the value can change:

Used when the context value might be reassigned (e.g., theme_state is a prop). Direct value contexts like frontend_context and library_context are for values stable for the context's lifetime.

For an inventory of contexts in fuz_ui and zzz, grep for create_context< in the source.

Snippet Patterns

Svelte 5 replaces slots with snippets ({#snippet} and {@render}).

The children Snippet

Implicit children replaces the default slot. Typed as Snippet (or Snippet<[params]> with parameters):

Content between component tags becomes children:

Children with Parameters

Children can be parameterized — Dialog passes a close function back to the consumer:

ThemeRoot uses the same pattern with multiple values: Snippet<[theme_state: ThemeState, style: string | null, theme_style_html: string | null]>.

Named Snippets

Snippets with Parameters

Default Snippet Content and String/Snippet Unions

For optional snippets, fall back with {#if snippet} {@render snippet()} {:else} ... {/if}. For props that accept either a string or a snippet (e.g. icon?: string | Snippet), branch on typeof at render. fuz_ui's Card and Alert use this; Alert further parameterizes with Snippet<[icon: string]> to pass the resolved icon back.

Effect Patterns

Effects are an escape hatch — avoid when possible. Prefer:

- $derived / $derived.by() for computing from state - {@attach} for syncing with external libraries or DOM - Event handlers / function bindings for responding to user interaction - $inspect / $inspect.trace() for debugging (not $effect + console.log) - createSubscriber from svelte/reactivity for observing external sources

Don't wrap effect contents in if (browser) {...} — effects don't run on the server. Avoid updating $state inside effects.

Basic Effects

Effect Cleanup

Return a cleanup function for subscriptions or timers:

For window/document listeners, prefer <svelte:window onkeydown={...}> and <svelte:document> over $effect + addEventListener. For element-scoped listeners, prefer {@attach} (with on() from svelte/events inside).

$effect.pre()

Runs before DOM updates. Used for dev-mode validation and scroll management:

effect_with_count()

From @fuzdev/fuz_ui/rune_helpers.svelte.js — passes call count to the effect, useful for skipping the initial run:

untrack()

Read values without creating dependencies:

Use cases: reading config that shouldn't trigger re-runs, accessing stable references, breaking infinite loops in bidirectional syncing.

Attachment Patterns

Svelte 5 attachments ({@attach}) replace actions (use:). Attachments live in *.svelte.ts files and use Attachment from svelte/attachments.

Attachment API

An attachment is (element) => cleanup | void. fuz_ui uses a factory pattern — export a function that accepts configuration and returns the Attachment:

Usage: {@attach my_attachment()} or {@attach my_attachment({...options})}

fuz_ui Attachments

autofocus -- Focus on Mount

Solves the HTML autofocus attribute not working when elements mount from reactive conditionals ({#if}) in SPAs.

intersect -- IntersectionObserver

Wraps IntersectionObserver with a lazy function pattern — reactive callbacks update without recreating the observer.

contextmenu_attachment -- Context Menu Data

Caches context menu params on an element via dataset. Direct params (no lazy function). Returns cleanup that removes the cache entry.

Class Method Attachments (zzz)

Attachments as class properties, sharing reactive state with the instance:

Choosing a Pattern

| Pattern | When to use | Example | | ----------------------------- | ----------------------------------------- | --------------- | | Simple factory | Fire-once, no ongoing observation | autofocus | | Lazy function (() => p) | Reactive callbacks without observer churn | intersect | | Direct params | Static config cached for later retrieval | contextmenu | | Class method | Attachment shares state with a class | Scrollable |

Writing a New Attachment

1. Create src/lib/my_attachment.svelte.ts 2. Export a factory function returning Attachment<HTMLElement | SVGElement> 3. Return cleanup if holding resources (observers, listeners) 4. Use $effect inside for reactive behavior, on() for event listeners 5. Add JSDoc with @module and @param tags

Props Patterns

Basic Props

Bindable Props

Use let (not const) for $bindable() props:

Real examples from fuz_ui:

Rest Props with SvelteHTMLElements

Use SvelteHTMLElements from svelte/elements intersected with custom props:

Use SvelteHTMLElements['div'] (not HTMLAttributes<HTMLDivElement>).

Event Handling

Svelte 5 uses standard DOM event syntax:

Programmatic Event Listeners

on() from svelte/events for programmatic listeners in attachments, .svelte.ts files, and plain .ts modules. Preserves correct ordering relative to declarative handlers that use event delegation. Always prefer on() over addEventListener — even in non-component code. Returns a cleanup function:

swallow — Claiming Events

swallow() from @fuzdev/fuz_util/dom.js combines preventDefault() and stopImmediatePropagation() (or stopPropagation() with immediate: false).

Design principle: handling an event = claiming it. If you call preventDefault, you're already saying "I own this event's default behavior." Use swallow to extend that to "and no one else should react to it either." If a parent needs to observe events before children claim them, use the capture phase explicitly — don't rely on implicit bubbling.

Use swallow whenever you would call preventDefault — the event is yours, stop it from propagating too. For handlers that only need stopPropagation without preventDefault (e.g., preventing game input from seeing keystrokes in a chat input), use e.stopPropagation() directly.

Component Composition

Module Script Block

<script lang="ts" module> for component-level exports (contexts, types):

Forwarding Snippets

Generic Components

Dynamic Elements

svelte:element for components rendering different HTML tags:

Transitions

Runes in .svelte.ts Files

.svelte.ts files use runes ($state, $derived, $effect) outside components. Prefer classes over module-level state — export a class, instantiate once at the appropriate root, and share it via context.

Avoid Module-Level Runes for Shared State

Don't declare $state variables at module scope and expose them through getter/setter objects. A module-level rune is a hidden global: it can't be reset per test, per realm, or per session; it ties the lifetime of the state to the module rather than to a component; and a second instance is impossible when you later decide you need one.

Use a class + context instead — the class owns its state, and a root component sets it once:

When module-level runes are fine: inside a factory function body (see below) — the state is scoped to the returned object, not the module.

Factory Functions with Getter/Setter Proxies

Reactive State Classes

The most common pattern for shared state:

Plain Classes for Imperative Loops

Canvas2D/WebGPU renderers, requestAnimationFrame loops, and long-lived pointer listeners are the inverse case: use a plain class with no runes, mounted by a thin .svelte wrapper. Private fields (e.g. #hovered_id, #cursor_x) stay non-reactive on purpose — mutating them from an rAF tick must not schedule reruns. The wrapper binds dimensions, forwards reactive sources via getter-backed options, and calls destroy() on unmount. Runes live in the wrapper, never in the loop.

Debugging

$inspect.trace()

Add as the first line of an $effect or $derived.by to trace dependencies and discover which one triggered an update:

Each Blocks

Prefer keyed each blocks — Svelte can surgically insert or remove items rather than updating existing DOM:

The key must uniquely identify the object — do not use the array index. Avoid destructuring if you need to mutate the item (e.g., bind:value={item.count}).

CSS in Components

Goal: minimal <style> blocks. Components should delegate styling to fuz_css utility classes and design tokens. Many well-designed components have no <style> block at all. See css-patterns.md §Component Styling Philosophy for the full rationale, anti-patterns, and examples.

When a <style> block is needed, keep it focused on component-specific layout logic (positioning, complex pseudo-states, responsive breakpoints). All values should reference design tokens, not hardcoded pixels or colors.

Class naming: fuz_css utilities use snake_case (p_md, gap_lg). Component-local classes use kebab-case (site-header, nav-links) to distinguish them visually.

JS Variables in CSS

Use style: directive to pass JS values as CSS custom properties:

Styling Child Components

Prefer CSS custom properties. Use :global only when necessary (e.g., third-party components):

Use clsx-style arrays and objects in class attributes instead of class: directive:

Legacy Features to Avoid

Always use runes mode. Deprecated patterns and their replacements:

| Instead of | Use | | ---------------------------------- | --------------------------------------------- | | let count = 0 (implicit) | let count = $state(0) | | $: assignments/statements | $derived / $effect | | export let | $props() | | on:click={...} | onclick={...} | | <slot> | {#snippet} / {@render} | | <svelte:component this={C}> | <C /> (dynamic component directly) | | <svelte:self> | import Self from './Self.svelte' + <Self> | | use:action | {@attach} | | class:active | class={['base', active && 'active']} | | Stores (writable, readable) | Classes with $state fields |

Quick Reference

The decision-fraught choices, summarized:

- $state.raw() vs $state() — $state.raw() for primitives and values replaced wholesale; $state() when you want in-place mutation (push, property writes, bind: on object properties) to trigger reactivity. - $derived vs $derived.by() — $derived takes an expression; $derived.by() takes a function for loops/conditionals/multi-step logic. Mark class-level deriveds readonly. - {@attach} vs $effect — attachments for element behavior (replaces use:action); effects for everything else, but reach for $derived, <svelte:window>, or event handlers first. - create_context<T>() vs raw setContext/getContext — fuz_ui's create_context provides the throw-on-missing get() plus get_maybe(), with optional fallback factory.