Local vs Global State
SuperState is the only library that lets you start with a local state and promote it to a global one without changing your component logic.
#Vanilla Local State
For local state, use createLocalState. It is exactly equal to React's native useState under the hood. You can safely use useState in place of it if you prefer! It is entirely private and local to that component instance.
ts
LocalCounter.tsx1// State is local and private
2const [counter, setCounter] = createLocalState(0)
3
4// You can also just use React's built-in hook:
5// const [counter, setCounter] = useState(0)
#Global Shared State
To share this state with other components, simply add a key as the first argument. SuperState will automatically register it in the global registry.
ts
GlobalCounter.tsx1// Key passed - state is global
2const [counter, setCounter] = createSuperState('counter', 0)
Habit-Preserving
Start every state as local. If you later realize you need to access it from another feature, just add a key and update the other component with
useSuperState('counter'). No refactors needed.#Reactivity & Comparison
Local state updates trigger standard React re-renders. Global state updates use useSyncExternalStore to notify only relevant components, often making global state *faster* than prop-drilled local state for complex trees.