Hooks unstable

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.

Gotchas

In promise and promiseExit modes, the setter observes the atom's next settled result, not a result correlated with that write. Overlapping writes can resolve with another write's result. Serialize writes when each caller needs its own result.

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]

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

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

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

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]>

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]

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

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.

Gotchas

In promise and promiseExit modes, the setter observes the atom's next settled result, not a result correlated with that write. Overlapping writes can resolve with another write's result. Serialize writes when each caller needs its own result.

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

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

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

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 subscribes to the atom and applies the selector to its value from the current RegistryContext.

Gotchas

Late Suspense boundaries hydrate with the same atom snapshot as earlier readers, then update to the live value. The snapshot lasts until all readers unsubscribe. Changes before the first reader hydrates or after the last unsubscribes can still cause mismatches, as can a derived atom first read inside a late boundary.

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;
}