$derived rune declares derived state
Derived state is declared with the $derived rune. The expression inside $derived(...) should be free of side-effects. Svelte will disallow state changes inside derived expressions.
Svelte · Language · all subjects
core/runes
108 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
Code in Svelte components executes once at creation
Code in Svelte components is only executed once at creation. Without the $derived rune, a derived variable would maintain its original value even when its dependencies change.
Referentially identical derived values skip downstream updates
If the new value of a derived is referentially identical to its previous value, downstream updates will be skipped. Svelte only updates dependents when the derived value actually changes.
Svelte uses push-pull reactivity
Svelte uses push-pull reactivity: when state is updated, everything that depends on it is immediately notified (the push), but derived values are not re-evaluated until they are actually read (the pull).
Destructuring with $derived creates reactive variables
When using destructuring with a $derived declaration, the resulting variables will all be reactive. This is roughly equivalent to creating separate $derived declarations for each destructured property.
$derived values are not deeply reactive proxies
Unlike $state, which converts objects and arrays to deeply reactive proxies, $derived values are left as-is. Mutating properties of a $derived value will affect the underlying source if that source is deeply reactive.
Prior to Svelte 5.25 deriveds were read-only
In Svelte versions prior to 5.25, derived values could not be reassigned. This changed in Svelte 5.25.
Derived values can be temporarily overridden by reassignment
Derived expressions are recalculated when their dependencies change, but you can temporarily override their values by reassigning them (unless they are declared with const). This is useful for optimistic UI patterns.
untrack exempts state from being a dependency
Use untrack to exempt a piece of state from being treated as a dependency in a $derived expression.
$derived with await tracks state after the await
If a $derived expression contains await, Svelte transforms it such that any state after the await is also tracked, even if it is only read once the awaited value resolves. This applies only to await in the expression itself, not in functions called by the expression.
Dependencies in $derived are tracked synchronously
Anything read synchronously inside the $derived expression or $derived.by function body is considered a dependency. When the state changes, the derived is marked as dirty and recalculated when next read.
$derived.by for complex derivations
$derived.by accepts a function as its argument for creating complex derivations that don't fit inside a short expression. The expression $derived(expression) is equivalent to $derived.by(() => expression).
Use derived values with function bindings instead of effects
For connecting state values where one depends on another, use $derived combined with function bindings on input elements rather than using effects. For example, use bind:value={() => value, updateFunction} instead of updating state in effects.
Avoid infinite loops with effects updating state
Do not use effects to update state that the effect also reads, as this causes infinite loops. If you must update $state within an effect and read the same state, use untrack() to avoid the infinite loop.
Avoid using $effect to synchronise state
$effect is best considered an escape hatch for analytics and direct DOM manipulation. It should not be used frequently to synchronise state. Instead of using $effect to update one state from another, use $derived or $derived.by for simple to complex expressions.
$effect.root creates non-tracked manual scope
The $effect.root rune is an advanced feature that creates a non-tracked scope that doesn't auto-cleanup. It is useful for nested effects you want to manually control and allows creating effects outside of the component initialisation phase. It returns a destroy function that can be called later to clean up.
$effect.pending() counts pending promises
The $effect.pending() rune returns the number of pending promises in the current boundary, not including child boundaries. It is used when components use await to determine how many promises are awaiting.
$effect.tracking() tells if code runs in tracking context
The $effect.tracking() rune is an advanced feature that returns true if the code is running inside a tracking context (such as an effect or inside the template) and false otherwise. It is used to implement abstractions that create listeners only when values are being tracked.
$effect.pre runs before DOM updates
The $effect.pre rune runs code before the DOM updates, unlike $effect which runs after. Apart from timing, $effect.pre works exactly like $effect.
$effect with conditional code only tracks accessed dependencies
An effect only depends on the values it read the last time it ran. With conditional code, if a condition is true and code inside the if block runs, that code's dependencies are tracked. If the condition is false, those dependencies are not tracked and the effect only reruns when the condition changes.
$effect does not track object reassignments, only mutations
An effect only reruns when the object it reads changes, not when a property inside it changes. If state is mutated (e.g., state.value += 1) but the state variable is never reassigned, the effect reading just 'state' will not rerun. An effect reading 'state.value' directly will rerun when the property changes.
$effect teardown function
An effect can return a teardown function that runs immediately before the effect re-runs and when the component is destroyed. Teardown functions also run when the effect is destroyed, which happens when its parent is destroyed or the parent effect re-runs.
$effect lifecycle and timing
Effects run after the component has been mounted to the DOM, in a microtask after state changes. Re-runs are batched, so changing multiple state values in the same moment causes only one effect re-run, which happens after any DOM updates have been applied.
$effect tracks reactive dependencies synchronously
When Svelte runs an effect function, it automatically tracks which pieces of state ($state, $derived, $props) are accessed synchronously inside the effect body (including indirectly via function calls) and registers them as dependencies. When those dependencies change, the effect schedules a re-run. Values read asynchronously after an await or inside setTimeout are not tracked.
$effect rune basic usage
The $effect rune creates functions that run when state updates. Effects are used for side effects like calling third-party libraries, drawing on canvas elements, or making network requests. Effects only run in the browser, not during server-side rendering.
$derived values can be directly overridden
As of Svelte 5.25, derived values can be directly overridden, allowing optimistic UI patterns where you reassign a derived value when needed.
$effect can be used anywhere during parent effect runtime
You can use $effect anywhere in a component, not just at the top level, as long as it is called while a parent effect is running. Svelte uses effects internally to represent template logic and expressions.
Typing snippet props
Snippet props like `children` should be typed using the `Snippet` interface imported from the 'svelte' module.
Props type safety with JSDoc
In JavaScript, add type safety to props using JSDoc type annotations. Example: `/** @type {{ adjective: string }} */ let { adjective } = $props();`
Props type safety with TypeScript
In TypeScript, annotate props by adding a type to the destructured variable. Example: `let { adjective }: { adjective: string } = $props();` You can also define a separate interface and use it as the type annotation.
Non-reactive fallback props
Fallback values for non-bindable props are not converted to reactive state proxies, so mutations to them will not cause component updates.
Props are reactive but should not be mutated
When a prop value changes in the parent component, it automatically updates in the child component. A child component can temporarily reassign a prop value for ephemeral state, but should not mutate props unless they are declared with $bindable. Mutating regular object props has no effect. Mutating reactive state proxy props will work but triggers an ownership_invalid_mutation warning.
$props rest property
Use the rest property syntax to capture remaining props not explicitly destructured. Example: `let { a, b, c, ...others } = $props();`
$props renaming with destructuring
Props can be renamed during destructuring using the colon syntax. This is necessary for invalid identifiers or JavaScript keywords like `super`. Example: `let { super: trouper = 'lights are gonna find me' } = $props();`
$props destructuring with fallback values
When destructuring props, you can provide fallback values that are used if the parent does not set a prop or passes undefined. Fallback values are not turned into reactive state proxies. Example: `let { adjective = 'happy' } = $props();`
$props rune basic usage
The $props rune receives component inputs called props. You can use it to capture all props in an object with `let props = $props();` or destructure specific props with `let { adjective } = $props();`.
$props.id() generates unique instance ID
$props.id() is a rune added in version 5.20.0 that generates an ID unique to the current component instance. When hydrating server-rendered components, the value is consistent between server and client. It is useful for linking elements via attributes like `for` and `aria-labelledby`.
Parent can pass $bindable props as normal one-way props
A parent component is not required to use bind: when passing a value to a $bindable prop. It can pass a normal one-way prop instead if it does not want to listen to child mutations.
$bindable rune for two-way prop binding
The $bindable rune marks a prop as bindable, enabling data to flow both from parent to child and from child to parent. Use the syntax let { value = $bindable() } within $props() to mark a prop as bindable. This allows child components to mutate state and parent components to listen to changes using the bind: directive.
$bindable prevents Svelte mutation warnings
Normally, mutating props in child components is strongly discouraged and triggers Svelte warnings for unmutated state. Marking a prop with $bindable allows safe mutation in the child component without warnings, since it indicates the component owns the state.
Parent can bind to $bindable props with bind: directive
A parent component using a child with $bindable props can use the bind: directive to establish two-way binding, such as bind:value={message}. This allows the parent to receive updates when the child mutates the value.
$bindable fallback value syntax
A fallback value can be specified for a $bindable prop using the syntax let { value = $bindable('fallback') }. This fallback is used when the parent does not pass the prop at all.
$bindable use case and warnings
Two-way binding with $bindable should be used sparingly and carefully. Overuse can make data flow unpredictable and components harder to maintain. It is recommended to use it only when it genuinely simplifies code.
$inspect.trace for tracing function re-runs
$inspect.trace is a rune added in Svelte 5.14 that causes the surrounding function to be traced in development. Any time the function re-runs as part of an effect or derived, information will be printed to the console about which pieces of reactive state caused the function to fire. $inspect.trace must be the first statement of a function body. It takes an optional first argument which will be used as the label.
$inspect with callback method
$inspect(...) returns an object with a with method that accepts a callback function. This callback will be invoked instead of console.log. The first argument to the callback is either 'init' or 'update', indicating whether this is the initial run or a subsequent update. Subsequent arguments are the values passed to $inspect.
$inspect rune for logging reactive state changes
The $inspect rune is roughly equivalent to console.log, except it re-runs whenever its arguments change. It tracks reactive state deeply, meaning that updating something inside an object or array using fine-grained reactivity will cause it to re-fire. $inspect only works during development; in a production build it becomes a noop.
$inspect stack trace on updates
On updates, $inspect will print a stack trace, making it easy to find the origin of a state change. Stack traces are not printed in the Svelte playground due to technical limitations.
$host requires customElement option
The $host rune is only available in components compiled as custom elements, which requires setting the customElement option in <svelte:options customElement="element-name" /> at the top of the component file.
$host rune for custom elements
The $host rune provides access to the host element when a component is compiled as a custom element. It allows you to perform operations on the host element, such as dispatching custom events.
$host() dispatchEvent example
To dispatch a custom event from a custom element component, call $host().dispatchEvent(new CustomEvent(type)) where type is the event name string. For example: $host().dispatchEvent(new CustomEvent('increment')) dispatches an 'increment' event that can be listened to on the host element.
Runes definition and purpose in Svelte 5
Runes are compiler directives in Svelte 5 that provide reactivity and component behavior. They are indicated by the $ symbol prefix and form the foundation of Svelte 5's reactive system.
Context with reactive state requires mutation not reassignment
When storing reactive state in context, you must mutate the state object properties rather than reassign the entire context variable. For example, use counter.count = 0 instead of counter = { count: 0 }. Reassigning breaks the link to the context. Svelte will warn if you get this wrong.
setContext and getContext use string keys
setContext(key, value) sets context in a parent component with a string key. getContext(key) retrieves the context value in a child component using the same key. Both the key and the context value can be any JavaScript value.
hasContext and getAllContexts utility functions
Svelte exposes hasContext and getAllContexts functions in addition to setContext and getContext. These allow checking if context exists and retrieving all available contexts.
Context avoids prop drilling
Context allows components to access values owned by parent components without passing them down as props through many layers of intermediate components, a pattern known as prop-drilling.
createContext creates typed get/set pair
createContext is a function that returns a [get, set] pair of functions. It was added in Svelte version 5.40. The get function retrieves context values from child components, and the set function assigns context values from parent components. createContext is preferred over setContext/getContext because it provides better type safety and eliminates the need for keys.
Context solves shared state server-side rendering problem
Context is preferred over global module state for shared values because context is not shared between requests during server-side rendering. If you mutate global module state during SSR, the data may be accessible by the next user. Context prevents this security issue because each request has its own context.
Context testing with mount wrapper component
When writing component tests with Vitest, create a wrapper component that calls setContext to set up context for the component being tested. As of Svelte version 5.49, you can define the wrapper as a function that calls setContext and returns the component, then pass this wrapper to mount().
Context works with children snippets
Context is particularly useful when a parent component is not directly aware of child components but instead renders them as part of a children snippet. The parent uses {@render children()} to render child components that can access the context set by the parent.
$effect.pre replaces beforeUpdate with granular control
$effect.pre behaves the same as $effect but runs before the DOM is updated. When you explicitly reference a state variable inside the effect body, it will run whenever that specific state changes, but not when other unrelated state changes. This provides more granular control than beforeUpdate, which fires before every component update.