Signals

The reactive primitives that tie everything together.

The four shapes

Type	What it is
Atom<T>	A writable value that notifies on change. atom('name', initial).
Computed<T>	A derived value that auto-tracks its reads. computed('name', () => atom.get() + 1).
Reactor	A side-effecting reaction. react('name', () => { /* tracks reads */ }).
Signal<T>	The shared interface (get(), change-tracking metadata).

All four live in packages/state/src/lib/. They are dependency-free and exported as a standalone package, @tldraw/state.

Transactions

import { atom, transact } from '@tldraw/state';

const x = atom('x', 0);
const y = atom('y', 0);

transact(() => {
  x.set(1);
  y.set(2);
}); // subscribers see one update with both new values

Transactions are the unit of consistency. Every mutation made inside editor.run(() => { ... }) runs inside a transact (and inside a history mark), so no observer ever sees a half-mutated state.

Capture stack

Inside a Computed, every signal.get() registers a dependency on a "capture stack". When the computed is asked for its value, the dependency set determines whether to recompute. unsafe__withoutCapture opens an escape hatch — useful for reads that should not retrigger the computed.

React glue

@tldraw/state-react ships hooks for components:

• useValue('name', () => signal.get(), [deps]) — re-render on change.
• useComputed('name', () => ..., [deps]) — memoize a Computed across renders.
• useReactor('name', () => ..., [deps]) — run a side-effect tied to the component lifecycle.
• track(Component) — HOC that re-renders on any tracked read.

Why this matters

The editor's most common bug class is "I changed state but the UI didn't update." The fix is almost always one of:

• Read inside useValue, not on first render.
• Read inside a Computed, not at module scope.
• Don't call unsafe__withoutCapture unless the read should be untracked.

Related

• @tldraw/state
• @tldraw/state-react
• Patterns and conventions