Svelte Svelte
search ⌘K

Svelte • Runes

$derived

On this page

Derived state is declared with the $derived rune:

<script lang="ts">
	let let count: numbercount = 
function $state<0>(initial: 0): 0 (+1 overload)
namespace $state
Declares reactive state.
Example:
let count = $state(0);
@see{@link https://svelte.dev/docs/svelte/$state Documentation}@paraminitial The initial value
$
function $state<0>(initial: 0): 0 (+1 overload)
namespace $state
Declares reactive state.
Example:
let count = $state(0);
@see{@link https://svelte.dev/docs/svelte/$state Documentation}@paraminitial The initial value
state(0);
	let let doubled: numberdoubled = 
function $derived<number>(expression: number): number
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
$
function $derived<number>(expression: number): number
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
derived(let count: numbercount * 2);
</script>

<button onclick={() => let count: numbercount++}>
	{let doubled: numberdoubled}
</button>

<p>{let count: numbercount} doubled is {let doubled: numberdoubled}</p>
<script>
	let let count: numbercount = 
function $state<0>(initial: 0): 0 (+1 overload)
namespace $state
Declares reactive state.
Example:
let count = $state(0);
@see{@link https://svelte.dev/docs/svelte/$state Documentation}@paraminitial The initial value
$
function $state<0>(initial: 0): 0 (+1 overload)
namespace $state
Declares reactive state.
Example:
let count = $state(0);
@see{@link https://svelte.dev/docs/svelte/$state Documentation}@paraminitial The initial value
state(0);
	let let doubled: numberdoubled = 
function $derived<number>(expression: number): number
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
$
function $derived<number>(expression: number): number
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
derived(let count: numbercount * 2);
</script>

<button onclick={() => let count: numbercount++}>
	{let doubled: numberdoubled}
</button>

<p>{let count: numbercount} doubled is {let doubled: numberdoubled}</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.

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.

<script lang="ts">
	let let numbers: number[]numbers = 
function $state<number[]>(initial: number[]): number[] (+1 overload)
namespace $state
Declares reactive state.
Example:
let count = $state(0);
@see{@link https://svelte.dev/docs/svelte/$state Documentation}@paraminitial The initial value
$
function $state<number[]>(initial: number[]): number[] (+1 overload)
namespace $state
Declares reactive state.
Example:
let count = $state(0);
@see{@link https://svelte.dev/docs/svelte/$state Documentation}@paraminitial The initial value
state([1, 2, 3]);
	let let total: numbertotal = 
namespace $derived
function $derived<T>(expression: T): T
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
$
namespace $derived
function $derived<T>(expression: T): T
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
derived.function $derived.by<number>(fn: () => number): number
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.
Example:
let total = $derived.by(() => {
  let result = 0;
 for (const n of numbers) {
   result += n;
  }
  return result;
});
@see{@link https://svelte.dev/docs/svelte/$derived#$derived.by Documentation}
by(() => {
		let let total: numbertotal = 0;
		for (const const n: numbern of let numbers: number[]numbers) {
			let total: numbertotal += const n: numbern;
		}
		return let total: numbertotal;
	});
</script>

<button onclick={() => let numbers: number[]numbers.Array<number>.push(...items: number[]): number
Appends new elements to the end of an array, and returns the new length of the array.
@paramitems New elements to add to the array.
push(let numbers: number[]numbers.Array<number>.length: number
Gets or sets the length of the array. This is a number one higher than the highest index in the array.
length + 1)}>
	{let numbers: number[]numbers.Array<number>.join(separator?: string): string
Adds all the elements of an array into a string, separated by the specified separator string.
@paramseparator A string used to separate one element of the array from the next in the resulting string. If omitted, the array elements are separated with a comma.
join(' + ')} = {let total: numbertotal}
</button>
<script>
	let let numbers: number[]numbers = 
function $state<number[]>(initial: number[]): number[] (+1 overload)
namespace $state
Declares reactive state.
Example:
let count = $state(0);
@see{@link https://svelte.dev/docs/svelte/$state Documentation}@paraminitial The initial value
$
function $state<number[]>(initial: number[]): number[] (+1 overload)
namespace $state
Declares reactive state.
Example:
let count = $state(0);
@see{@link https://svelte.dev/docs/svelte/$state Documentation}@paraminitial The initial value
state([1, 2, 3]);
	let let total: numbertotal = 
namespace $derived
function $derived<T>(expression: T): T
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
$
namespace $derived
function $derived<T>(expression: T): T
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
derived.function $derived.by<number>(fn: () => number): number
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.
Example:
let total = $derived.by(() => {
  let result = 0;
 for (const n of numbers) {
   result += n;
  }
  return result;
});
@see{@link https://svelte.dev/docs/svelte/$derived#$derived.by Documentation}
by(() => {
		let let total: numbertotal = 0;
		for (const const n: numbern of let numbers: number[]numbers) {
			let total: numbertotal += const n: numbern;
		}
		return let total: numbertotal;
	});
</script>

<button onclick={() => let numbers: number[]numbers.Array<number>.push(...items: number[]): number
Appends new elements to the end of an array, and returns the new length of the array.
@paramitems New elements to add to the array.
push(let numbers: number[]numbers.Array<number>.length: number
Gets or sets the length of the array. This is a number one higher than the highest index in the array.
length + 1)}>
	{let numbers: number[]numbers.Array<number>.join(separator?: string): string
Adds all the elements of an array into a string, separated by the specified separator string.
@paramseparator A string used to separate one element of the array from the next in the resulting string. If omitted, the array elements are separated with a comma.
join(' + ')} = {let total: numbertotal}
</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.

In addition, if an expression contains an await, Svelte transforms it such that any state after the await is also tracked — in other words, in a case like this…

let let a: Promise<number>let a: Promise<number>a = var Promise: PromiseConstructor
Represents the completion of an asynchronous operation
var Promise: PromiseConstructor
Represents the completion of an asynchronous operation
Promise.PromiseConstructor.resolve<number>(value: number): Promise<number> (+2 overloads)
Creates a new resolved promise for the provided value.
@paramvalue A promise.@returnsA promise whose internal state matches the provided promise.
PromiseConstructor.resolve<number>(value: number): Promise<number> (+2 overloads)
Creates a new resolved promise for the provided value.
@paramvalue A promise.@returnsA promise whose internal state matches the provided promise.
resolve(1);
let let b: numberlet b: numberb = 2;
// cut
let let total: numberlet total: numbertotal = 
function $derived<number>(expression: number): number
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
function $derived<number>(expression: number): number
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
$derived(await let a: Promise<number>let a: Promise<number>a + let b: numberlet b: numberb);

…both a and b are tracked, even though b is only read once a has resolved, after the initial execution. (This does not apply to await in functions that are called by the expression, only the expression itself.)

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, where a value is derived from the ‘source of truth’ (such as data from your server) but you’d like to show immediate feedback to the user:

<script lang="ts">
	let { let post: anypost, let like: anylike } = 
function $props(): any
namespace $props
Declares the props that a component accepts. Example:
let { optionalProp = 42, requiredProp, bindableProp = $bindable() }: { optionalProp?: number; requiredProps: string; bindableProp: boolean } = $props();
@see{@link https://svelte.dev/docs/svelte/$props Documentation}
$
function $props(): any
namespace $props
Declares the props that a component accepts. Example:
let { optionalProp = 42, requiredProp, bindableProp = $bindable() }: { optionalProp?: number; requiredProps: string; bindableProp: boolean } = $props();
@see{@link https://svelte.dev/docs/svelte/$props Documentation}
props();

	let let likes: anylikes = 
function $derived<any>(expression: any): any
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
$
function $derived<any>(expression: any): any
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
derived(let post: anypost.likes);

	async function function (local function) onclick(): Promise<void>onclick() {
		// increment the `likes` count immediately...
		let likes: anylikes += 1;

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

<button {onclick?: MouseEventHandler<HTMLButtonElement> | null | undefinedonclick}>🧡 {let likes: anylikes}</button>
<script>
	let { let post: anypost, let like: anylike } = 
function $props(): any
namespace $props
Declares the props that a component accepts. Example:
let { optionalProp = 42, requiredProp, bindableProp = $bindable() }: { optionalProp?: number; requiredProps: string; bindableProp: boolean } = $props();
@see{@link https://svelte.dev/docs/svelte/$props Documentation}
$
function $props(): any
namespace $props
Declares the props that a component accepts. Example:
let { optionalProp = 42, requiredProp, bindableProp = $bindable() }: { optionalProp?: number; requiredProps: string; bindableProp: boolean } = $props();
@see{@link https://svelte.dev/docs/svelte/$props Documentation}
props();

	let let likes: anylikes = 
function $derived<any>(expression: any): any
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
$
function $derived<any>(expression: any): any
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
derived(let post: anypost.likes);

	async function function (local function) onclick(): Promise<void>onclick() {
		// increment the `likes` count immediately...
		let likes: anylikes += 1;

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

<button {onclick?: MouseEventHandler<HTMLButtonElement> | null | undefinedonclick}>🧡 {let likes: anylikes}</button>

Prior to Svelte 5.25, deriveds were read-only.

Deriveds and reactivity

Unlike $state, which converts objects and arrays to deeply reactive proxies, $derived values are left as-is. For example, in a case like this…

let items = 
function $state<never[]>(initial: never[]): never[] (+1 overload)
namespace $state
Declares reactive state.
Example:
let count = $state(0);
@see{@link https://svelte.dev/docs/svelte/$state Documentation}@paraminitial The initial value
$state([ /*...*/ ]);
Variable 'items' implicitly has an 'any[]' type.

let let index: numberindex = 
function $state<0>(initial: 0): 0 (+1 overload)
namespace $state
Declares reactive state.
Example:
let count = $state(0);
@see{@link https://svelte.dev/docs/svelte/$state Documentation}@paraminitial The initial value
$state(0);
let let selected: anyselected = 
function $derived<any>(expression: any): any
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
$derived(let items: any[]items[let index: numberindex]);

…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 — this…

function 
function stuff(): {
    a: number;
    b: number;
    c: number;
}
function stuff(): {
    a: number;
    b: number;
    c: number;
}
stuff() { return { a: numbera: numbera: 1, b: numberb: numberb: 2, c: numberc: numberc: 3 } }
// cut
let { let a: numberlet a: numbera, let b: numberlet b: numberb, let c: numberlet c: numberc } = 
function $derived<{
    a: number;
    b: number;
    c: number;
}>(expression: {
    a: number;
    b: number;
    c: number;
}): {
    a: number;
    b: number;
    c: number;
}
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
function $derived<{
    a: number;
    b: number;
    c: number;
}>(expression: {
    a: number;
    b: number;
    c: number;
}): {
    a: number;
    b: number;
    c: number;
}
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
$derived(
function stuff(): {
    a: number;
    b: number;
    c: number;
}
function stuff(): {
    a: number;
    b: number;
    c: number;
}
stuff());

…is roughly equivalent to this:

function 
function stuff(): {
    a: number;
    b: number;
    c: number;
}
function stuff(): {
    a: number;
    b: number;
    c: number;
}
stuff() { return { a: numbera: numbera: 1, b: numberb: numberb: 2, c: numberc: numberc: 3 } }
// cut
let 
let _stuff: {
    a: number;
    b: number;
    c: number;
}
let _stuff: {
    a: number;
    b: number;
    c: number;
}
_stuff = 
function $derived<{
    a: number;
    b: number;
    c: number;
}>(expression: {
    a: number;
    b: number;
    c: number;
}): {
    a: number;
    b: number;
    c: number;
}
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
function $derived<{
    a: number;
    b: number;
    c: number;
}>(expression: {
    a: number;
    b: number;
    c: number;
}): {
    a: number;
    b: number;
    c: number;
}
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
$derived(
function stuff(): {
    a: number;
    b: number;
    c: number;
}
function stuff(): {
    a: number;
    b: number;
    c: number;
}
stuff());
let let a: numberlet a: numbera = 
function $derived<number>(expression: number): number
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
function $derived<number>(expression: number): number
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
$derived(
let _stuff: {
    a: number;
    b: number;
    c: number;
}
let _stuff: {
    a: number;
    b: number;
    c: number;
}
_stuff.a: numbera: numbera);
let let b: numberlet b: numberb = 
function $derived<number>(expression: number): number
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
function $derived<number>(expression: number): number
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
$derived(
let _stuff: {
    a: number;
    b: number;
    c: number;
}
let _stuff: {
    a: number;
    b: number;
    c: number;
}
_stuff.b: numberb: numberb);
let let c: numberlet c: numberc = 
function $derived<number>(expression: number): number
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
function $derived<number>(expression: number): number
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
$derived(
let _stuff: {
    a: number;
    b: number;
    c: number;
}
let _stuff: {
    a: number;
    b: number;
    c: number;
}
_stuff.c: numberc: numberc);

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. In other words, Svelte will only update the text inside the button when large changes, not when count changes, even though large depends on count:

<script lang="ts">
	let let count: numbercount = 
function $state<0>(initial: 0): 0 (+1 overload)
namespace $state
Declares reactive state.
Example:
let count = $state(0);
@see{@link https://svelte.dev/docs/svelte/$state Documentation}@paraminitial The initial value
$
function $state<0>(initial: 0): 0 (+1 overload)
namespace $state
Declares reactive state.
Example:
let count = $state(0);
@see{@link https://svelte.dev/docs/svelte/$state Documentation}@paraminitial The initial value
state(0);
	let let large: booleanlarge = 
function $derived<boolean>(expression: boolean): boolean
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
$
function $derived<boolean>(expression: boolean): boolean
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
derived(let count: numbercount > 10);
</script>

<button onclick={() => let count: numbercount++}>
	{let large: booleanlarge}
</button>
<script>
	let let count: numbercount = 
function $state<0>(initial: 0): 0 (+1 overload)
namespace $state
Declares reactive state.
Example:
let count = $state(0);
@see{@link https://svelte.dev/docs/svelte/$state Documentation}@paraminitial The initial value
$
function $state<0>(initial: 0): 0 (+1 overload)
namespace $state
Declares reactive state.
Example:
let count = $state(0);
@see{@link https://svelte.dev/docs/svelte/$state Documentation}@paraminitial The initial value
state(0);
	let let large: booleanlarge = 
function $derived<boolean>(expression: boolean): boolean
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
$
function $derived<boolean>(expression: boolean): boolean
namespace $derived
Declares derived state, i.e. one that depends on other state variables.
The expression inside $derived(...) should be free of side-effects.
Example:
let double = $derived(count * 2);
@see{@link https://svelte.dev/docs/svelte/$derived Documentation}@paramexpression The derived state expression
derived(let count: numbercount > 10);
</script>

<button onclick={() => let count: numbercount++}>
	{let large: booleanlarge}
</button>
Edit this page on GitHub llms.txt