mirror of
https://github.com/sveltejs/svelte.git
synced 2024-12-01 01:11:24 +01:00
6a2c28c590
* docs: tweak untrack description, provide an example of usage * link to untrack * add derived docs too
54 lines
1.6 KiB
Markdown
54 lines
1.6 KiB
Markdown
---
|
|
title: $derived
|
|
---
|
|
|
|
Derived state is declared with the `$derived` rune:
|
|
|
|
```svelte
|
|
<script>
|
|
let count = $state(0);
|
|
let doubled = $derived(count * 2);
|
|
</script>
|
|
|
|
<button onclick={() => count++}>
|
|
{doubled}
|
|
</button>
|
|
|
|
<p>{count} doubled is {doubled}</p>
|
|
```
|
|
|
|
The expression inside `$derived(...)` should be free of side-effects. Svelte will disallow state changes (e.g. `count++`) inside derived expressions.
|
|
|
|
As with `$state`, you can mark class fields as `$derived`.
|
|
|
|
> [!NOTE] Code in Svelte components is only executed once at creation. Without the `$derived` rune, `doubled` would maintain its original value even when `count` changes.
|
|
|
|
## `$derived.by`
|
|
|
|
Sometimes you need to create complex derivations that don't fit inside a short expression. In these cases, you can use `$derived.by` which accepts a function as its argument.
|
|
|
|
```svelte
|
|
<script>
|
|
let numbers = $state([1, 2, 3]);
|
|
let total = $derived.by(() => {
|
|
let total = 0;
|
|
for (const n of numbers) {
|
|
total += n;
|
|
}
|
|
return total;
|
|
});
|
|
</script>
|
|
|
|
<button onclick={() => numbers.push(numbers.length + 1)}>
|
|
{numbers.join(' + ')} = {total}
|
|
</button>
|
|
```
|
|
|
|
In essence, `$derived(expression)` is equivalent to `$derived.by(() => expression)`.
|
|
|
|
## Understanding dependencies
|
|
|
|
Anything read synchronously inside the `$derived` expression (or `$derived.by` function body) is considered a _dependency_ of the derived state. When the state changes, the derived will be marked as _dirty_ and recalculated when it is next read.
|
|
|
|
To exempt a piece of state from being treated as a dependency, use [`untrack`](svelte#untrack).
|