Skip to content

Commit 21cf79b

Browse files
committed
Clarify derived signal tracking behavior
1 parent 38d7e75 commit 21cf79b

1 file changed

Lines changed: 25 additions & 10 deletions

File tree

‎src/routes/(0)concepts/(2)derived-values/(0)derived-signals.mdx‎

Lines changed: 25 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -13,21 +13,34 @@ tags:
1313
- state
1414
version: "1.0"
1515
description: >-
16-
Create reactive derived values that automatically update when their
17-
dependencies change using Solid's derived signals.
16+
Derive values from signals with plain functions and use them in tracking
17+
scopes to keep dependent computations up to date.
1818
---
1919

2020
Derived signals are functions that rely on one or more [signals](/concepts/signals) to produce a value.
2121

22-
These functions are not executed immediately, but instead are only called when the values they rely on are changed.
23-
When the underlying signal is changed, the function will be called again to produce a new value.
22+
A derived signal is a plain function: it runs when you call it, not automatically when a signal changes.
23+
Each call reads the current signal values and calculates a new result.
2424

2525
```js
2626
const double = () => count() * 2;
2727
```
2828

29-
In the above example, the `double` function relies on the `count` signal to produce a value.
30-
When the `count` signal is changed, the `double` function will be called again to produce a new value.
29+
Calling `double()` reads `count()` and returns twice its current value.
30+
Changing `count` alone does not call `double`.
31+
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.
32+
33+
```js
34+
import { createEffect, createSignal } from "solid-js";
35+
36+
const [count, setCount] = createSignal(1);
37+
const double = () => count() * 2;
38+
39+
console.log(double()); // 2: a one-time read
40+
createEffect(() => console.log(double())); // tracks count
41+
42+
setCount(2); // the effect sees the new value; the one-time read does not run again
43+
```
3144

3245
Similarly you can create a derived signal that relies on a store value because stores use signals under the hood.
3346
To learn more about how stores work, [you can visit the stores section](/concepts/stores).
@@ -36,9 +49,11 @@ To learn more about how stores work, [you can visit the stores section](/concept
3649
const fullName = () => store.firstName + " " + store.lastName;
3750
```
3851

39-
These dependent functions gain reactivity from the signal they access, ensuring that changes in the underlying data propagate throughout your application.
40-
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.
41-
If included within a component's body, these derived signals will trigger an update when necessary.
52+
Derived signals do not store or cache their results.
53+
Calling one multiple times repeats the calculation each time.
54+
Reading one at the top level of a component is a one-time read, since components do not re-run when signals change.
55+
Use it inside JSX or another tracking scope when the result needs to stay up to date.
4256

43-
While you can create derived values in this manner, Solid created the [`createMemo`](/reference/basic-reactivity/create-memo) primitive.
57+
For a cached derived value, use [`createMemo`](/reference/basic-reactivity/create-memo).
58+
A memo tracks its own dependencies and reuses its result until those dependencies change.
4459
To dive deeper into how memos work, [check out the memos section](/concepts/derived-values/memos).

0 commit comments

Comments
 (0)