State management

State is data that changes over time

A small program is easy to follow when all its data lives inside one function. A web app is harder. One click can change the header, a form, the web address, and a list of results all at once. State management means two things:

• You decide which one place owns each changing value.
• You decide the one way that value is allowed to change.

State does not all live in one big shared place. Some state belongs to one part of the page. Some comes from the server. Some lives in the web address. Some is a form the user is still filling in. The skill is to pick the smallest owner that works. The next lesson, app architecture, shows how those owners fit into a whole app. This lesson stays with state itself.

The table below lists five kinds of state. Read each row as: "this kind of state is owned by this, for example these values."

In code, that one shared place is called the single source of truth. Every part of the page reads from it, so they all agree.

Work out values instead of storing them twice

Here is a common bug. You store the cart's items in cart.items. You also store how many there are in cartItemCount. Then you remove an item and forget to change the count. Now the header says 3 and the cart shows 2.

The fix is simple. Store only the items. Work out the count and the total from the items when you need them. A value you work out from other state is called derived state.

1const cart = [2  { name: "Tea", price: 12, qty: 2 },3  { name: "Mug", price: 5, qty: 1 },4];5 6const itemCount = cart.reduce((total, item) => total + item.qty, 0);7const total = cart.reduce((sum, item) => sum + item.price * item.qty, 0);8 9console.log(itemCount);10console.log(total.toFixed(2));

Line 1 stores the cart: an array of items. Only this array is stored.

• Line 6 works out the count. reduce walks through the array and adds up each item.qty, starting from 0.
• Line 7 works out the total the same way: price times quantity for each item, added up.
• Lines 9 and 10 print 3 and 29.00. The count is 3 because two teas count as two.

If the cart changes, you run lines 6 and 7 again and get fresh numbers. There is no second value to keep in step.

const cart = [];
const itemCount = cart.reduce((sum, item) => sum + item.qty, 0);

console.log(itemCount);

Line 2 starts reduce at 0. The cart has no items, so there is nothing to add. reduce just gives back its starting value, and line 4 prints 0.

A small function that reads or works out a value from state has a name: a selector. Working out a count like this is fast, so you can do it every time. Some apps save a result and reuse it while the inputs stay the same. That is called memoization. Only add it when the work is really slow, or when other code needs to get back the very same object each time.

const store = { cart: [{ name: "Tea", qty: 2 }] };
const headerCount = store.cart.reduce((sum, item) => sum + item.qty, 0);
const cartNames = store.cart.map((item) => item.name).join(", ");

console.log(headerCount);
console.log(cartNames);

Line 1 makes one store object that holds the cart. Line 2 works out the count for the header. Line 3 works out the item names for the cart page. Both read the same store.cart. The code prints 2 and Tea.

A store is an object that holds the state for the whole app. The store below is small. It has three methods:

• getState() gives back the current state.
• subscribe(listener) saves a function to call after every change. That function is a subscriber. subscribe gives back another function. Call it to unsubscribe, which means "stop calling me".
• dispatch(action) asks for a change. It is the only way to change the state.

An action is a plain object that says what happened, like { type: "cart/add", payload: { id: "tea" } }. The type names the change. The payload carries the data for it. A reducer is a function that takes the current state and an action, and gives back the next state. The next section looks at reducers closely.

Subscribers are like the observer pattern: they wait to be told about a change. The key point here is different: subscribers never keep their own copy of the cart. They read the store.

1function createStore(reducer, initialState) {Run2  let state = initialState;3  const listeners = new Set();4 5  return {6    getState() {7      return state;8    },9    subscribe(listener) {10      listeners.add(listener);11      return () => listeners.delete(listener);12    },13    dispatch(action) {14      const previousState = state;15      state = reducer(state, action);16      if (previousState !== state) {17        listeners.forEach((listener) => listener(state, action, previousState));18      }19      return action;20    },21  };22}23 24function cartReducer(state, action) {25  switch (action.type) {26    case "cart/add":27      return { ...state, items: [...state.items, action.payload] };28    default:29      return state;30  }31}32 33const store = createStore(cartReducer, { items: [] });34const unsubscribe = store.subscribe((state, action) => {35  console.log(action.type + ": " + state.items.length);36});37 38store.dispatch({ type: "cart/add", payload: { id: "tea", name: "Tea" } });39unsubscribe();40store.dispatch({ type: "cart/add", payload: { id: "mug", name: "Mug" } });41console.log(store.getState().items.map((item) => item.id).join(", "));

The step-through follows one change from start to end:

1. dispatch(action) hands the action to the store.
2. The reducer gives back the next state.
3. The store keeps that next state in place of the old one.
4. The store calls each subscriber, so each part of the page can show the new state.

Unsubscribing matters too. When a part of the page goes away, it should stop listening. Line 39 does that. The second dispatch on line 40 still changes the store, but nothing prints for it.

A reducer has this shape: (state, action) => nextState. It takes the current state and an action. It gives back the next state. A reducer must be a pure function. That means two rules:

• The same state and the same action always give the same result.
• It changes nothing outside itself. It doesn't fetch data, write to web storage, read the clock, or change the state it was given.

The pure functions lesson explains these rules in more detail.

const addItem = (item) => ({ type: "cart/add", item });
function reducer(state, action) {
  if (action.type === "cart/add") {
    return { ...state, items: [...state.items, action.item] };
  }
  return state;
}

const before = { items: [] };
const after = reducer(before, addItem("tea"));
console.log(after.items.join(", "));
console.log(reducer(after, { type: "cart/unknown" }) === after);

Line 1 is an action creator: a small function that builds an action object for you. addItem("tea") gives back { type: "cart/add", item: "tea" }.

• Lines 3 and 4 handle the add action. They give back a new state object with the item added.
• Line 6 handles every other action. It gives back the same state, unchanged.
• Line 11 prints tea: the added item.
• Line 12 sends an action the reducer doesn't know. It prints true, because the reducer gave back the very same object. That tells the store nothing changed.

A real app has more than one area of state. You can give each area its own reducer. Each area is called a slice. For example:

• A cart reducer changes only the cart's items.
• A UI reducer changes only whether the cart panel is open.
• A root reducer calls both and puts their results together.

1const addItem = (item) => ({ type: "cart/add", payload: item });2const toggleCart = () => ({ type: "ui/toggle-cart" });3 4function cartReducer(state = { items: [] }, action) {5  if (action.type === "cart/add") {6    return { ...state, items: [...state.items, action.payload] };7  }8  return state;9}10 11function uiReducer(state = { cartOpen: false }, action) {12  if (action.type === "ui/toggle-cart") {13    return { ...state, cartOpen: !state.cartOpen };14  }15  return state;16}17 18function combineReducers(reducers) {19  return (state, action) => {20    let changed = false;21    const next = {};22    for (const key of Object.keys(reducers)) {23      next[key] = reducers[key](state[key], action);24      changed = changed || next[key] !== state[key];25    }26    return changed ? next : state;27  };28}29 30const reducer = combineReducers({ cart: cartReducer, ui: uiReducer });31let state = { cart: { items: [] }, ui: { cartOpen: false } };32state = reducer(state, addItem({ id: "tea" }));33state = reducer(state, toggleCart());34console.log(state.cart.items.length);35console.log(state.ui.cartOpen);

Lines 1 and 2 are action creators. Line 4 starts the cart reducer, and line 11 starts the UI reducer. Lines 18 to 28 build the root reducer:

• Line 23 calls each slice reducer with its own part of the state.
• Line 24 notes whether any slice gave back a new object.
• Line 26 gives back the new root object only if something changed. Otherwise it gives back the old one.

Lines 32 and 33 send two actions. The code prints 1 (one cart item) and true (the cart panel is open).

A variable that holds an object really holds the object's address: where the object lives in memory. Two variables can hold the address of the same object. The objects and references lesson explains this.

State management uses this on purpose. A reducer never changes the old object. Instead it makes a new object with the change in it. This is called an immutable update. "Immutable" means "never changed". Changing an object in place is called mutating it.

Why bother? Because then one quick check tells you if anything changed: prevState !== nextState. A new object means a change. The same object means no change. Old states also stay as they were, so you can keep them for an undo button.

You only copy the parts that change. These tools make copies:

• Object spread, { ...obj }, from the spread and rest lesson.
• Array spread, [...arr], and the array methods map and filter.
• toSorted() and with(index, value). They give back a new array and leave the old one alone.

1const board = {2  user: { name: "Asha", badges: ["member"] },3  tasks: [4    { id: "draft", title: "Draft reducer", done: false },5    { id: "ship", title: "Ship lesson", done: false },6  ],7  priorities: ["low", "medium", "high"],8};9 10const nextBoard = {11  ...board,12  user: { ...board.user, badges: [...board.user.badges, "reviewer"] },13  tasks: board.tasks.map((task) =>14    task.id === "draft" ? { ...task, done: true } : task,15  ),16  priorities: board.priorities.with(1, "normal").toSorted(),17};18 19console.log(board.tasks[0].done);20console.log(nextBoard.tasks[0].done);21console.log(board.tasks === nextBoard.tasks);22console.log(nextBoard.priorities.join(", "));

Line 10 starts a new board. Line 11 copies everything from the old board into it. Then:

• Line 12 makes a new user with a new badges array that adds "reviewer".
• Lines 13 to 15 make a new tasks array. Only the "draft" task is replaced, by a copy with done: true.
• Line 16 swaps "medium" for "normal" with with, then sorts the result.

Lines 19 to 22 print false, true, false, and high, low, normal. The old task is still not done, and the old board is untouched. For more ways to copy, see immutability.

const state = {
  profile: { name: "Asha" },
  settings: { theme: "light" },
};
const next = {
  ...state,
  profile: { ...state.profile, name: "Mina" },
};

console.log(state.profile.name);
console.log(next.profile.name);
console.log(state.profile === next.profile);
console.log(state.settings === next.settings);

Lines 5 to 7 copy two objects: the outer state and the profile inside it. The name changes only in the copy. Line 10 prints Asha and line 11 prints Mina.

Line 12 prints false: the two profiles are different objects. Line 13 prints true: settings did not change, so both states share it. A spread only copies one level. If you spread only the outer object, both states would share one profile. Changing the name would then change the old state too.

1function createStore(reducer, initialState) {2  let state = initialState;3  const listeners = new Set();4 5  return {6    getState() {7      return state;8    },9    subscribe(listener) {10      listeners.add(listener);11      return () => listeners.delete(listener);12    },13    dispatch(action) {14      const previousState = state;15      state = reducer(state, action);16      if (previousState !== state) {17        listeners.forEach((listener) => listener(state, action));18      }19    },20  };21}22 23function badCartReducer(state, action) {24  if (action.type === "cart/add") {25    state.items.push(action.payload);26    return state;27  }28  return state;29}30 31const store = createStore(badCartReducer, { items: [] });Run32const renders = [];33store.subscribe((state) => {34  renders.push("rendered " + state.items.length);35});36 37store.dispatch({ type: "cart/add", payload: { id: "tea" } });38console.log(renders.length);39console.log(store.getState().items.length);

The step-through above shows the bug slowly. On line 25, push adds the item to the old array. The cart really changes. But the reducer gives back the same state object. So the store's check finds the same object, decides nothing changed, and skips the subscriber. The page would keep showing the old cart.

1const template = {2  user: { name: "Asha" },3  created: new Date("2026-09-26T00:00:00Z"),4};5 6const copy = structuredClone(template);7copy.user.name = "Mina";8 9console.log(template.user.name);10console.log(copy.user.name);11console.log(Object.prototype.toString.call(copy.created));

structuredClone(value) is a built-in function that makes a deep copy: it copies the object and every object inside it. Line 6 copies the template. Line 7 changes the copy's name. Line 9 prints Asha, so the original did not change. Line 10 prints Mina. Line 11 shows the date was copied as a real Date.

It is handy, but it is not how reducers usually copy:

• It throws an error for functions and page elements.
• Copying the whole state is much more work than copying the one part that changed.
• Parts that did not change become new objects too, so the quick "same object?" check stops working for them.

1// Conceptual Immer-style code. Immer is not installed in this lesson.2const nextState = produce(state, (draft) => {3  draft.cart.items.push({ id: "tea", name: "Tea" });4  draft.ui.cartOpen = true;5});

Immer is a library with a produce function. You write code that seems to change a draft, a stand-in for the state. Immer watches those changes and builds a new state from them. The old state is never touched. Immer is not installed here, so this block only shows the idea and does not run.

Reducers are good for changing data. Some state is different: it moves through a few named stages. A request to a server, for example, is always in one of four stages:

• idle: nothing has happened yet.
• loading: the request was sent, and we are waiting.
• success: the answer came back.
• error: something went wrong.

It can never be loading and success at once. It also should not send a second request while the first one is still loading.

A state machine writes these rules down. It has a list of stages, called states. Things that happen, like SUBMIT, are called events. A transition table says which event moves which state to which next state. Any event not in the table for the current state is ignored.

1const transitions = {Run2  idle: { SUBMIT: "loading" },3  loading: { RESOLVE: "success", REJECT: "error" },4  success: { RESET: "idle" },5  error: { RETRY: "loading", RESET: "idle" },6};7 8function transition(state, event) {9  const nextValue = transitions[state.value]?.[event.type];10  if (!nextValue) return state;11  return {12    value: nextValue,13    context: { ...state.context, lastEvent: event.type },14  };15}16 17let state = { value: "idle", context: { lastEvent: null } };18for (const event of [{ type: "SUBMIT" }, { type: "SUBMIT" }, { type: "RESOLVE" }]) {19  const next = transition(state, event);20  console.log(state.value + " + " + event.type + " -> " + next.value);21  state = next;22}

The code that runs the machine is small. Line 9 looks up the event in the table, under the current state. The ?. there means "if this part is missing, give undefined instead of an error". If nothing is found, line 10 gives back the current state unchanged. That one line is what blocks the second SUBMIT.

Bigger apps sometimes need more: states inside states, or checks before a move. Libraries such as XState add these. But the core idea is this small table and lookup.

The first question is not "Which library should I use?". It is "Who owns this value?". Here are the usual answers:

• A value only one part of the page uses, like "is this tooltip showing?", stays in that part. This is local UI state.
• Data several parts of the app read, like the cart, goes in one shared place. This is shared app state. It does not mean a variable on window.
• Data fetched from a server belongs to the server. Your app keeps a copy, called a cache, with rules for when to fetch it again. This is server cache state.
• Choices someone might share or come back to, like the sort order or page number, go in the web address. This is URL state. The URL objects lesson covers how to read and change a URL.
• A form the user hasn't sent yet stays with the form.

const url = new URL("https://shop.example/products?sort=price&page=2");
const page = Number(url.searchParams.get("page"));
url.searchParams.set("page", String(page + 1));

console.log(page);
console.log(url.search);

Line 1 makes a URL object from a product page address. Line 2 reads the page number, 2. Line 3 sets it to the next page. The code prints 2 and ?sort=price&page=3.

In a real app, the page should also follow the address. When the user presses Back or Forward, the page should show the page number in the address.

The playground below is a small todo list run by a reducer. Each button sends an action. The reducer gives back a new state, and the playground keeps every state in a list. The slider lets you go back to an older state. This is called time travel. It works because old states were never changed.

1const initialState = {2  todos: [{ id: "draft", text: "Draft reducer", done: false }],3  filter: "all",4};5 6function todoReducer(state, action) {7  switch (action.type) {8    case "todo/add":9      return { ...state, todos: [...state.todos, action.payload] };10    case "todo/toggle":11      return {12        ...state,13        todos: state.todos.map((todo) =>14          todo.id === action.payload.id ? { ...todo, done: !todo.done } : todo,15        ),16      };17    case "filter/set":18      return { ...state, filter: action.payload };19    default:20      return state;21  }22}23 24const selectOpenCount = (state) => state.todos.filter((todo) => !todo.done).length;25let state = initialState;26state = todoReducer(state, {27  type: "todo/add",28  payload: { id: "ship", text: "Ship lesson", done: false },29});30state = todoReducer(state, { type: "todo/toggle", payload: { id: "draft" } });31console.log(selectOpenCount(state));

Try it: add a todo, mark one done, then drag the slider back. The older state still shows the todo as open, because the reducer made a new state instead of changing the old one.

1const preferences = { theme: "dark", sidebar: "open" };2localStorage.setItem("cf-preferences", JSON.stringify(preferences));3 4const restored = JSON.parse(localStorage.getItem("cf-preferences") ?? "{}");5const url = new URL("https://example.com/products?sort=price");6url.searchParams.set("page", "2");7 8console.log(restored.theme);9console.log(url.pathname + url.search);

Saving state so it survives a page reload is called persistence. It is a place to save a copy, not a second owner.

• Lines 1 and 2 save private settings, like the theme, with localStorage.setItem. JSON.stringify turns the object into text, because storage only holds text.
• Line 4 reads the text back and turns it into an object again with JSON.parse.
• Lines 5 and 6 put the page number in a URL, so someone can reload, bookmark, or share it.
• Lines 8 and 9 print dark and /products?sort=price&page=2.

The code runner on this page can't use storage. Try this code in the console of a real web page.

Common misconceptions

• "All state belongs in one shared store." A toggle or an unsent form that one part of the page uses should stay with that part.
• "Storing the count makes the page faster." Store the items and work out the count. Only store it if you measure and find the work is really slow.
• "A reducer can change the old state if the page still looks right." Then the "same object?" check fails. Subscribers get skipped, and undo shows the wrong data.
• "State machines are only for huge apps." They help in any small flow with steps that must not happen, like sending a form twice.
• "Saving to localStorage is state management." Storage only keeps a copy. After the page loads it back, the app still needs one owner and one way to change it.
• "Signals mean I don't have to choose an owner." Signals change how readers are told about changes. You still decide what is local, shared, server cache, or URL state.

The table below compares four tools. Read each row as: "this tool is good for this, helps in this way, and needs care here."

Some nearby ideas have their own lessons. The observer pattern lesson covers subscribers and signals. The app architecture lesson covers how to split an app into parts. Structural and behavioral patterns covers commands and undo.

Key takeaways

• State is data that changes while the app runs and changes what it shows or does. Not all of it belongs in one shared place.
• A single source of truth means one owner. Nobody keeps a second copy that could disagree.
• A reducer takes the current state and an action, and gives back the next state. It touches nothing else.
• Copying instead of changing in place makes the "same object?" check work, and keeps old states for undo.
• A state machine lists its stages and which events move between them. Any other event is ignored.
• Use localStorage to save private settings. Use the URL for choices someone might share.

Up next: Structuring an application. It shows how these state owners fit into the parts of a whole app.