Introduction to SuperState
Zero-setup, key-based global state for React. Designed to be as simple as `useState` but with the power of shared synchronization.
#Why SuperState?
Most state management libraries require you to rethink your entire architecture. SuperState is different. It promotes local habits—you write your state like you're in a local component, and promote it to global when you need it.
Zero Boilerplate
No store files, no <Provider> at the root, and no complex setup.
Fine-grained
Only components watching a specific key re-render. Performance by default.
Use Sync External Store
SuperState is built on React 18's
useSyncExternalStore, ensuring perfect synchronization across your app with zero hydration or tearing issues.#Basic Usage
SuperState uses an **Owner / Consumer** pattern. The owner component initializes the state, and any consumer component can access it using the same key.
#1. Installation
ts
app/page.tsx1npm install react-use-superstate
#2. Using the Hooks
Use createSuperState to initialize and own the state, and useSuperState to consume it elsewhere.
ts
Components.tsx1import { createSuperState, useSuperState } from "react-use-superstate"
2
3// 1. Initial State Owner
4function Navbar() {
5 const [user] = createSuperState('user', { name: 'Ahsan', age: 25 })
6 return <h3>Welcome, {user.name}</h3>
7}
8
9// 2. Global Consumer
10function Profile() {
11 // Pass the key to consume existing state
12 const [user, setUser] = useSuperState('user')
13
14 return (
15 <button onClick={() => setUser({ ...user, age: user.age + 1 })}>
16 Increment Age
17 </button>
18 )
19}
Next SectionInstallation