Hooks

Subscribes to a writable atom and returns its current value together with a setter for updating it.

When to use

Use when a React component needs both to render the current value of a writable atom and update it from the same component.

See

• useAtomValue for subscribing to an atom without a setter
• useAtomSet for updating a writable atom without subscribing to its value

declare function useAtom<R, W, Mode extends "value" | "promise" | "promiseExit" = never>(atom: Writable<R, W>, options?: {
  readonly mode?: [R] extends [AsyncResult<any, any>] ? Mode : "value";
}): readonly [R, "promise" extends Mode ? (value: W) => Promise<Success<R>> : "promiseExit" extends Mode ? (value: W) => Promise<Exit<Success<R>, Failure<R>>> : (value: W | (value: R) => W) => void]

Seeds initial atom values in the current React atom registry.

When to use

Use to seed atom values from a React component after the current registry already exists.

Gotchas

Each atom is initialized at most once for a given registry by this hook, so later calls for the same atom in that registry are ignored.

declare function useAtomInitialValues(initialValues: Iterable<readonly [Atom<any>, any]>): void

Mounts an atom in the current React registry for the lifetime of the component.

When to use

Use to keep an atom mounted from a React component without reading, writing, or refreshing it.

Details

The hook uses the current RegistryContext and releases the mount through React effect cleanup when the component unmounts or when the registry or atom dependency changes.

See

• useAtomSet for mounting a writable atom while returning a setter
• useAtomRefresh for mounting an atom while returning a refresh callback

declare function useAtomMount<A>(atom: Atom<A>): void

Subscribes to an atom ref and returns its latest value.

When to use

Use when a React component should render from an AtomRef.ReadonlyRef directly instead of reading an atom through the current registry.

Details

The hook subscribes with ref.subscribe, triggers re-renders through React state, and returns the current ref.value.

See

• useAtomValue for reading an Atom from the current registry
• useAtomRefPropValue for reading a property ref value

declare function useAtomRef<A>(ref: ReadonlyRef<A>): A

Returns a memoized atom ref for a property of another atom ref.

When to use

Use to derive an AtomRef for one property of an object-shaped atom ref.

Details

The hook memoizes ref.prop(prop) for the [ref, prop] dependency pair and returns the property ref so callers can read, set, update, or subscribe to that nested property.

See

• useAtomRef for subscribing to an atom ref value
• useAtomRefPropValue for subscribing directly to a property value

declare function useAtomRefProp<A, K extends string | number | symbol>(ref: AtomRef<A>, prop: K): AtomRef<A[K]>

Subscribes to a property ref derived from an atom ref and returns its current value.

When to use

Use when a React component needs only the current value of one property from an object-shaped AtomRef.

Details

The hook composes useAtomRefProp(ref, prop) with useAtomRef, so the property ref is memoized for the [ref, prop] pair and then subscribed through ref.subscribe.

See

• useAtomRefProp for returning the property ref directly
• useAtomRef for subscribing to a whole atom ref value

declare function useAtomRefPropValue<A, K extends string | number | symbol>(ref: AtomRef<A>, prop: K): A[K]

Mounts an atom and returns a callback that refreshes it in the current React registry.

When to use

Use to expose a React callback that requests a refresh for an atom without reading or writing its value.

Details

The hook uses the current RegistryContext, mounts the atom for the component lifetime, and returns a callback that calls registry.refresh.

See

• useAtomMount for mounting an atom without returning a refresh callback

declare function useAtomRefresh<A>(atom: Atom<A>): () => void

Mounts a writable atom and returns a setter without subscribing to its value.

When to use

Use when a React component needs to update a writable atom without rendering from that atom's value.

Details

The hook mounts the atom and returns a setter. In value mode the setter accepts a write value or updater function; for AsyncResult atoms, promise and promiseExit modes return a promise for the success value or full Exit.

See

• useAtom for reading and updating the same writable atom

declare function useAtomSet<R, W, Mode extends "value" | "promise" | "promiseExit" = never>(atom: Writable<R, W>, options?: {
  readonly mode?: [R] extends [AsyncResult<any, any>] ? Mode : "value";
}): "promise" extends Mode ? (value: W) => Promise<Success<R>> : "promiseExit" extends Mode ? (value: W) => Promise<Exit<Success<R>, Failure<R>>> : (value: W | (value: R) => W) => void

Subscribes a callback to an atom in the current React registry for the component lifetime.

When to use

Use when a React component needs to run a callback for atom changes without reading the atom value during render.

Details

The subscription is installed in a React effect and cleaned up on unmount or dependency change. When options.immediate is enabled, the callback receives the current value when the effect subscribes.

See

• useAtomValue for reading an atom value during render instead of running a callback

declare function useAtomSubscribe<A>(atom: Atom<A>, f: (_: A) => void, options?: {
  readonly immediate?: boolean;
}): void

Reads an AsyncResult atom through React Suspense, suspending while the result is initial or configured as waiting.

When to use

Use when a React component should render only after an AsyncResult atom has left its initial state, with loading delegated to a Suspense boundary.

Details

suspendOnWaiting defaults to false. When includeFailure is true, a failure result is returned instead of being thrown.

Gotchas

Without includeFailure, failure results are thrown with Cause.squash(result.cause), so callers need an error boundary for failures.

See

• useAtomValue for reading the raw AsyncResult value without Suspense

declare function useAtomSuspense<A, E, IncludeFailure extends boolean = false>(atom: Atom<AsyncResult<A, E>>, options?: {
  readonly includeFailure?: IncludeFailure;
  readonly suspendOnWaiting?: boolean;
}): Success<A, E> | IncludeFailure extends true ? Failure<A, E> : never

Subscribes to an atom in the current React registry and returns its current value, optionally mapped through a selector.

When to use

Use when a React component needs to render from an atom value without also returning a setter.

Details

When a selector is provided, the hook maps the atom before subscribing so the component reads the selected value from the current RegistryContext.

See

• useAtom for reading and updating a writable atom from one component
• useAtomRef for reading an AtomRef directly

declare const useAtomValue: {
  <A>(atom: Atom<A>): A;
  <A, B>(atom: Atom<A>, f: (_: A) => B): B;
}