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() vs $state.raw()

$state() for deep reactivity (objects are proxied — mutation triggers updates, but with performance overhead). $state.raw() for data replaced wholesale (no proxy, better for large objects).

When to use $state.raw():

- API responses (replaced entirely on each fetch) - ReadonlyArray collections replaced via spread ($state.raw([])) - Large objects where deep tracking is wasteful - Immutable data structures - Objects from external libraries

When to use $state():

- Form state with individual field updates - UI state (toggles, selections, counters) - Objects you'll mutate property-by-property

The $state()! Non-null Assertion Pattern

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

Used in fuz_ui state classes (ThemeState, SelectedStyleVariable) and zzz Cell subclasses. Library and Module use the variant $state.raw()! for data replaced wholesale.

Arrays and Collections

$state.snapshot()

Returns a plain (non-reactive) snapshot of a $state proxy. Used in zzz's Cell base class for JSON serialization:

Use when you need to pass reactive state to non-reactive APIs (e.g., structuredClone, JSON.stringify, or external libraries that don't understand Svelte proxies).

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 $derived and $derived.by() directly:

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.

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 Cell base class that automates JSON hydration from Zod schemas:

Key patterns:

- Zod schema defines the JSON shape (see ./zod-schemas) - Class properties use $state()! for reactivity (non-null assertion) - $derived / $derived.by() for computed values in classes - $state.raw() for properties replaced wholesale - toJSON() or to_json() for serialization (zzz Cell uses a $derived json property)

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.

Common Contexts

fuz_ui contexts:

| Context | Type | Source file | Purpose | | ---------------------------------- | ---------------------------- | ---------------------------------- | -------------------------------- | | theme_state_context | () => ThemeState | theme_state.svelte.ts | Theme state (getter pattern) | | library_context | Library | library.svelte.ts | Package API metadata for docs | | tomes_context | () => Map<string, Tome> | tome.ts | Available documentation tomes | | tome_context | () => Tome | tome.ts | Current documentation page | | docs_links_context | DocsLinks | docs_helpers.svelte.ts | Documentation navigation | | section_depth_context | number | TomeSection.svelte | Heading depth (fallback: 0) | | register_section_header_context | RegisterSectionHeader | TomeSection.svelte | Register section header callback | | section_id_context | string \| undefined | TomeSection.svelte | Current section ID | | contextmenu_context | () => ContextmenuState | contextmenu_state.svelte.ts | Context menu state (getter) | | contextmenu_submenu_context | SubmenuState | contextmenu_state.svelte.ts | Current submenu state | | contextmenu_dimensions_context | Dimensions | contextmenu_state.svelte.ts | Context menu positioning | | selected_variable_context | SelectedStyleVariable | style_variable_helpers.svelte.ts | Style variable selection | | mdz_components_context | MdzComponents | mdz_components.ts | Custom mdz components | | mdz_elements_context | MdzElements | mdz_components.ts | Allowed HTML elements in mdz | | mdz_base_context | () => string \| undefined | mdz_components.ts | Base path for mdz links |

zzz contexts:

| Context | Type | Source file | Purpose | | -------------------- | ---------- | -------------------- | ----------------- | | frontend_context | Frontend | frontend.svelte.ts | Application state |

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

ThemeRoot and Dialog pass data back via parameterized children:

Named Snippets

Snippets with Parameters

Default Snippet Content

Icon as String or Snippet

Card accepts icons as string (emoji) or Snippet:

Alert uses a richer variant — the Snippet receives the resolved icon string, and null hides the icon:

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, timers, or listeners:

$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 and .svelte.ts files. Returns cleanup:

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.

Factory Functions with Getter/Setter Proxies

Reactive State Classes

The most common pattern for shared state:

Effect Helpers

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

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

| Pattern | Use Case | | -------------------- | --------------------------------------------- | | $state() | Mutable UI state, form data, class properties | | $state()! | Class properties initialized by constructor | | $state.raw() | API responses, ReadonlyArrays, immutable data | | $state.snapshot() | Plain copy of reactive state for serialization | | $derived | Simple computed values, class properties | | $derived.by() | Complex logic, loops, conditionals | | $effect | Side effects, subscriptions | | $effect.pre() | Before DOM update, dev-mode validation | | effect_with_count | Skip initial effect run | | untrack() | Read without tracking | | $inspect.trace() | Debug dependency tracking in effects/derived | | $props() | Component inputs (const or let) | | $bindable() | Two-way binding props (requires let) | | {#snippet} | Named content areas | | {@render} | Render snippets | | {@attach} | DOM element behaviors (replaces use:) | | create_context | Typed Svelte context | | SvelteMap/Set | Reactive Map/Set collections | | on() (events) | Programmatic event listeners |