Skip to content

Hooks

Solid hooks for using Effect Atoms from components and computations. The hooks read and write atoms through the current RegistryContext, mount atoms for cleanup, subscribe callbacks, seed initial values, expose AsyncResult atoms as Solid resources, and read values from AtomRef references.

11 exports Added in v4.0.0 Source

Hooks

useAtom

Added in v4.0.0 Source

Returns a Solid accessor for a writable atom together with a setter for updating it.

When to use

Use when a Solid component or computation needs both a reactive accessor for a writable atom and a write function for that same atom.

Details

The setter accepts either a write value or an updater function. For AsyncResult atoms, promise and promiseExit modes return promises for the success value or full Exit.

See

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

Signature

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

useAtomInitialValues

Added in v4.0.0 Source

Seeds initial atom values in the current Solid atom registry.

When to use

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

Details

For each atom in the current registry, this hook applies the first value supplied through the hook. Later calls for the same atom in that registry are ignored.

Signature

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

useAtomMount

Added in v4.0.0 Source

Mounts an atom in the current Solid registry for the lifetime of the current Solid computation.

When to use

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

Details

The hook uses the current RegistryContext, mounts inside a Solid computation, and releases the mount through Solid cleanup when the computation changes or the owner is disposed.

See

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

Signature

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

useAtomRef

Added in v4.0.0 Source

Subscribes to an atom ref and returns its value as a Solid accessor.

When to use

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

Details

The hook accepts a thunk for the ref, reads ref().value, subscribes with ref.subscribe, and releases the subscription through Solid cleanup when the selected ref changes or the owner is disposed.

See

Signature

declare function useAtomRef<A>(ref: () => ReadonlyRef<A>): Accessor<A>;

useAtomRefProp

Added in v4.0.0 Source

Returns a Solid accessor for a property ref derived from an atom ref.

When to use

Use to derive an AtomRef for one property of an object-shaped atom ref in a Solid computation.

Details

The returned accessor memoizes ref().prop(prop), updating when the source ref thunk produces a different ref.

Gotchas

The prop argument is captured as a plain value. Recreate the hook call when the property key should change.

See

Signature

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

useAtomRefPropValue

Added in v4.0.0 Source

Returns a Solid accessor for the value of a property ref derived from an atom ref.

When to use

Use when a Solid component or computation needs the value of one property from an object-shaped AtomRef without keeping the intermediate property ref.

Details

The hook composes useAtomRefProp(ref, prop) with useAtomRef, returning a Solid accessor for the selected property value.

Gotchas

The prop argument is captured as a plain value. Recreate the hook call when the property key should change.

See

Signature

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

useAtomRefresh

Added in v4.0.0 Source

Mounts an atom and returns a callback that refreshes the current atom.

Signature

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

useAtomResource

Added in v4.0.0 Source

Converts an AsyncResult atom into a Solid resource.

Signature

declare function useAtomResource<A, E>(
  atom: () => Atom<AsyncResult<A, E>>,
  options?: any,
): ResourceReturn<A, void>;

useAtomSet

Added in v4.0.0 Source

Returns a setter for a writable atom without subscribing to its value.

Signature

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

useAtomSubscribe

Added in v4.0.0 Source

Subscribes a callback to an atom in the current Solid registry.

Signature

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

useAtomValue

Added in v4.0.0 Source

Subscribes to an atom in the current Solid registry and returns its value as a Solid accessor.

Signature

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