> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/sveltejs/svelte/llms.txt
> Use this file to discover all available pages before exploring further.

# $derived

> Create derived state in Svelte with the $derived rune

Derived state is declared with the `$derived` rune:

```svelte theme={null}
<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.

## Signature

```ts theme={null}
function $derived<T>(expression: T): T;
```

<ParamField path="expression" type="T">
  The expression to derive from. Should be free of side-effects.
</ParamField>

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.
</Note>

## \$derived.by

```ts theme={null}
function by<T>(fn: () => T): T;
```

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 theme={null}
<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>
```

<ParamField path="fn" type="() => T">
  A function that returns the derived value. Should be free of side-effects.
</ParamField>

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`.

## Overriding derived values

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 can be useful for things like *optimistic UI*:

```svelte theme={null}
<script>
	let { post, like } = $props();

	let likes = $derived(post.likes);

	async function onclick() {
		// increment the `likes` count immediately...
		likes += 1;

		// and tell the server, which will eventually update `post`
		try {
			await like();
		} catch {
			// failed! roll back the change
			likes -= 1;
		}
	}
</script>

<button {onclick}>🧡 {likes}</button>
```

<Note>
  Prior to Svelte 5.25, deriveds were read-only.
</Note>

## Deriveds and reactivity

Unlike `$state`, which converts objects and arrays to deeply reactive proxies, `$derived` values are left as-is. For example:

```js theme={null}
let items = $state([/* ... */]);

let index = $state(0);
let selected = $derived(items[index]);
```

You can change (or `bind:` to) properties of `selected` and it will affect the underlying `items` array. If `items` was *not* deeply reactive, mutating `selected` would have no effect.

## Destructuring

If you use destructuring with a `$derived` declaration, the resulting variables will all be reactive:

```js theme={null}
let { a, b, c } = $derived(stuff());
```

This is roughly equivalent to:

```js theme={null}
let _stuff = $derived(stuff());
let a = $derived(_stuff.a);
let b = $derived(_stuff.b);
let c = $derived(_stuff.c);
```

## Update propagation

Svelte uses something called *push-pull reactivity* — when state is updated, everything that depends on the state (whether directly or indirectly) is immediately notified of the change (the 'push'), but derived values are not re-evaluated until they are actually read (the 'pull').

If the new value of a derived is referentially identical to its previous value, downstream updates will be skipped:

```svelte theme={null}
<script>
	let count = $state(0);
	let large = $derived(count > 10);
</script>

<button onclick={() => count++}>
	{large}
</button>
```

In this example, Svelte will only update the text inside the button when `large` changes, not when `count` changes, even though `large` depends on `count`.