React State Management Patterns
There is no one-size-fits-all state tool. This skill covers the most common choices and when each fits.
Decision tree
| Data | Tool |
|---|
| Local component state (count, isOpen, hover) | useState, useReducer |
| Shared between siblings / parent-child | Lift to common parent + props |
| App-wide UI state (theme, locale, sidebar open) | Context, Zustand, Jotai |
| Complex domain state with many actions | Redux Toolkit (or Zustand for simpler cases) |
| Server data with caching, pagination, refetch | TanStack Query, SWR |
| Form state | react-hook-form (see react-forms skill) |
| URL-synced state | URL params via useSearchParams |
Detect what the project uses and follow its pattern. Don't introduce a new state lib without BA approval.
useState and useReducer
const [count, setCount] = useState(0);
// Function form for updates depending on previous state
setCount((c) => c + 1);
// Reducer for complex state with discriminated actions
const [state, dispatch] = useReducer(reducer, initialState);
When state has more than ~3 fields and updates are coordinated, prefer useReducer:
type State = { items: Item[]; loading: boolean; error: string | null };
type Action =
| { type: 'fetch_start' }
| { type: 'fetch_success'; items: Item[] }
| { type: 'fetch_error'; error: string };
function reducer(state: State, action: Action): State {
switch (action.type) {
case 'fetch_start': return { ...state, loading: true, error: null };
case 'fetch_success': return { ...state, loading: false, items: action.items };
case 'fetch_error': return { ...state, loading: false, error: action.error };
}
}
Context API
For values shared across many components without prop drilling. Best for relatively static or rarely-changing data (theme, locale, current user).
import { createContext, useContext, useState } from 'react';
type Theme = 'light' | 'dark';
const ThemeContext = createContext<{ theme: Theme; setTheme: (t: Theme) => void } | null>(null);
export function ThemeProvider({ children }: { children: React.ReactNode }) {
const [theme, setTheme] = useState<Theme>('light');
return <ThemeContext.Provider value={{ theme, setTheme }}>{children}</ThemeContext.Provider>;
}
export function useTheme() {
const ctx = useContext(ThemeContext);
if (!ctx) throw new Error('useTheme must be used within ThemeProvider');
return ctx;
}
Context pitfall: rerender storms
Every consumer of a Context re-renders when the Context value changes. For frequently-updating state, this is expensive. Solutions:
- Split contexts: one for state, one for setters (setters are stable references).
- Memoize the value:
const value = useMemo(() => ({ theme, setTheme }), [theme]).
- Switch to Zustand or Jotai (they use direct subscriptions, not React's Context).
For app-wide state that updates frequently, prefer Zustand/Jotai over Context.
Zustand
Lightweight (pnpm add zustand). Simple API, no Provider needed.
// stores/userStore.ts
import { create } from 'zustand';
type User = { id: string; name: string };
type UserStore = {
user: User | null;
setUser: (user: User | null) => void;
logout: () => void;
};
export const useUserStore = create<UserStore>((set) => ({
user: null,
setUser: (user) => set({ user }),
logout: () => set({ user: null }),
}));
Usage:
const user = useUserStore((s) => s.user);
const setUser = useUserStore((s) => s.setUser);
Selectors ((s) => s.user) prevent unrelated re-renders. Without a selector, the component re-renders on every store change.
Persistence and middleware
import { create } from 'zustand';
import { persist, createJSONStorage } from 'zustand/middleware';
export const useUserStore = create(
persist(
(set) => ({ user: null, setUser: (user) => set({ user }) }),
{ name: 'user-storage', storage: createJSONStorage(() => sessionStorage) }
)
);
NEVER persist auth tokens to localStorage / sessionStorage — XSS risk.
Jotai
Atomic state — each piece is an atom. Best for fine-grained state where many components subscribe to small slices.
import { atom, useAtom } from 'jotai';
export const userAtom = atom<User | null>(null);
export const themeAtom = atom<'light' | 'dark'>('light');
// Derived atom
export const isAuthenticatedAtom = atom((get) => get(userAtom) !== null);
Usage:
const [user, setUser] = useAtom(userAtom);
const isAuth = useAtomValue(isAuthenticatedAtom);
Jotai is great for forms with many independent fields, atomic updates, or React Suspense integration. Less idiomatic for big domain stores.
Redux Toolkit (RTK)
For complex domain state with many actions, time-travel debugging, or large team conventions.
// features/users/usersSlice.ts
import { createSlice, createAsyncThunk, PayloadAction } from '@reduxjs/toolkit';
export const fetchUsers = createAsyncThunk('users/fetch', async () => {
const res = await fetch('/api/users');
return res.json() as Promise<User[]>;
});
const slice = createSlice({
name: 'users',
initialState: { items: [] as User[], loading: false, error: null as string | null },
reducers: {
add: (state, action: PayloadAction<User>) => {
state.items.push(action.payload);
},
},
extraReducers: (builder) => {
builder
.addCase(fetchUsers.pending, (state) => { state.loading = true; })
.addCase(fetchUsers.fulfilled, (state, action) => { state.loading = false; state.items = action.payload; })
.addCase(fetchUsers.rejected, (state, action) => { state.loading = false; state.error = action.error.message ?? 'failed'; });
},
});
export const { add } = slice.actions;
export default slice.reducer;
// store.ts
import { configureStore } from '@reduxjs/toolkit';
import users from './features/users/usersSlice';
export const store = configureStore({ reducer: { users } });
export type RootState = ReturnType<typeof store.getState>;
export type AppDispatch = typeof store.dispatch;
// hooks.ts
import { useDispatch, useSelector } from 'react-redux';
import type { RootState, AppDispatch } from './store';
export const useAppDispatch = useDispatch.withTypes<AppDispatch>();
export const useAppSelector = useSelector.withTypes<RootState>();
For most apps in 2024+, RTK is overkill — Zustand or Jotai is lighter. Pick RTK when:
- Time-travel debugging matters.
- Strong team familiarity with Redux conventions.
- RTK Query is already used for server state.
TanStack Query (server state)
For data that lives on the server. Handles caching, deduplication, refetching, pagination, mutation-then-invalidation.
// features/users/api.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
export function useUsers() {
return useQuery({
queryKey: ['users'],
queryFn: async () => {
const res = await fetch('/api/users');
if (!res.ok) throw new Error('Failed to fetch');
return res.json() as Promise<User[]>;
},
});
}
export function useUser(id: string) {
return useQuery({
queryKey: ['users', id],
queryFn: () => fetch(`/api/users/${id}`).then((r) => r.json() as Promise<User>),
enabled: !!id,
});
}
export function useCreateUser() {
const qc = useQueryClient();
return useMutation({
mutationFn: (input: CreateUserInput) =>
fetch('/api/users', { method: 'POST', body: JSON.stringify(input) }).then((r) => r.json()),
onSuccess: () => {
qc.invalidateQueries({ queryKey: ['users'] });
},
});
}
Usage:
function UsersList() {
const { data, isLoading, error } = useUsers();
if (isLoading) return <Spinner />;
if (error) return <Error error={error} />;
return <ul>{data?.map((u) => <li key={u.id}>{u.name}</li>)}</ul>;
}
Query key conventions
Use array keys with hierarchical structure:
['users'] // list
['users', id] // single
['users', { filter: 'active' }] // filtered list
['users', id, 'orders'] // sub-resource
invalidateQueries({ queryKey: ['users'] }) invalidates ALL keys starting with ['users'] — handy for "users changed somewhere, refresh everything."
Mutations
const { mutate, isPending } = useCreateUser();
mutate({ email: 'a@b.c', name: 'Alice' }, {
onSuccess: (user) => router.push(`/users/${user.id}`),
onError: (err) => toast.error(err.message),
});
Always invalidate or update queries after mutation success. Otherwise UI shows stale data.
Optimistic updates
useMutation({
mutationFn: deleteUser,
onMutate: async (id) => {
await qc.cancelQueries({ queryKey: ['users'] });
const previous = qc.getQueryData<User[]>(['users']);
qc.setQueryData<User[]>(['users'], (old) => old?.filter((u) => u.id !== id) ?? []);
return { previous };
},
onError: (_err, _id, context) => {
qc.setQueryData(['users'], context?.previous);
},
onSettled: () => qc.invalidateQueries({ queryKey: ['users'] }),
});
SWR (alternative to TanStack Query)
import useSWR from 'swr';
const fetcher = (url: string) => fetch(url).then((r) => r.json());
function Users() {
const { data, error, isLoading } = useSWR<User[]>('/api/users', fetcher);
if (isLoading) return <Spinner />;
if (error) return <Error />;
return <ul>{data?.map((u) => <li key={u.id}>{u.name}</li>)}</ul>;
}
Simpler API than TanStack Query, slightly less feature-rich. Match the project.
URL state (useSearchParams)
For state that should be shareable / bookmarkable / browser-back-compatible:
import { useSearchParams } from 'react-router-dom';
function FilteredList() {
const [params, setParams] = useSearchParams();
const filter = params.get('filter') ?? 'all';
return (
<>
<select value={filter} onChange={(e) => setParams({ filter: e.target.value })}>
<option value="all">All</option>
<option value="active">Active</option>
</select>
</>
);
}
Use for filters, pagination, sort order, search queries — anything users want to return to.
Anti-patterns
- ❌ Reaching for Redux when
useState + a Context would do.
- ❌ Using Context for fast-changing state (causes re-render storm).
- ❌ Forgetting
invalidateQueries after mutations — stale UI.
- ❌ Storing server data in
useState and manually refetching — that's what TanStack Query/SWR are for.
- ❌ Persisting auth tokens to localStorage (XSS-readable).
- ❌ Multiple
useState calls for clearly-coordinated state — use useReducer.
- ❌ Lifting state to root just because two distant components both need it — use Context or a store.
- ❌ Mutating state in place (
state.items.push(x) followed by setState(state)) — React shallow-compares; same reference = no re-render.
- ❌
dispatch(action()) outside a Redux Toolkit slice — actions ARE creators in RTK, just call dispatch(slice.actions.add(payload)).