state-management

State Management Patterns

When to Use This Skill

Use when:

• Setting up state management for a new React app
• Deciding between state solutions
• Implementing data fetching/caching
• Debugging stale state or unnecessary re-renders
• Migrating from Redux or other state libraries

State Categories Decision Tree

What kind of state?
├── UI State (local) → useState / useReducer
│   └── Shared across 2-3 components → Lift state up
├── UI State (global) → Zustand
│   └── Theme, sidebar open, modals, toasts
├── Server State → TanStack Query
│   └── API data, caching, background refetching
├── URL State → useSearchParams / nuqs
│   └── Filters, pagination, sort, tab selection
└── Form State → React Hook Form + Zod
    └── Inputs, validation, submission

1. Local State — useState / useReducer

Use for: Component-scoped UI state that doesn't need sharing.

// Simple toggle
const [isOpen, setIsOpen] = useState(false);

// Complex state with multiple transitions — use useReducer
type Action =
  | { type: 'FETCH_START' }
  | { type: 'FETCH_SUCCESS'; data: Item[] }
  | { type: 'FETCH_ERROR'; error: string };

interface State {
  items: Item[];
  loading: boolean;
  error: string | null;
}

function reducer(state: State, action: Action): State {
  switch (action.type) {
    case 'FETCH_START':
      return { ...state, loading: true, error: null };
    case 'FETCH_SUCCESS':
      return { items: action.data, loading: false, error: null };
    case 'FETCH_ERROR':
      return { ...state, loading: false, error: action.error };
  }
}

Rule: If you have 3+ related useState calls that change together, switch to useReducer.

2. Global UI State — Zustand

Use for: State shared across many components (theme, auth status, notifications, layout).

Setup

pnpm add zustand

Store Pattern

// src/stores/use-app-store.ts
import { create } from 'zustand';
import { devtools, persist } from 'zustand/middleware';

interface AppState {
  theme: 'light' | 'dark';
  sidebarOpen: boolean;
  setTheme: (theme: 'light' | 'dark') => void;
  toggleSidebar: () => void;
}

export const useAppStore = create<AppState>()(
  devtools(
    persist(
      (set) => ({
        theme: 'light',
        sidebarOpen: true,
        setTheme: (theme) => set({ theme }),
        toggleSidebar: () => set((s) => ({ sidebarOpen: !s.sidebarOpen })),
      }),
      { name: 'app-store' }
    )
  )
);