$state
Only use the
$state
rune for variables that should be
reactive
— in other words, variables that cause an
$effect
,
$derived
or template expression to update. Everything else can be a normal variable.
Objects and arrays (
$state({...})
or
$state([...])
) are made deeply reactive, meaning mutation will trigger updates. This has a trade-off: in exchange for fine-grained reactivity, the objects must be proxied, which has performance overhead. In cases where you're dealing with large objects that are only ever reassigned (rather than mutated), use
$state.raw
instead. This is often the case with API responses, for example.
$derived
To compute something from state, use
$derived
rather than
$effect
:
// do this
let
square
=
$derived
(
num
*
num
)
;
// don't do this
let
square
;
$effect
(
(
)
=>
{
square
=
num
*
num
;
}
)
;
[!NOTE]
$derived
is given an expression,
not
a function. If you need to use a function (because the expression is complex, for example) use
$derived.by
.
Deriveds are writable — you can assign to them, just like
$state
, except that they will re-evaluate when their expression changes.
If the derived expression is an object or array, it will be returned as-is — it is
not
made deeply reactive. You can, however, use
$state
inside
$derived.by
in the rare cases that you need this.
$effect
Effects are an escape hatch and should mostly be avoided. In particular, avoid updating state inside effects.
If you need to sync state to an external library such as D3, it is often neater to use
{@attach ...}
If you need to run some code in response to user interaction, put the code directly in an event handler or use a
function binding
as appropriate
If you need to log values for debugging purposes, use
$inspect
If you need to observe something external to Svelte, use
createSubscriber
Never wrap the contents of an effect in
if (browser) {...}
or similar — effects do not run on the server.
$props
Treat props as though they will change. For example, values that depend on props should usually use
$derived
:
// @errors: 2451
let
{
type
}
=
$props
(
)
;
// do this
let
color
=
$derived
(
type
===
'danger'
?
'red'
:
'green'
)
;
// don't do this — color will not update if type changes
let
color
=
type
===
'danger'
?
'red'
:
'green'
;
$inspect.trace
$inspect.trace
is a debugging tool for reactivity. If something is not updating properly or running more than it should you can add
$inspect.trace(label)
as the first line of an
$effect
or
$derived.by
(or any function they call) to trace their dependencies and discover which one triggered an update.
Events
Any element attribute starting with
on
is treated as an event listener:
If you need to attach listeners to
window
or
document
you can use
hello {name}!
{/snippet} {@render greeting('world')} [!NOTE] Snippets declared at the top level of a component (i.e. not inside elements or blocks) can be referenced inside