State Management

The 30-second version

"Should we use Redux?" is the wrong first question. Most state bugs come from data that lives in the wrong place: two copies that disagree, a whole page that re-renders on every keystroke, filters that vanish when you press Back, or a list from the server that's quietly out of date.

StateState (React)Data a component remembers between renders, like the text in a search box. Changing it with its setter makes React render that component again. is data that can change while the page is open and that the screen depends on: a counter, a search text, the logged-in user, a list of orders. When it changes, React re-rendersRender (React)React calling your component function to get a description of the UI. It's cheap-ish and can happen often; changing the real DOM happens later, in the commit.: it calls your components again to work out the new screen.

So there isn't one kind of state; there are roughly five, and each has a natural home:

Try sorting some real examples:

Local state, and lifting it up

Local state is the default, and it's the best kind: only one component can change it, so when it's wrong you know exactly where to look. A dropdown's open flag, a hover, the text in a single input: all local.

function Dropdown({ options }) {
  const [open, setOpen] = useState(false);   // ← nobody else needs this
  return (
    <div>
      <button onClick={() => setOpen((o) => !o)}>Sort by ▾</button>
      {open && <ul>{options.map((o) => <li key={o}>{o}</li>)}</ul>}
    </div>
  );
}

When a sibling needs it

Now a page has a <SearchBox> and a <ResultList> next to each other. The list must filter by what's typed in the box. If each keeps its own q (the query text) in useState, they can't talk: a component can only pass data down to its children, never sideways to a sibling. Try it, then flip the toggle:

With the state lifted, FruitPage owns q. It passes the value down to both children, and passes setQ down to the box so the box can change it. Data flows down as props; changes flow up through functions passed down.

function FruitPage() {
  const [q, setQ] = useState("");             // ← one q, owned by the common parent
  return (
    <>
      <SearchBox q={q} onChange={setQ} />     {/* can change it */}
      <ResultList q={q} />                    {/* can read it */}
      <Footer />
    </>
  );
}

function SearchBox({ q, onChange }) {
  return <input value={q} onChange={(e) => onChange(e.target.value)} />;
}

Lifting gives you a single source of truthSingle source of truthEach piece of data is stored in exactly one place; everything else reads it from there or computes from it. Two copies of the same data will eventually disagree.: one q, stored once. Two copies of the same data always drift apart eventually, so whenever you catch yourself keeping two things in sync with code, lift them into one.

The cost: re-renders spread with the state

Look at the counters in the lifted mode again. Every keystroke re-rendered FruitPage and all its children, including Footer, which uses nothing. That's not a bug: when a component re-renders, React re-renders its children too (How React Works §06 explains why). The higher the state lives, the more components each change re-renders.

So lift state only as high as needed, to the nearest common parent, and no higher. Keeping state close to where it's used is called colocationColocation (of state)Keeping state as close as possible to the components that use it: in the component itself if only it needs it, in the nearest common parent if a few do. The opposite of putting everything at the top.. It's the single most effective "performance optimization" in React, and it's free.

function App() {
  const [q, setQ] = useState("");
  const [menuOpen, setMenuOpen] = useState(false);
  const [hovered, setHovered] = useState(null);
  // typing in a search box re-renders
  // the header, the menu, the footer…
  return <Layout q={q} setQ={setQ} menuOpen={menuOpen} /* … */ />;
}

function App() {
  return <Layout />;        // no state needed here
}
function SearchPage() {
  const [q, setQ] = useState("");  // only this page
  /* … */
}
function Menu() {
  const [open, setOpen] = useState(false); // only the menu
  /* … */
}

Prop drilling, and two ways out

Lifting state (§02) has a side effect: the owner can end up far above the component that shows the value. In between sit layout components that have to accept the prop and pass it along, like buckets passed hand to hand down a line. That's prop drillingProp drillingPassing a prop down through several layers of components that don't use it themselves, only so a component deep below can receive it..

Here's the same tree wired three ways. Watch which components have to mention user:

function App() {
  const [user] = useState({ name: "Ana" });
  return <Layout user={user} />;
}
function Layout({ user }) {           // doesn't use it…
  return (<><Header /><Sidebar user={user} /><Main /></>);
}
function Sidebar({ user }) { return <Nav user={user} />; }   // …nor this
function Nav({ user })     { return <UserMenu user={user} />; } // …nor this
function UserMenu({ user }) { return <span>{user.name}</span>; }

Drilling isn't evil

Two or three levels of props are fine, and often the clearest option: the data flow is visible in the code, and a component's props tell you exactly what it depends on. Drilling becomes a problem when the in-between components multiply, change often, or are shared by many pages. Then every rename touches all of them.

Fix 1: composition

Most drilling happens because a layout component builds its children itself. Let it accept them instead. A component that renders {children} doesn't need to know what's inside, so the owner can pass user straight to the component that uses it. This approach is called compositionComposition (children)Building components by passing other elements in, usually as children: <Layout><UserMenu user={user} /></Layout>. Layout just renders {children} and never needs to know what's inside..

function App() {
  const [user] = useState({ name: "Ana" });
  return (
    <Layout sidebar={<UserMenu user={user} />}>   {/* ← an element passed as a prop */}
      <Dashboard user={user} />                    {/* ← and as children */}
    </Layout>
  );
}

function Layout({ sidebar, children }) {           // knows nothing about user
  return (
    <div className="grid">
      <aside>{sidebar}</aside>
      <main>{children}</main>
    </div>
  );
}

Composition costs nothing at runtime and keeps the data flow visible. It's the fix to try first.

Fix 2: context

When many components in different branches need the same value (the theme, the current user, the language), composition gets awkward. ContextContext (React)A way to pass a value to every component below a Provider without threading it through props at each level. Components read it with useContext (or use() in React 19) and re-render when it changes. In React 19 you can write <MyContext value={…}> instead of <MyContext.Provider value={…}>. lets a component provide a value once and any component below read it directly:

const ThemeContext = createContext("light");      // 1. create it (with a default)

function App() {
  const [theme, setTheme] = useState("dark");
  return (
    <ThemeContext value={theme}>                   {/* 2. provide a value */}
      <Page />
    </ThemeContext>
  );
}

function Button() {
  const theme = useContext(ThemeContext);          // 3. read it anywhere below
  return <button className={theme}>OK</button>;
}

Context solves the "passing" problem. It's tempting to go one step further and put all shared state in one big context, as a home-made store. The next section measures what that costs.

Context as a store, and what it costs

A common pattern is to combine context with useReducer and call it a store. If you've only used useState, useReducer needs three new words, so here they are first (more in React Hooks §04).

With useState you set the new value yourself. With useReducer you describe what happened and one function decides the new state:

• An actionActionA plain object describing what happened, by convention with a type field: { type: "bump", i: 7 } or { type: "cart/add", payload: item }. You hand it to dispatch; the reducer reads it and decides the new state. is a plain object describing what happened: { type: "bump", i: 7 } means "seat 7 was clicked".
• A reducerReducer (useReducer)A pure function (state, action) => newState that holds all the rules for changing one piece of state. Components describe what happened by calling dispatch({ type: … }); the reducer decides the new state. is a function (state, action) => newState that holds all the rules in one place.
• dispatchdispatchThe function you call with an action (dispatch({ type: "bump", i: 7 })). It runs the reducer with the current state and that action, stores whatever the reducer returns, and triggers the re-renders. is the function useReducer gives you instead of a setter. dispatch(action) calls reducer(currentState, action), and whatever it returns becomes the new state.

Here's the reducer for a seat board (48 seat counters plus a title):

const initialBoard = { title: "Seat map", seats: Array(48).fill(0) };

function boardReducer(state, action) {
  switch (action.type) {
    case "bump": {
      const seats = state.seats.slice();       // copy the array…
      seats[action.i] = seats[action.i] + 1;   // …change the copy
      return { ...state, seats };              // ← always a NEW state object
    }
    case "title":
      return { ...state, title: action.title };
    default:
      return state;                            // unknown action: no change
  }
}

Now put state and dispatch into a context so any component can use them:

const BoardContext = createContext(null);

function BoardProvider({ children }) {
  const [state, dispatch] = useReducer(boardReducer, initialBoard);
  const value = useMemo(() => ({ state, dispatch }), [state]);   // ← new object when state changes
  return <BoardContext value={value}>{children}</BoardContext>;
}

function Seat({ i }) {
  const { state, dispatch } = useContext(BoardContext);
  const value = state.seats[i];                                  // uses one number…
  return <button onClick={() => dispatch({ type: "bump", i })}>{value}</button>;
}

Step through one click on seat 7, from the action to the re-renders:

1function boardReducer(state, action) {
2  switch (action.type) {
3    case "bump": {
4      const seats = state.seats.slice();   // copy the array
5      seats[action.i] = seats[action.i] + 1; // change the copy
6      return { ...state, seats };          // a new state object
7    }
8    case "title":
9      return { ...state, title: action.title };
10    default:
11      return state;                        // unknown action: no change
12  }
13}
14 
15// inside <Seat i={7}>
16<button onClick={() => dispatch({ type: "bump", i: 7 })} />

It works, and for a small app it's fine. But look at Seat: it uses one number and reads the whole value. React has no way to know which part a component cares about. When any seat changes, state is a new object, so value is a new object, so every Seat re-renders. Click one seat and count:

One click, about fifty re-renders, and every component here is wrapped in memoReact.memoA wrapper (memo(Component)) that makes React skip re-rendering that component when its parent re-renders, as long as every prop is the same value (Object.is) as last time.. memo only skips a re-render when the props are unchanged; a context change goes around it. Typing in the title box is worse: each keystroke re-renders all 48 seats, which don't show the title at all.

Is that actually slow?

Usually not, at this size. A re-render means React called the function; if the output is the same, nothing on the page changes (How React Works §06). We measured these fifty tiny components re-rendering in about 1.6 ms in a production build (this machine, headless Chromium). It becomes a problem when the readers are many, expensive (big lists, charts), or the value changes very often (every keystroke, every mouse move, a timer). Then the work adds up to visible lag, and the cure is to re-render fewer components, not to make each one faster.

Making context cheaper

const BoardState = createContext(null);
const BoardDispatch = createContext(null);

function BoardProvider({ children }) {
  const [state, dispatch] = useReducer(boardReducer, initialBoard);
  return (
    <BoardDispatch value={dispatch}>          {/* dispatch is stable: readers never re-render */}
      <BoardState value={state}>{children}</BoardState>
    </BoardDispatch>
  );
}

None of these fixes lets a Seat say "re-render me only when seat 7 changes". For that you need state that lives outside React and lets each component subscribe to its own slice. That's an external store, and we'll build one in the next section.

An external store from scratch

Zustand, Redux and their cousins all work this way at the core. Building the small version yourself is the fastest way to understand what they do, and what their rules (like "never mutate") are protecting.

The store

export function createStore(initial) {
  let state = initial;                      // lives outside React
  const listeners = new Set();              // who to tell about changes

  return {
    getState: () => state,
    subscribe(listener) {
      listeners.add(listener);
      return () => listeners.delete(listener);   // ← hand back an "unsubscribe"
    },
    setState(update) {
      const next = typeof update === "function" ? update(state) : update;
      if (Object.is(next, state)) return;        // same object → nothing changed
      state = next;
      listeners.forEach((l) => l());             // tell everyone
    },
  };
}

This is the publish/subscribePublish/subscribe (pub/sub)Senders (publishers) emit messages without knowing who receives them; receivers (subscribers) sign up for the kinds of message they care about. The two sides never reference each other directly. idea (also called the observer pattern, see Behavioral patterns): the store doesn't know who's listening or why; it just calls every listenerListener (subscriber)A function a store keeps in a list and calls after every change, so whoever registered it can react, for example by asking React to re-check a component. after a change.

Connecting it to React

React needs two things from an external storeExternal storeState that lives outside React, for example a module variable, localStorage or a browser API, plus a way to subscribe to changes. useSyncExternalStore connects one to components safely.: a way to subscribe (so it hears about changes) and a way to read the current value. useSyncExternalStore takes exactly those:

import { useSyncExternalStore } from "react";

export function useStore(store, selector) {
  return useSyncExternalStore(
    store.subscribe,                      // React calls this once, and the returned function on unmount
    () => selector(store.getState()),     // "the snapshot": what this component wants, right now
  );
}

// in a component
const value = useStore(boardStore, (s) => s.seats[i]);   // ← only seat i

The second function returns the snapshotSnapshot (useSyncExternalStore)The value a component reads from an external store right now, returned by the function you pass to useSyncExternalStore. React compares it with the previous snapshot using Object.is to decide whether to re-render.. After every change, React calls it again and compares the result with the previous one using Object.is (===, except it treats NaN as equal to itself). Same value: React skips this component. Different value: it re-renders. That comparison is what context can't do. Step through one click:

1function createStore(initial) {
2  let state = initial;
3  const listeners = new Set();
4  return {
5    getState: () => state,
6    subscribe(listener) {
7      listeners.add(listener);
8      return () => listeners.delete(listener);
9    },
10    setState(update) {
11      const next = typeof update === "function" ? update(state) : update;
12      if (Object.is(next, state)) return;
13      state = next;
14      listeners.forEach((l) => l());
15    },
16  };
17}
18 
19function useStore(store, selector) {
20  return useSyncExternalStore(
21    store.subscribe,
22    () => selector(store.getState()),
23  );
24}

Why not useEffect + useState?

You could subscribe in an effect and copy the value into useState. It mostly works, but React can pause a render halfway through and continue later (concurrent renderingConcurrent renderingReact's ability to prepare a render in small slices, pause to let the browser handle input, and throw a half-done render away if newer data arrives. Still one thread; it's about interruption, not parallelism., see How React Works §10). If the store changes during that pause, some components show the old value and some the new one, a glitch called tearingTearingDifferent components on screen showing different versions of the same outside value during one render, because the value changed while React was halfway through. useSyncExternalStore prevents it.. useSyncExternalStore guarantees one consistent value per render. React Hooks §12 shows this site's own store built the same way.

Real libraries add conveniences on top: actions bundled with the state, middleware, devtools, persistence. But the mechanism you just stepped through is the whole idea.

Selectors: subscribe to a slice

Here is the board from §04 again, now with a switch. "useContext" is the context store from §04; "store + selector" is the createStore from §05, with each seat reading s => s.seats[i]. Click a seat in each mode, then type in the title:

With the store, one click re-renders one seat and the total, because those are the only two components whose selected value changed. Typing in the title re-renders only the title. Same components, same memo, the only difference is how they subscribe.

What we measured in a production build, clicking one seat (this machine, headless Chromium, median of 40 clicks):

Both are fast here, because the components are tiny, and part of each number is fixed overhead that doesn't depend on how many components re-render. What grows is the count: 50 re-renders versus 2. Put 2,000 rows or a chart in each component and the context version does 25× the rendering work on every change.

The same thing with Zustand

StoreStoreAn object that holds state outside your components, lets code read it (getState), change it (setState or dispatch) and subscribe to be told when it changes. Zustand and Redux are libraries that give you one. libraries give you this pattern ready-made. Zustand is the smallest popular one; create returns a hook that takes a selector:

import { create } from "zustand";

export const useCart = create((set) => ({
  owner: "Ana",
  items: [],
  add: (item) => set((s) => ({ items: [...s.items, item] })),   // ← actions live in the store
  clear: () => set({ items: [] }),
}));

// any component, no provider needed
function CartBadge() {
  const count = useCart((s) => s.items.length);    // re-renders only when the count changes
  return <span>{count}</span>;
}
function AddButton({ item }) {
  const add = useCart((s) => s.add);               // functions never change: never re-renders
  return <button onClick={() => add(item)}>Add</button>;
}

And with Redux Toolkit

Redux is older and more structured: changes are described as actions (plain objects like { type: "cart/add", payload: item }), and a reducer decides the new state. Redux Toolkit is the official, modern way to write it:

import { configureStore, createSlice } from "@reduxjs/toolkit";

const cartSlice = createSlice({
  name: "cart",
  initialState: { items: [] },
  reducers: {
    add(state, action) {
      state.items.push(action.payload);   // ← looks like mutation; Immer makes a copy
    },
  },
});

export const { add } = cartSlice.actions;   // add(item) → { type: "cart/add", payload: item }
export const store = configureStore({ reducer: { cart: cartSlice.reducer } });

import { useDispatch, useSelector } from "react-redux";

function CartBadge() {
  const count = useSelector((s) => s.cart.items.length);
  return <span>{count}</span>;
}
function AddButton({ item }) {
  const dispatch = useDispatch();
  return <button onClick={() => dispatch(add(item))}>Add</button>;
}
// once, at the top: <Provider store={store}><App /></Provider>

Which one? Zustand is less code and has no provider. Redux Toolkit adds a strict action log, excellent devtools (replay every action), and conventions that help big teams. Both use useSyncExternalStore underneath, and both re-render by selector.

The selector that loops forever

Every selector rule comes down to Object.is. This looks harmless:

const { owner, count } = useCart((s) => ({ owner: s.owner, count: s.items.length }));

The selector builds a new object every time it's called. React calls it, compares with the previous result, sees a different object, re-renders, calls it again, gets another new object… With Zustand 5, React logs The result of getSnapshot should be cached to avoid an infinite loop and then throws Maximum update depth exceeded. (React Redux doesn't loop, because it compares more carefully, but it warns in development that the selector "returned a different result when called with the same parameters" and re-renders on every store change.)

Three fixes:

// 1. one selector per value (simplest)
const owner = useCart((s) => s.owner);
const count = useCart((s) => s.items.length);

// 2. Zustand: compare the object field by field
import { useShallow } from "zustand/react/shallow";
const { owner, count } = useCart(useShallow((s) => ({ owner: s.owner, count: s.items.length })));

// 3. Redux: a memoized selector for derived data
import { createSelector } from "@reduxjs/toolkit";
const selectPricey = createSelector([(s) => s.cart.items], (items) => items.filter((it) => it.price > 50));
const pricey = useSelector(selectPricey);   // same array back until s.cart.items changes

useShallow compares the old and new objects with shallow equalityShallow equalityTwo objects count as equal if they have the same keys and each value is === to the other's. Nested objects are compared by identity, not opened up. Zustand's useShallow uses it.: same keys, each value ===. createSelector builds a memoized selectorMemoized selectorA selector that remembers its last inputs and result, and returns the very same result object when the inputs haven't changed (for example with Reselect's createSelector). Lets a selector build arrays or objects without causing extra renders.: it remembers its last input (s.cart.items) and returns the very same output array until that input changes.

The URL is state too

Imagine sending a colleague a link to "lamps under $100, sorted by price, page 2". If the filters live in useState, the link opens an unfiltered first page, a reload throws your filters away, and Back leaves the shop entirely. Users notice all three.

Put the filters in the query stringQuery stringThe part of a URL after the ?, made of key=value pairs joined by &: ?q=lamp&page=2. In JavaScript you read and build it with URLSearchParams. instead: /products?q=lamp&sort=price&page=2. Try both versions in this simulated browser tab:

Reading and writing the query string

The browser has a built-in parser, URLSearchParams, and two functions that change the address without loading a new page, from the History APIHistory API (pushState / replaceState)Browser functions that change the address bar without loading a new page. pushState adds a new entry to the Back-button list; replaceState overwrites the current one. The popstate event fires when the user goes Back or Forward.:

// read
const params = new URLSearchParams(location.search);    // location.search is "?q=lamp&page=2"
const q = params.get("q") ?? "";                         // "lamp"
const page = Math.max(1, Number(params.get("page")) || 1); // a string: convert, and fall back to 1

// write
params.set("page", "3");
history.pushState(null, "", `?${params}`);       // new entry: Back returns to page 2
history.replaceState(null, "", `?${params}`);    // same entry, updated: Back skips it

// listen for Back / Forward
window.addEventListener("popstate", () => render(new URLSearchParams(location.search)));

Push or replace? Push for deliberate steps a user might want to go back to: changing page, switching tab, applying a filter. Replace for continuous changes like typing, otherwise Back walks through ?q=l, ?q=la, ?q=lam one letter at a time. Flip "typing: pushState" in the demo to feel the difference.

In a React app, use the router

You rarely call pushState yourself; your router wraps it and re-renders on changes. With React Router, useSearchParams works like a useState that lives in the URL:

import { useSearchParams } from "react-router";

function Products() {
  const [params, setParams] = useSearchParams();
  const q = params.get("q") ?? "";
  const page = Math.max(1, Number(params.get("page")) || 1);   // the URL is user input: validate it

  return (
    <>
      <input
        value={q}
        onChange={(e) => setParams({ q: e.target.value }, { replace: true })}  // ← typing: replace
        // an object replaces ALL params, so page (and anything else) resets: wanted for a new search
      />
      <button onClick={() => setParams({ q, page: String(page + 1) })}>Next</button>  {/* push */}
      <ProductList q={q} page={page} />
    </>
  );
}

There's no useState for q or page at all: they're derived from the URL on every render, so they can't disagree with it. Next.js (useSearchParams + router.replace), TanStack Router (typed search params) and the nuqs library offer the same idea with different APIs.

Server state: a cache, not a store

In most apps, the biggest chunk of "global state" is server data: the user, the orders, the product list. Teams used to fetch it in an effect and copy it into a Redux store. That means writing loading flags, error flags, caching, refetching and "is this still current?" logic by hand, for every endpoint.

That strategy has a name: stale-while-revalidateStale-while-revalidateServing the old cached copy for a short while after it expires, while one background request fetches a fresh copy. Readers never wait; they may see data a little out of date., the same idea as the HTTP header of that name (Caching). Here's how it plays out when you return to a profile you've seen before:

A query cache, live

The demo below runs a real (small) query cache. It works like TanStack Query, the most widely used library for this, with the same vocabulary. Things to try:

1. Ana → Bo → Ana. The first visit to each shows a spinner. Going back to Ana is instant from cache, while a background refetch runs.
2. "2 cards, same key", then switch person. Two components ask for the same data; the log shows one request.
3. "Move Ana on the server". The cache doesn't know. Then press invalidate or simulate window focus and watch it catch up.
4. Set staleTime 15 s and repeat step 1: no refetch while the data is fresh.
5. Switch away from someone and wait 20 seconds: their entry is removed (gcTime).

The vocabulary

• Query keyQuery keyThe name a query library stores fetched data under, such as ['user', 7]. Same key means same cache entry; a different key means a different request and a different entry.: the name the data is stored under, like ["user", 1]. Same key, same entry. A different key (a different user) is a different entry and a different request. Put everything the request depends on into the key.
• staleTimestaleTimeHow long freshly fetched data counts as fresh. While fresh, a query library serves it from cache without refetching. TanStack Query's default is 0: data is stale immediately, so it's refetched in the background at the next chance.: how long fresh data stays fresh. TanStack Query's default is 0: data is stale the moment it arrives. "Stale" doesn't mean "hidden"; it means "show it, but refetch at the next opportunity" (a component mounting, window focus, reconnecting).
• DeduplicationRequest deduplicationWhen several components ask for the same data at the same moment, sending one request and giving all of them its result, instead of one request each.: if a request for a key is already in flight, a second component waits for that one instead of sending another.
• gcTimegcTime (garbage-collection time)How long a query library keeps a cache entry that no component is using any more before deleting it. TanStack Query's default is 5 minutes in the browser.: how long an entry nobody is using stays in the cache. TanStack Query's default is 5 minutes in the browser. (The demo uses 20 seconds so you can watch it happen.)

The same thing in TanStack Query

import { useQuery } from "@tanstack/react-query";

function Profile({ userId }) {
  const { data, isPending, isFetching, error } = useQuery({
    queryKey: ["user", userId],                          // ← the cache key
    queryFn: ({ signal }) =>
      fetch(`/api/users/${userId}`, { signal }).then((r) => {
        if (!r.ok) throw new Error(`HTTP ${r.status}`);  // fetch doesn't throw on 404/500
        return r.json();
      }),
    staleTime: 30_000,                                   // fresh for 30 s
  });

  if (isPending) return <Spinner />;                     // nothing cached yet
  if (error) return <p>Couldn't load: {error.message}</p>;
  return <h2>{data.name} {isFetching && "⟳"}</h2>;       // cached data + background refresh
}
// once, at the top:
// const queryClient = new QueryClient();
// <QueryClientProvider client={queryClient}><App /></QueryClientProvider>

We checked the two key claims against TanStack Query 5 in a real browser: two components with the same key mounted together made one call, and invalidateQueries made the active query fetch again. SWR (by Vercel) and RTK Query (part of Redux Toolkit) work the same way with different names.

Changing server data: invalidate or be optimistic

A request that changes server data (POST, PUT, PATCH, DELETE) is a mutationMutation (server data)A request that changes data on the server (POST, PUT, PATCH, DELETE), as opposed to a query, which only reads. After a mutation, cached copies of that data may be out of date.. The query cache from §08 doesn't know what your mutation changed, so you tell it.

Option 1: invalidate, then refetch

import { useMutation, useQueryClient } from "@tanstack/react-query";

function AddTodo() {
  const queryClient = useQueryClient();
  const mutation = useMutation({
    mutationFn: (text) =>
      fetch("/api/todos", {
        method: "POST",
        headers: { "Content-Type": "application/json" },   // tell the server the body is JSON
        body: JSON.stringify({ text }),
      }).then((r) => {
        if (!r.ok) throw new Error(`HTTP ${r.status}`);    // ← a 500 must fail, or onSuccess runs
        return r.json();
      }),
    onSuccess: () =>
      queryClient.invalidateQueries({ queryKey: ["todos"] }),   // ← every key starting with "todos"
  });

  return (
    <button disabled={mutation.isPending} onClick={() => mutation.mutate("Buy milk")}>
      {mutation.isPending ? "Adding…" : "Add"}
    </button>
  );
}

Two details matter. fetch only rejects when the network fails; a 404 or 500 still "succeeds", so the r.ok check turns it into an error, and then onSuccess doesn't run and mutation.error is set. And the Content-Type header tells the server how to read the body; many servers ignore a JSON body without it.

InvalidationCache invalidationRemoving or updating cached copies when the original data changes, so readers don't keep seeing stale values. Famously one of the hard problems in computing. marks matching entries stale, and the ones on screen refetch right away (you tried this with the ✱ button in §08). It matches by prefix: ["todos"] covers ["todos"], ["todos", { done: true }] and ["todos", 7]. It's simple and always correct, because the server's answer is the truth. The cost is one extra round trip before the user sees the result.

Option 2: optimistic updates

For small, likely-to-succeed actions (a like, a checkbox, renaming), waiting feels sluggish. An optimistic updateOptimistic UIThe screen shows the result of an action right away, assuming it will succeed, and marks it as pending until the server confirms. If the server says no, the screen rolls back. shows the result immediately, marks it as pending, and undoes it if the request fails. That undo is the rollbackRollbackUndoing a change you already showed on screen because the server rejected it: the UI goes back to the last value the server confirmed.. Try both styles, with a working and a failing server:

Here's what each style shows over time, for a server that takes 900 ms:

React 19 has a hook for exactly this, useOptimistic. The demo uses it:

import { startTransition, useOptimistic, useState } from "react";

function TodoList({ initial }) {
  const [todos, setTodos] = useState(initial);               // what the server confirmed
  const [shown, addOptimistic] = useOptimistic(              // what the screen shows
    todos,
    (current, { id, done }) => current.map((t) => (t.id === id ? { ...t, done, pending: true } : t)),
  );

  function toggle(todo) {
    const done = !todo.done;
    startTransition(async () => {
      addOptimistic({ id: todo.id, done });                  // ← on screen right now
      try {
        await saveTodo(todo.id, done);
        startTransition(() =>
          setTodos((ts) => ts.map((t) => (t.id === todo.id ? { ...t, done } : t))));
      } catch {
        showToast("Couldn't save. Try again.");              // the optimistic value disappears by itself
      }
    });
  }
  return shown.map((t) => <Row key={t.id} todo={t} onToggle={() => toggle(t)} />);
}

TanStack Query supports the same pattern through onMutate (update the cache and remember the old value), onError (put the old value back) and onSettled (invalidate to be sure), for cases where the optimistic value must appear in several components that read the same cache key.

Form state

A form needs more state than it seems: the values, which fields the user has touched (left at least once), which are dirty (changed from the start), the validation errors, and whether a submit is in progress. The question is who holds the values.

const [email, setEmail] = useState("");
<input
  value={email}                        // React decides
  onChange={(e) => setEmail(e.target.value)}
/>
// every keystroke → setState → re-render

A controlled inputControlled inputA form field whose value comes from React state (value={name}) and is updated in onChange. React is the source of truth, so every keystroke is a state update and a re-render. gets its value from state, so React knows the text at all times: easy to validate as you type, format a phone number, or disable the submit button. An uncontrolled inputUncontrolled inputA form field that keeps its own value in the DOM, like plain HTML. React may give it a starting value (defaultValue) and reads it when needed, typically on submit with FormData or a ref. keeps its text in the page itself, as plain HTML does; you read everything at the end with FormDataFormDataA browser object holding a form's fields as name → value pairs: new FormData(formElement). Each input needs a name attribute to be included.. Both are valid tools. Type in each mode below and watch the render counter:

// React state, updated on every keystroke
values  = {"name":"","email":""}
touched = {}
errors  = {}   // computed

React 19 form actions

React 19 lets you pass a function to <form action={…}>. React calls it with the form's FormData when the form is submitted. Combined with useActionState, you get the last result and a pending flag without writing any state yourself. The third mode in the demo is this:

import { useActionState } from "react";

function SignupForm() {
  const [state, formAction, isPending] = useActionState(
    async (previousState, formData) => {                  // ← runs on submit
      const email = String(formData.get("email"));
      const result = await signup(email);                 // call your server
      return result.ok
        ? { error: "", email: "" }
        : { error: result.message, email };               // ← send the typed text back
    },
    { error: "", email: "" },                             // the initial state
  );

  return (
    <form action={formAction}>
      <input name="email" defaultValue={state.email} />  {/* ← keeps the text after the reset */}
      {state.error && <p role="alert">{state.error}</p>}
      <button disabled={isPending}>{isPending ? "Saving…" : "Sign up"}</button>
    </form>
  );
}

When to validate

Errors shown on the first keystroke are annoying ("not an email" after typing a). A common rule: validate a field when the user leaves it (on blur), then re-check as they type once an error is showing, and validate everything on submit. That's what the "touched" set in the controlled demo is for. And always validate again on the server: the browser's checks are a convenience, not a security measure.

Where form state does not go

For big forms (dozens of fields, arrays of rows, complex validation), a form library saves a lot of code. React Hook Form is built on uncontrolled inputs, so typing in one field doesn't re-render the whole form; pair it with a schema library like Zod to describe the rules once and reuse them on the server.

Staff level: choosing, structuring, and SSR

A decision guide

Walk down the list and stop at the first "yes":

The order matters: the first questions remove the most state. Teams that answer the server-data question first usually find the last two rows hold very little.

Shaping a store that stays maintainable

When the same record shows up in several places (a user in a list, in a detail panel and in a comment), store it once, keyed by id. That's normalized stateNormalized stateStoring each record once, in a lookup table keyed by id ({ byId: { 7: {…} }, ids: [7, 9] }), and referring to it by id elsewhere, instead of copying the same object into several lists.: a lookup table, like a hash map, plus lists of ids.

// nested: Ana is copied into every post. Rename her → find and fix every copy.
{ posts: [{ id: 1, author: { id: 7, name: "Ana" } }, { id: 2, author: { id: 7, name: "Ana" } }] }

// normalized: Ana is stored once; posts refer to her by id.
{
  users: { byId: { 7: { id: 7, name: "Ana" } } },
  posts: { byId: { 1: { id: 1, authorId: 7 }, 2: { id: 2, authorId: 7 } }, ids: [1, 2] },
}

Redux Toolkit's createEntityAdapter generates this shape and its update functions for you. Query caches avoid the problem differently: each query has its own copy and invalidation refreshes them together.

Stores and server rendering

A store created at module level (export const store = createStore(…), or Zustand's create) is one object per JavaScript process. In the browser that's one per tab, which is what you want. On a server that renders pages for many users (Rendering strategies), it's one object shared by every request: user A's cart can appear in user B's HTML. Create a per-request storePer-request storeOn a server that renders pages, a fresh store created for each incoming request, so one user's data can never leak into another user's page through a shared module-level variable. instead, inside the component tree, and hand it down through context:

const StoreContext = createContext(null);

export function StoreProvider({ initial, children }) {
  const [store] = useState(() => createStore(initial));   // ← created once per mounted tree, i.e. per request on the server
  return <StoreContext value={store}>{children}</StoreContext>;
}

export function useAppStore(selector) {
  const store = useContext(StoreContext);                  // the store object never changes: no context re-renders
  return useSyncExternalStore(store.subscribe, () => selector(store.getState()), () => selector(store.getState()));
}

This is the shape the board in §06 uses, and the one Zustand's docs recommend for Next.js (createStore from zustand/vanilla plus a context). Context carries the store object, which never changes, so it causes no extra re-renders; the selectors do the subscribing. The third argument to useSyncExternalStore is the snapshot used during server rendering and HydrationHydrationMaking server-rendered HTML interactive: the browser runs the same components, attaches event handlers to the existing markup, and takes over.; it must give the same value the server used, or React reports a hydration mismatch. TanStack Query has the same rule: create the QueryClient per request on the server.

Persistence, testing, devtools

• Persistence. Saving a store to localStorage (Zustand's persist middleware, redux-persist) is easy. The hard parts: the saved shape outlives your code, so version it and write migrations; and the server can't read localStorage, so the first render must match the server's (load after HydrationHydrationMaking server-rendered HTML interactive: the browser runs the same components, attaches event handlers to the existing markup, and takes over., or accept a flash). Browser Storage covers what's safe to store.
• Testing. A reducer or a store is a plain function or object: test it with no React at all (store.setState(…), then check store.getState()). Test components against a real store created per test, not a mock, so selectors are exercised too.
• Devtools. Redux DevTools shows every action and the state after it, and can step backwards. Zustand can connect to the same extension with its devtools middleware. A log of "what happened, in order" is the best debugging tool for state bugs.

Transitions and external stores

One trade-off to know: updates to an external store can't be marked non-urgent. React's startTransition (How React Works §10) can interrupt and delay renders caused by React state, but a change to a store read through useSyncExternalStore is always rendered as urgent. React's docs say that if the store changes during a transition, React falls back to rendering that update as blocking, which is the price of never showing TearingTearingDifferent components on screen showing different versions of the same outside value during one render, because the value changed while React was halfway through. useSyncExternalStore prevents it.. If you need useDeferredValue or transitions on top of store data, select the value from the store, then defer it in the component.

Pitfalls

Check yourself: predict what happens

Commit to an answer before you click. Each explanation points back to the section that covers it.

const CartBadge = memo(function CartBadge() {
  const { cart } = useContext(AppContext);
  return <span>{cart.items.length}</span>;
});

const { name, count } = useAppStore((s) => ({
  name: s.name,
  count: s.count,
}));

store.setState((s) => {
  s.count += 1;   // change it in place
  return s;
});

Cheat sheet

Symptom → cause → fix