diff --git a/src/routes/(0)concepts/(2)derived-values/(0)derived-signals.mdx b/src/routes/(0)concepts/(2)derived-values/(0)derived-signals.mdx index 146bce5224..db20aeebb8 100644 --- a/src/routes/(0)concepts/(2)derived-values/(0)derived-signals.mdx +++ b/src/routes/(0)concepts/(2)derived-values/(0)derived-signals.mdx @@ -13,21 +13,38 @@ tags: - state version: "1.0" description: >- - Create reactive derived values that automatically update when their - dependencies change using Solid's derived signals. + Derive values from signals with plain functions and use them in tracking + scopes to keep dependent computations up to date. --- Derived signals are functions that rely on one or more [signals](/concepts/signals) to produce a value. -These functions are not executed immediately, but instead are only called when the values they rely on are changed. -When the underlying signal is changed, the function will be called again to produce a new value. +A derived signal is a plain function: it runs when you call it, not automatically when a signal changes. +Each call reads the current signal values and calculates a new result. ```js const double = () => count() * 2; ``` -In the above example, the `double` function relies on the `count` signal to produce a value. -When the `count` signal is changed, the `double` function will be called again to produce a new value. +Calling `double()` reads `count()` and returns twice its current value. +Changing `count` alone does not call `double`. +If you call `double()` inside a tracking scope, such as an effect or a JSX expression, that scope tracks the `count()` read and runs again when `count` changes. + +```js +import { createEffect, createSignal } from "solid-js"; + +const [count, setCount] = createSignal(1); +const double = () => count() * 2; + +console.log(double()); +createEffect(() => console.log(double())); + +setCount(2); +``` + +The first `console.log(double())` is a one-time read that prints `2`. +The effect tracks the `count()` read inside `double()`, so it runs again and prints `4` when `setCount(2)` updates the signal. +The first `console.log` does not run again. Similarly you can create a derived signal that relies on a store value because stores use signals under the hood. To learn more about how stores work, [you can visit the stores section](/concepts/stores). @@ -36,9 +53,11 @@ To learn more about how stores work, [you can visit the stores section](/concept const fullName = () => store.firstName + " " + store.lastName; ``` -These dependent functions gain reactivity from the signal they access, ensuring that changes in the underlying data propagate throughout your application. -It is important to note that these functions do not store a value themselves; instead, they can update any effects or components that depend on them. -If included within a component's body, these derived signals will trigger an update when necessary. +Derived signals do not store or cache their results. +Calling one multiple times repeats the calculation each time. +Reading one at the top level of a component is a one-time read, since components do not re-run when signals change. +Use it inside JSX or another tracking scope when the result needs to stay up to date. -While you can create derived values in this manner, Solid created the [`createMemo`](/reference/basic-reactivity/create-memo) primitive. +For a cached derived value, use [`createMemo`](/reference/basic-reactivity/create-memo). +A memo tracks its own dependencies and reuses its result until those dependencies change. To dive deeper into how memos work, [check out the memos section](/concepts/derived-values/memos).