Client State Management

Choosing the right state management approach requires understanding that “state” is not monolithic—different categories have fundamentally different requirements. Server state needs caching, deduplication, and background sync. UI state needs fast updates and component isolation. Form state needs validation and dirty tracking. Conflating these categories is the root cause of most state management complexity.

Abstract

Client state management reduces to one principle: match the tool to the state category.

• Server state (API data) → Use TanStack Query or SWR. These handle caching, deduplication, background refetch, and optimistic updates. Trying to manage server state with Redux or Context creates cache invalidation nightmares.
• UI state → Start with useState. Escalate to Context for cross-component sharing, Zustand for module-level state, or Jotai for fine-grained reactivity. Global state libraries are overkill for most UI state.
• Form state → Use React Hook Form for performance-critical forms (uncontrolled inputs, minimal re-renders). Built-in browser validation covers most cases.
• URL state → Store filters, pagination, and view modes in query parameters. Makes state shareable and survives refresh.
• Derived state → Compute, don’t store. Use selectors with memoization to avoid stale data and reduce state surface area.

The 2025 consensus: push server state to specialized libraries, keep global state minimal, and let URLs carry shareable state.

State Categories

Not all state is equal. Each category has distinct characteristics that dictate the right management approach.

Server State

Data fetched from APIs. Characteristics:

Why specialized tools exist: Managing server state with useState or Redux requires manually handling caching, deduplication, background refetch, cache invalidation, and optimistic updates. TanStack Query and SWR solve these problems out of the box.

UI State

Local, synchronous state for user interactions:

• Modal open/closed
• Dropdown selections
• Accordion expansion
• Animation states
• Component-specific flags

Design principle: UI state should live as close to where it’s used as possible. Lifting state to global stores creates unnecessary coupling and re-renders.

Form State

Specialized category with unique requirements:

Why form libraries exist: Native form handling with useState creates excessive re-renders (every keystroke triggers render). Libraries like React Hook Form use uncontrolled inputs to batch updates.

URL State

Query parameters and path segments that represent application state:

1
/products?category=electronics&sort=price&page=2

Why URL state matters:

1. Shareable — Users can share filtered views
2. Bookmarkable — Browser back/forward works correctly
3. Server-renderable — Initial state from URL, no hydration mismatch
4. Debuggable — State visible in address bar

Persistent State

State that survives page refresh or browser close:

Server State Management

The Stale-While-Revalidate Pattern

SWR (the library) is named after RFC 5861’s stale-while-revalidate cache directive. The pattern:

1. Return cached (potentially stale) data immediately
2. Revalidate in the background
3. Update UI when fresh data arrives

Why this design: Users see instant responses while data freshness is maintained. The alternative—waiting for network—creates perceived slowness even on fast connections.

TanStack Query Deep Dive

As of TanStack Query v5, the core caching model uses two time-based controls:

Critical relationship: gcTime must be ≥ staleTime. If cache is garbage collected before data goes stale, you lose the cached data before you’d naturally refetch it.

2 collapsed lines
1
import { QueryClient } from "@tanstack/react-query"
2

3
// Aggressive refetching (default): always revalidate
4
const defaultConfig = {
5
  staleTime: 0, // Data immediately stale
6
  gcTime: 5 * 60_000, // Keep in cache 5 minutes
7
}
8

9
// Conservative refetching: stable data
10
const stableDataConfig = {
11
  staleTime: 15 * 60_000, // Fresh for 15 minutes
8 collapsed lines
12
  gcTime: 30 * 60_000, // Cache for 30 minutes
13
}
14

15
const queryClient = new QueryClient({
16
  defaultOptions: {
17
    queries: defaultConfig,
18
  },
19
})

When staleTime > 0 makes sense:

• User profile data (changes infrequently)
• Configuration/feature flags
• Reference data (countries, currencies)
• Data with explicit invalidation triggers

Design rationale behind staleTime: 0 default: TanStack Query chose safety over efficiency. Stale data causes bugs that are hard to trace; extra network requests are visible and debuggable.

Automatic Refetch Triggers

TanStack Query refetches stale queries on:

Production consideration: Disable refetchOnWindowFocus for data that rarely changes or where refetch is expensive:

3 collapsed lines
1
import { useQuery } from "@tanstack/react-query"
2

3
useQuery({
4
  queryKey: ["analytics", "dashboard"],
5
  queryFn: fetchDashboard,
6
  refetchOnWindowFocus: false, // Heavy query, explicit refresh only
7
  staleTime: 5 * 60_000,
8
})

Request Deduplication

TanStack Query automatically deduplicates in-flight requests:

4 collapsed lines
1
// Both components mount simultaneously
2
// Only ONE network request is made
3

4
// Component A
5
const { data } = useQuery({ queryKey: ["user", 1], queryFn: fetchUser })
6

7
// Component B (mounts at same time)
8
const { data } = useQuery({ queryKey: ["user", 1], queryFn: fetchUser })
9
// ↑ Shares the in-flight request from Component A

How it works: Query keys are serialized and compared. If a request for that key is already pending, subsequent calls wait for the same Promise.

Cache Invalidation Strategies

Invalidation marks queries as stale, triggering refetch if they’re currently rendered.

3 collapsed lines
1
import { useQueryClient } from "@tanstack/react-query"
2

3
const queryClient = useQueryClient()
4

5
// Invalidate all queries starting with 'todos'
6
queryClient.invalidateQueries({ queryKey: ["todos"] })
7

8
// Invalidate exact key only
9
queryClient.invalidateQueries({
10
  queryKey: ["todos", "list"],
11
  exact: true,
12
})
13

14
// Predicate-based invalidation
15
queryClient.invalidateQueries({
16
  predicate: (query) => query.queryKey[0] === "todos" && query.state.data?.some((todo) => todo.assignee === userId),
17
})
18

19
// Invalidate and refetch immediately (don't wait for render)
20
queryClient.invalidateQueries({
21
  queryKey: ["todos"],
22
  refetchType: "all", // Also refetch inactive queries
23
})

Design decision: Invalidation is separate from refetching. invalidateQueries only marks as stale—actual refetch happens when the query is rendered. Use refetchQueries for immediate network call regardless of render state.

Optimistic Updates

Update the UI immediately, roll back on error:

5 collapsed lines
1
import { useMutation, useQueryClient } from "@tanstack/react-query"
2

3
interface Todo {
4
  id: string
5
  title: string
6
  completed: boolean
7
}
8

9
const queryClient = useQueryClient()
10

11
const mutation = useMutation({
12
  mutationFn: updateTodo,
13
  onMutate: async (newTodo) => {
14
    // Cancel outgoing refetches (they'd overwrite optimistic update)
15
    await queryClient.cancelQueries({ queryKey: ["todos"] })
16

17
    // Snapshot previous value
18
    const previous = queryClient.getQueryData<Todo[]>(["todos"])
19

20
    // Optimistically update
21
    queryClient.setQueryData<Todo[]>(["todos"], (old) => old?.map((t) => (t.id === newTodo.id ? newTodo : t)))
22

23
    // Return snapshot for rollback
24
    return { previous }
25
  },
26
  onError: (err, newTodo, context) => {
27
    // Roll back on error
28
    queryClient.setQueryData(["todos"], context?.previous)
29
  },
30
  onSettled: () => {
31
    // Refetch to ensure server state
32
    queryClient.invalidateQueries({ queryKey: ["todos"] })
33
  },
34
})

Why onSettled invalidation: Even on success, the server might have modified the data (timestamps, computed fields). Invalidation ensures the cache matches server state.

SWR Comparison

SWR takes a more minimal approach:

When to choose SWR: Simpler apps, smaller bundle priority, preference for minimal API. SWR’s mutate function handles most cases without dedicated mutation hooks.

Global UI State

When Global State Is Necessary

Global state is appropriate when:

1. Multiple unrelated components need the same data
2. No common ancestor can reasonably hold the state
3. State persists across route changes

Common legitimate cases:

• Authentication state
• Theme/appearance settings
• Feature flags
• Toast/notification queue
• Modal registry

When to Avoid Global State

Server state doesn’t belong in global stores. This was the primary mistake of early Redux applications. Patterns like “fetch in action creator, store in Redux” create:

• Manual cache invalidation logic
• No request deduplication
• No background refetch
• Complex loading state management

“With the hooks provided by React, you can share these pieces of application state with the rest of the application. No need for a library to do it for you.” — Kent C. Dodds, “Application State Management with React”

React Context Limitations

Context is not optimized for frequent updates:

3 collapsed lines
1
import { createContext, useContext, useState } from 'react'
2

3
interface AppState {
4
  user: User
5
  theme: 'light' | 'dark'
6
  notifications: Notification[]
7
}
8

9
const AppContext = createContext<AppState | null>(null)
10

11
function App() {
12
  const [state, setState] = useState<AppState>(/* ... */)
13

14
  return (
15
    <AppContext.Provider value={state}>
16
      <Header />      {/* Re-renders when notifications change */}
17
      <Sidebar />     {/* Re-renders when theme changes */}
18
      <NotificationBell />  {/* The only component that needs notifications */}
19
    </AppContext.Provider>
20
  )
21
}

Problem: Every context consumer re-renders when any part of the context value changes, even if that consumer only uses a subset.

Solutions:

1. Split contexts — One context per concern (theme, auth, notifications)
2. Memoize values — useMemo to prevent new object references
3. External stores — Zustand/Jotai with selective subscriptions

Zustand: Module-First State

Zustand (12KB gzipped) provides a minimal API with selective subscriptions:

2 collapsed lines
1
import { create } from 'zustand'
2

3
interface BearStore {
4
  bears: number
5
  fish: number
6
  increasePopulation: () => void
7
  eatFish: () => void
8
}
9

10
const useBearStore = create<BearStore>((set) => ({
11
  bears: 0,
12
  fish: 10,
13
  increasePopulation: () => set((state) => ({ bears: state.bears + 1 })),
14
  eatFish: () => set((state) => ({ fish: state.fish - 1 })),
15
}))
16

17
// Selective subscription — only re-renders when bears changes
18
function BearCounter() {
19
  const bears = useBearStore((state) => state.bears)
20
  return <h1>{bears} bears</h1>
21
}
22

23
// Different subscription — only re-renders when fish changes
24
function FishCounter() {
25
  const fish = useBearStore((state) => state.fish)
26
  return <h1>{fish} fish</h1>
27
}

Design rationale: Zustand uses useSyncExternalStore internally. Selectors enable components to subscribe to specific slices, avoiding the Context re-render problem.

Jotai: Atomic State

Jotai (bottom-up) vs Zustand (top-down):

2 collapsed lines
1
import { atom, useAtom, useAtomValue, useSetAtom } from 'jotai'
2

3
// Primitive atoms
4
const countAtom = atom(0)
5
const doubledAtom = atom((get) => get(countAtom) * 2)  // Derived
6

7
// Component only subscribes to what it reads
8
function Counter() {
9
  const [count, setCount] = useAtom(countAtom)
10
  return <button onClick={() => setCount(c => c + 1)}>{count}</button>
11
}
12

13
// Read-only subscription (no setter in bundle)
14
function Display() {
15
  const doubled = useAtomValue(doubledAtom)
16
  return <span>{doubled}</span>
17
}
18

19
// Write-only (no subscription, no re-render on change)
20
function ResetButton() {
21
  const setCount = useSetAtom(countAtom)
22
  return <button onClick={() => setCount(0)}>Reset</button>
23
}

When Jotai over Zustand:

• Fine-grained reactivity needed (many independent pieces)
• Derived state with complex dependency graphs
• Preference for bottom-up composition

Redux Toolkit: When Scale Demands It

Redux remains appropriate for:

• Large teams needing strict patterns
• Complex middleware requirements (sagas, thunks)
• Time-travel debugging critical
• Existing Redux investment

Modern Redux ≠ boilerplate Redux. RTK (Redux Toolkit) eliminates most ceremony:

3 collapsed lines
1
import { createSlice, PayloadAction } from "@reduxjs/toolkit"
2

3
interface CounterState {
4
  value: number
5
}
6

7
const counterSlice = createSlice({
8
  name: "counter",
9
  initialState: { value: 0 } as CounterState,
10
  reducers: {
11
    increment: (state) => {
12
      state.value += 1
13
    }, // Immer handles immutability
14
    incrementByAmount: (state, action: PayloadAction<number>) => {
15
      state.value += action.payload
16
    },
17
  },
18
})
19

20
export const { increment, incrementByAmount } = counterSlice.actions
21
export default counterSlice.reducer

Decision Matrix

Form State Management

Why Form Libraries Exist

Native controlled inputs re-render on every keystroke:

2 collapsed lines
1
// Every character typed re-renders the entire component
2
function NaiveForm() {
3
  const [values, setValues] = useState({ email: '', password: '' })
4

5
  return (
6
    <form>
7
      <input
8
        value={values.email}
9
        onChange={(e) => setValues(v => ({ ...v, email: e.target.value }))}
10
      />
11
      {/* Form re-renders on every keystroke */}
12
    </form>
13
  )
14
}

With 10+ fields and validation, this creates noticeable lag on lower-end devices.

React Hook Form

React Hook Form (12KB) uses uncontrolled inputs with refs:

4 collapsed lines
1
import { useForm } from 'react-hook-form'
2
import { zodResolver } from '@hookform/resolvers/zod'
3
import { z } from 'zod'
4

5
const schema = z.object({
6
  email: z.string().email(),
7
  password: z.string().min(8),
8
})
9

10
type FormData = z.infer<typeof schema>
11

12
function LoginForm() {
13
  const {
14
    register,
15
    handleSubmit,
16
    formState: { errors, isSubmitting }
17
  } = useForm<FormData>({
18
    resolver: zodResolver(schema),
19
  })
20

21
  const onSubmit = async (data: FormData) => {
22
    await login(data)
23
  }
24

25
  return (
26
    <form onSubmit={handleSubmit(onSubmit)}>
27
      <input {...register('email')} />
28
      {errors.email && <span>{errors.email.message}</span>}
29

6 collapsed lines
30
      <input type="password" {...register('password')} />
31
      {errors.password && <span>{errors.password.message}</span>}
32

33
      <button disabled={isSubmitting}>Submit</button>
34
    </form>
35
  )
36
}

Performance model: Inputs are uncontrolled (DOM holds value). Re-renders only happen when:

• formState properties you’re subscribed to change
• Explicit watch() calls
• Validation errors change

When to Use Native Forms

React Hook Form is overkill for:

• Login forms (2-3 fields)
• Search inputs
• Simple settings toggles

Native HTML validation covers basic cases:

1
<input type="email" required minlength="3" pattern="[a-z]+" />

Derived State and Selectors

Compute, Don’t Store

Storing derived data creates synchronization bugs:

1
// ❌ Storing derived state
2
interface State {
3
  items: Item[]
4
  completedItems: Item[] // Derived from items
5
  completedCount: number // Derived from completedItems
6
}
7

8
// ✅ Computing derived state
9
interface State {
10
  items: Item[]
11
}
12

13
const completedItems = items.filter((i) => i.completed)
14
const completedCount = completedItems.length

Why computation is better:

1. Single source of truth (no sync bugs)
2. Less state to manage
3. Automatic consistency

Memoized Selectors

For expensive computations, memoize with Reselect or useMemo:

3 collapsed lines
1
import { createSelector } from "reselect"
2

3
const selectItems = (state: State) => state.items
4

5
const selectCompletedItems = createSelector([selectItems], (items) => items.filter((i) => i.completed))
6

7
const selectCompletedCount = createSelector([selectCompletedItems], (completed) => completed.length)
8

9
// Reselect memoizes by reference equality
10
// If items hasn't changed, cached result is returned

How Reselect works: Input selectors are called first. If their results are referentially equal to the previous call, the output selector is skipped and cached result returned.

Zustand Selectors

2 collapsed lines
1
import { useStore } from "./store"
2

3
// Component re-renders only when filtered result changes
4
function CompletedList() {
5
  const completed = useStore((state) => state.items.filter((i) => i.completed))
6
  // ⚠️ Creates new array every time — need memoization
7
}
8

9
// Better: external memoized selector
10
import { createSelector } from "reselect"
11

12
const selectCompleted = createSelector(
13
  (state: State) => state.items,
14
  (items) => items.filter((i) => i.completed),
15
)
16

17
function CompletedList() {
18
  const completed = useStore(selectCompleted) // Stable reference
19
}

State Machines with XState

When State Machines Are Necessary

State machines excel when:

1. States have impossible combinations — isLoading && hasError && hasData shouldn’t all be true
2. Transitions matter — Can only go from idle → loading, not idle → success
3. Complex sequences — Multi-step wizards, checkout flows
4. Parallel states — Audio playing while video loading

XState v5 Example

3 collapsed lines
1
import { setup, assign, fromPromise } from "xstate"
2

3
interface Context {
4
  data: User | null
5
  error: Error | null
6
}
7

8
const fetchMachine = setup({
9
  types: {} as {
10
    context: Context
11
    events: { type: "FETCH"; id: string } | { type: "RETRY" }
12
  },
13
  actors: {
14
    fetchUser: fromPromise(async ({ input }: { input: { id: string } }) => {
15
      const response = await fetch(`/api/users/${input.id}`)
16
      if (!response.ok) throw new Error("Failed")
17
      return response.json()
18
    }),
19
  },
20
}).createMachine({
21
  id: "fetch",
22
  initial: "idle",
23
  context: { data: null, error: null },
24
  states: {
25
    idle: {
26
      on: { FETCH: "loading" },
27
    },
28
    loading: {
29
      invoke: {
30
        src: "fetchUser",
31
        input: ({ event }) => ({ id: event.id }),
32
        onDone: {
33
          target: "success",
34
          actions: assign({ data: ({ event }) => event.output }),
35
        },
36
        onError: {
37
          target: "failure",
38
          actions: assign({ error: ({ event }) => event.error }),
39
        },
40
      },
41
    },
42
    success: {
43
      on: { FETCH: "loading" },
44
    },
45
    failure: {
46
      on: { RETRY: "loading" },
47
    },
48
  },
49
})

What XState provides:

• Type-safe transitions — TypeScript enforces valid state/event combinations
• Visualization — Export to state diagram
• Testing — Model-based testing against the machine
• Impossible states eliminated — Can’t be loading and failed simultaneously

When State Machines Are Overkill

• Simple toggles (open/closed)
• Linear forms without complex validation
• CRUD operations (TanStack Query handles state)

Rule of thumb: If you can express it clearly with useState + a few conditionals, don’t add XState’s complexity.

Real-World Implementations

Figma: WebGL + Custom State

Challenge: Millions of objects on infinite canvas

Approach:

• WebGL rendering (bypasses DOM entirely)
• R-tree spatial indexing for viewport queries
• Level-of-detail: simplify distant objects
• Custom state synchronization (no off-the-shelf library)

Key insight: At Figma’s scale, no existing state library worked. They built custom solutions optimized for their specific access patterns.

Notion: Block-Based State

Challenge: Documents with 10K+ blocks, real-time collaboration

Approach:

• Block-based data model (each block has type, content, children)
• Redux for client state
• Transactions for grouping changes
• Kafka + Spark for server-side propagation

Local update pattern:

1. User edits block
2. Change grouped into transaction
3. Optimistic update to Redux
4. Transaction sent to server
5. Server broadcasts to collaborators

Linear: MobX + WebSockets

Challenge: Real-time project management across teams

Approach:

• MobX for reactive state
• Bootstrap full state on load
• WebSocket stream of changesets
• Merge local and remote changes continuously

Why MobX: Linear chose observable-based reactivity for automatic UI updates when any referenced data changes.

Discord: Event Sourcing for Messages

Challenge: Millions of messages per second

Architecture evolution:

1. MongoDB (couldn’t scale)
2. Cassandra (scales but complex)
3. Event sourcing for message history

State requirements:

• Stateful processes tracking user → socket mapping
• Separate processes holding actual WebSocket connections
• Event log as source of truth for message state

Performance Optimization

Re-render Prevention

State Normalization

For relational data, normalize to avoid duplication:

1
// ❌ Denormalized (data duplication)
2
interface State {
3
  posts: Array<{
4
    id: string
5
    author: { id: string; name: string } // Duplicated across posts
6
    content: string
7
  }>
8
}
9

10
// ✅ Normalized (single source of truth)
11
interface State {
12
  users: Record<string, User>
13
  posts: Record<string, { id: string; authorId: string; content: string }>
14
}

Benefits:

• O(1) lookup by ID
• Single place to update user name
• Smaller state size (no duplication)

Mobile Considerations

Mobile devices have tighter constraints:

Offline-first pattern:

1. Store critical data in IndexedDB
2. Queue mutations when offline
3. Sync when connection restored
4. Resolve conflicts (last-write-wins or merge)

Browser Constraints

Storage Quotas

Safari limitation: Safari’s 1GB IndexedDB cap and 50MB Cache API limit make it the constraint for offline-heavy apps.

Main Thread Budget

60fps = 16ms per frame. State updates compete with:

• Layout calculation
• Paint
• JavaScript execution
• Garbage collection

Mitigation strategies:

1. Web Workers — Heavy computation off main thread
2. requestIdleCallback — Non-critical state updates
3. Chunked updates — Split large state changes across frames

Conclusion

State management in 2025 is solved—the challenge is selecting the right solution for each category:

1. Server state → TanStack Query/SWR. Stop managing caches manually.
2. UI state → Keep it local. useState handles most cases.
3. Shared UI state → Zustand or Jotai. Not Redux unless you need its ecosystem.
4. Form state → React Hook Form. Performance matters at scale.
5. Shareable state → URL params. Users can bookmark and share.
6. Complex workflows → XState. When state transitions are the problem.

The pattern across successful products: minimize global state, specialize tools by category, and push server data to purpose-built libraries.

Appendix

Prerequisites

• React hooks (useState, useReducer, useContext, useMemo)
• Async JavaScript (Promises, async/await)
• REST API patterns
• Basic understanding of caching concepts

Terminology

Summary

• Match tool to category: Server state needs TanStack Query/SWR, not Redux
• Server state libraries handle: Caching, deduplication, background refetch, optimistic updates
• Context re-renders all consumers: Split contexts or use external stores for frequent updates
• Zustand for modules, Jotai for atoms: Choose based on state granularity needs
• Compute derived state: Don’t store what you can calculate
• URL state is shareable state: Filters, pagination, view modes belong in query params

References

• TanStack Query Documentation — Caching, invalidation, mutations
• SWR Documentation — Stale-while-revalidate implementation
• RFC 5861: HTTP Cache-Control Extensions — Origin of stale-while-revalidate
• Zustand Documentation — Module-first state management
• Jotai Documentation — Atomic state management
• XState Documentation — State machines and actors
• React Hook Form Documentation — Performant form handling
• Kent C. Dodds: Application State Management with React — When to use which approach
• Redux: Normalizing State Shape — Entity normalization patterns
• Figma Engineering Blog — Custom state at scale
• Notion: The data model behind Notion — Block-based architecture
• Linear Engineering — Real-time state sync patterns