From ad4d7e4a64ebb7bada8b29dbbffe86dc69a61b20 Mon Sep 17 00:00:00 2001 From: Neekoras Date: Mon, 19 Oct 2026 22:13:38 -0700 Subject: [PATCH] docs(signals): explain untrack with unresolved async reads --- packages/signals/src/core/core.ts | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/packages/signals/src/core/core.ts b/packages/signals/src/core/core.ts index a49dc13c5..bda7ecc7a 100644 --- a/packages/signals/src/core/core.ts +++ b/packages/signals/src/core/core.ts @@ -1517,6 +1517,16 @@ export function setStrictRead(v: string | false): string | false { * Use `untrack` inside a memo or effect when you need to read a signal once * without making the surrounding computation depend on its future changes. * + * `untrack` stops dependency tracking, not async settlement. Reading an + * uninitialized async source still suspends the owning computation; it runs + * again when that source first resolves. Afterward, the untracked read is a + * snapshot and does not subscribe the computation to later changes. + * + * If the first read must return immediately, give the async source a + * `loadingValue` before reading it with `untrack`. `isPending` and `latest` + * inspect updates to an existing value; neither supplies a missing initial + * value. + * * Pass a `strictReadLabel` string to enable a dev-mode warning: any reactive * read inside `fn` that isn't inside a nested tracking scope will log a * warning naming the label. @@ -1530,6 +1540,9 @@ export function setStrictRead(v: string | false): string | false { * log(snapshot); * } * ); + * + * const color = createMemo(() => fetchColor(), { loadingValue: "gray" }); + * const initialColor = untrack(color); // "gray" while the fetch is unresolved * ``` */ export function untrack(fn: () => T, strictReadLabel?: string | false): T {