Docs

useSuperState API

The consumer hook for accessing and updating existing global state. It allows any component to subscribe to state updates via a unique string key.

#Signature

ts
app/page.tsx
// Basic subscription
const [state, setState] = useSuperState(key: string)
// Subscribing to nested properties (Dot-notation)
const [city, setCity] = useSuperState('user.address.city')

#TypeScript

Because SuperState is completely decoupled and relies on string keys, you must pass a generic type to useSuperState to prevent TypeScript from treating the state as unknown.

ts
TypeScript Example
// Prevents "Type 'unknown' is not assignable to type 'ReactNode'" errors
const [age] = useSuperState<number>('user.age')
const [name] = useSuperState<string>('user.name')

#Parameters

  • key (required)

    The unique string key of the global state you want to consume. This must match the key used in createSuperState.

#Nested Updates

SuperState performs an immutable path update when you update a nested property. It shallow-clones each level of the object tree along the path, preserving references to unchanged branches. Updates are atomic and only notify components watching relevant keys.

ts
NestedUpdate.tsx
const [city, setCity] = useSuperState('user.address.city')
// Updating just the city property
const updateCity = () => setCity('London')
Fine-grained Reactivity
Components using useSuperState('user.address.city') will not re-render if user.name changes.
Previous createSuperState