Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/christianbaroni/stores/llms.txt

Use this file to discover all available pages before exploring further.

These hooks are part of the React build of @storesjs/stores and are not available in the vanilla (framework-agnostic) build. Import them from @storesjs/stores in any React or React Native project.

​
useListen

useListen subscribes to a slice of a store and runs a callback whenever that slice changes — without causing the component to re-render. It is the right tool when you need to react to state changes imperatively: forwarding values to Reanimated shared values, triggering side effects, or deciding yourself whether and when a render should occur. The hook attaches the subscription automatically on mount and removes it on unmount. Use the returned ListenHandle only when you need to pause or resume the listener manually.

​
Signature

function useListen<Store, Selected>(
  store: Store,
  selector: (state: S) => Selected,
  react: (current: Selected, previous: Selected, unsubscribe: () => void) => void,
  optionsOrEqualityFn?: UseListenOptions<Selected> | EqualityFn<Selected>
): RefObject<Readonly<ListenHandle>>

​
Parameters

​
store
BaseStore<S>
required
The store to subscribe to. Should be a stable reference — the hook re-attaches when this value changes.
​
selector
(state: S) => Selected
required
Selects the slice of store state to observe. The react callback is only invoked when this selected value changes according to equalityFn.
​
react
(current: Selected, previous: Selected, unsubscribe: () => void) => void
required
Callback fired whenever the selected slice changes. Receives the current value, the previous value, and a convenience unsubscribe function that permanently detaches this listener.
​
optionsOrEqualityFn
UseListenOptions<Selected> | EqualityFn<Selected>
Either a UseListenOptions config object or a shorthand equality function. When omitted, defaults apply.

​
Return value

​
RefObject<Readonly<ListenHandle>>
RefObject
A React ref whose .current value is a ListenHandle:

​
Example

The following pattern is taken directly from the source docblock. It forwards candlestick data to a Reanimated chart manager without ever re-rendering the component: 
useListen(
  useCandlestickStore,
  state => state.getData(),
  (candles, previous, unsubscribe) => {
    if (candles?.unsupported) return unsubscribe();
    updateTokenPrice(token, getPriceUpdate(candles, previous));
    runOnUI(() => chartManager.value?.setCandles(candles))();
  }
);
Changes to options other than enabled are not reactive. If you update equalityFn, fireImmediately, or debugMode between renders those new values only take effect the next time the listener resubscribes (e.g. when store changes or enabled toggles). Keep these values stable or use refs if you need them to update dynamically.
The hook manages its own lifecycle — you do not need to call unsubscribe in a cleanup function. Only reach for the returned ListenHandle when you want to explicitly pause the listener (e.g. while a long-lived component is off-screen) and later resume it with resubscribe().
useListen uses useLayoutEffect internally to attach and detach subscriptions. In server-side rendering (SSR) environments this is a no-op — the listener is never attached on the server. If you render on the server and need to suppress the React SSR warning about useLayoutEffect, consider wrapping the component in a client-only boundary or using the suppressHydrationWarning approach appropriate to your framework.

​
useStableValue

useStableValue runs an initializer function exactly once per component instance and returns the same value for the lifetime of that component. It is a safe, idiomatic alternative to useRef + manual initialization guards for expensive or stateful values that must not be recreated on re-renders.

​
Signature

function useStableValue<T>(init: () => T): T

​
Parameters

​
init
() => T
required
A zero-argument factory function. It is called only on the first render of a given component instance. Subsequent renders skip the call entirely and return the cached value.

​
Return value

​
T
T
The stable value produced by init on the first render.

​
Example

import { useStableValue } from '@storesjs/stores';

function MyComponent() {
  const initialState = useStableValue(() => computeExpensiveInitialState());
  // initialState is identical across every render of this component instance
}

Build docs developers (and LLMs) love

Get started for freeTalk to us