Docs

createSuperState API

The core hook for initializing and owning global state. Use it just like useState, but with a required string key for global sharing.

#Signature

ts
app/page.tsx
// Global state (Owned by this component)
const [state, setState] = createSuperState(key: string, initialValue)

#Parameters

  • key (required)

    A unique string identifier for the global state.

  • initialValue

    The initial value for the state. If a key is passed, this is the source of truth for all components sharing the same key.

#Returns

Returns a tuple with the current global state and a setter function, exactly like useState.

Need local state? Use createLocalState(initialValue) or React's built-in useState instead. They are identical under the hood.

ts
CounterExample.tsx
const [count, setCount] = createSuperState('count', 0)
// Standard updates
const increment = () => setCount(count + 1)
// Functional updates
const double = () => setCount(c => c * 2)
Hydration Note
When using SSR (Next.js, etc.), the initial value must be consistent between the server and the client to avoid hydration mismatches.
Unique Key Enforcement
You should ideally use createSuperState('key', initial) only once per unique key. If multiple components attempt to initialize the same global state, SuperState will warn in development to prevent conflicting initial values.

To consume the state in other components without re-initializing it, use useSuperState('key') instead. This maintains a single source of truth for the initial value.
NextuseSuperState