Queueing a series of state updates

Add 3 teas that really adds 3

In State as a snapshot, a button called setCount(count + 1) three times and added only 1. Every call read the same count from the same render, so all three asked for the same number:

setCount(count + 1);
setCount(count + 1);
setCount(count + 1);

Here is the same button, with one change on lines 11 to 13: each call passes a function instead of a number. Click Add 3 teas in the result:

1import { useState } from "react";2 3export default function App() {4  const [count, setCount] = useState(0);5 6  return (7    <>8      <p>Items in cart: {count}</p>9      <button10        onClick={() => {11          setCount((c) => c + 1);12          setCount((c) => c + 1);13          setCount((c) => c + 1);14        }}15      >16        Add 3 teas17      </button>18    </>19  );20}

Now one click adds 3. (c) => c + 1 is an arrow function that takes a number c and returns one more. Passed to setCount, it's called an updater function. It doesn't say "make the count 1". It says "whatever the count is by then, add one".

Two things make this work. First, React doesn't render after each setCount. It puts each update in a queue, a list kept in order, and waits until your handler finishes. Second, when React works out the next state, it goes through the queue in order and hands each updater the result of the one before: 0 becomes 1, then 2, then 3.

React waits for your handler: batching

Most clicks change more than one piece of state. Render and commit showed that React turns several set calls into one render. Here is why that matters for a series of updates. Press Place order in this checkout:

1import { useState } from "react";2 3export default function App() {4  const [items, setItems] = useState(2);5  const [status, setStatus] = useState("In your cart");6  const [note, setNote] = useState("");7 8  function handlePlaceOrder() {9    setItems(0);10    setStatus("Order placed");11    setNote("We'll email your receipt.");12  }13 14  return (15    <>16      <p>Items: {items}</p>17      <p>Status: {status}</p>18      <p>{note}</p>19      <button onClick={handlePlaceOrder}>Place order</button>20    </>21  );22}

Lines 4 to 6 keep three pieces of state: the number of items, a status, and a note. handlePlaceOrder sets all three on lines 9, 10, and 11. Each call adds an update to React's queue. Nothing renders until the handler ends; then React makes one render with all three changes, and the page changes all at once.

This grouping is batching. It has two benefits. React does less work: one render instead of three. And the page never shows a half-finished state, like Items: 0 next to Status: In your cart.

Since React 18, batching happens wherever the updates come from: event handlers, timers, promises, and the code after await (React 18 release notes). In React 17 and older, only updates inside React event handlers were batched; you may still see older code that works around that. If you ever need React to update the page before your handler goes on, flushSync from react-dom forces a render straight away. It's rarely needed, and it gives up batching.

Try every case in this playground. The checkout runs on this page with real React. Pick where its three updates run, press Place order, and count the renders. Then press Back to the cart and try the next one.

function handlePlaceOrder() {
  setItems(0);
  setStatus("Order placed");
  setNote("We'll email your receipt.");
}

In the click, in a timer, and after an await, React makes 1 render with all three changes. The timer and the await wait a second first: nothing renders while they wait. With flushSync, React makes 3 renders, and the first two show a half-finished checkout: items gone, status still In your cart.

Each row is a place your updates can run, and what React does with three of them:

The last row matters too. React never batches two separate clicks together: each click is its own event, and React renders for the first before it handles the second. So if the first click disables a button, the second click can't press it.

Updater functions work from the queued value

Here is what React does with setCount((c) => c + 1), step by step:

1. While your handler runs, each call adds the function itself to the queue. (When nothing else is waiting, React may call the first one right away, as a shortcut to see whether anything changes. The result is the same. What setState really does shows that shortcut in React's code.)
2. When React works out the next state, it starts from the state the last render had, here 0, and calls the first updater with it.
3. It hands each updater's result to the next one, as its argument.
4. The last result is the new state, and that's what useState returns in the next render.

For Add 3 teas, starting from 0, each row is one queued update, the value it gets, and what it returns:

React keeps 3, and the next render shows Items in cart: 3. Build your own queues in this playground. The points counter starts at 10. Add calls to handleClick with the buttons, press Run handleClick on the page, then press Step to see how React got there, one row at a time.

function handleClick() {
  setPoints(points + 5);
  setPoints((p) => p * 2);
}

The playground starts with setPoints(points + 5) and setPoints((p) => p * 2). The page shows 30. Step through: the first row is "replace with 15" and the second, p => p * 2, gets 15 and returns 30. Run it again, and the queue starts from 30. The next section explains why the first row is a replacement.

Mixing replacing and updating

You can mix both kinds in one handler. Here a shop gives loyalty points: a welcome bonus of 5, then double points. Points start at 10. Predict the number, then press Bonus:

1import { useState } from "react";2 3export default function App() {4  const [points, setPoints] = useState(10);5 6  function handleBonus() {7    setPoints(points + 5);8    setPoints((p) => p * 2);9  }10 11  return (12    <>13      <p>Points: {points}</p>14      <button onClick={handleBonus}>Bonus</button>15    </>16  );17}

It shows 30. Line 7 passes points + 5, which is worked out right away from this render's points: 10 + 5. So React queues "replace with 15". Line 8 passes a function, so React queues p => p * 2 itself. Then React works through the queue. Each row is one queued update, the value it gets, and what it returns:

Now add one more line at the end, a fixed number:

1import { useState } from "react";2 3export default function App() {4  const [points, setPoints] = useState(10);5 6  function handleBonus() {7    setPoints(points + 5);8    setPoints((p) => p * 2);9    setPoints(50);10  }11 12  return (13    <>14      <p>Points: {points}</p>15      <button onClick={handleBonus}>Bonus</button>16    </>17  );18}

It shows 50. Line 9 queues "replace with 50", which ignores the 30 it gets. Press Bonus again: still 50, because the last update in the queue always wins. The same three columns, with the new row at the end:

So what you pass to a set function decides what goes in the queue:

• A function, like (p) => p * 2, goes in the queue as it is. React calls it with the queued value.
• Any other value, like 50 or points + 5, adds "replace with this value", ignoring what was queued before. setPoints(50) acts like setPoints(() => 50).

Keep updaters pure, and name them simply

React calls your updater functions itself, usually while it works out the next state, and sometimes right inside your set call. It may call one more than once: in development, StrictMode calls each updater twice and keeps one result, to help you spot an updater that does more than return a value. So an updater must be a pure function: it only works out the next value from the one it gets. This one breaks that rule:

setCount((c) => {
  sendToServer(c + 1);
  return c + 1;
});

Line 2 sends a request from inside the updater. In development, StrictMode would send it twice. Put side effects in the event handler, and keep the updater to its one job:

function handleAdd() {
  sendToServer(count + 1);
  setCount((c) => c + 1);
}

Line 2 sends the request once per click, from the handler. Line 3 only adds one. (Both blocks are pieces of a component, so they have no result of their own.)

For the updater's argument, pick a name that says what it is. Three habits are common: the first letter of the state variable, the full name, or the name with prev in front:

setCount((c) => c + 1);
setIsMuted((m) => !m);
setPoints((prevPoints) => prevPoints * 2);
setItems((items) => [...items, "Tea"]);

Each row is a piece of state, an updater for it, and how to read it aloud:

When should you write an updater? Whenever the next state is worked out from the current one and more than one update might be queued: several calls in one handler, or code that runs later, like a timer or the code after await. When you set a fixed value, like setNote(""), pass the value. Many teams write an updater every time the new state comes from the old one, so they never have to stop and check.

Uploads that finish later

A photo app shows how many uploads are running and how many are done. Each upload takes two seconds. Press Upload a photo three times quickly, then wait:

1import { useState } from "react";2 3function upload() {4  return new Promise((resolve) => setTimeout(resolve, 2000));5}6 7export default function App() {8  const [uploading, setUploading] = useState(0);9  const [done, setDone] = useState(0);10 11  async function handleUpload() {12    setUploading(uploading + 1);13    await upload();14    setUploading(uploading - 1);15    setDone(done + 1);16  }17 18  return (19    <>20      <p>Uploading: {uploading}</p>21      <p>Done: {done}</p>22      <button onClick={handleUpload}>Upload a photo</button>23    </>24  );25}

While they run, it says Uploading: 3: each click comes after the last one rendered, so line 12 counts up from a fresh snapshot. But when they finish, it ends at Uploading: 1 and Done: 1, not 0 and 3 (on the way, it may even show -1). After the await on line 13, lines 14 and 15 still read the snapshot of their own click. The first click saw 0 uploading and 0 done, so it asks for -1 and 1. The second saw 1 and 0, so it asks for 0 and 1. The third saw 2 and 0: 1 and 1. The last replacement wins: 1 and 1.

Each finish should change whatever is queued by then, so write updaters:

1import { useState } from "react";2 3function upload() {4  return new Promise((resolve) => setTimeout(resolve, 2000));5}6 7export default function App() {8  const [uploading, setUploading] = useState(0);9  const [done, setDone] = useState(0);10 11  async function handleUpload() {12    setUploading((u) => u + 1);13    await upload();14    setUploading((u) => u - 1);15    setDone((d) => d + 1);16  }17 18  return (19    <>20      <p>Uploading: {uploading}</p>21      <p>Done: {done}</p>22      <button onClick={handleUpload}>Upload a photo</button>23    </>24  );25}

Lines 12, 14, and 15 now pass functions. Each finish takes one away from the latest count and adds one to done, so three uploads end at Uploading: 0 and Done: 3.

Common mix-ups

• "Every set function call renders the page right away." No. It queues an update. React renders once, after your handler finishes.
• "Batching only happens in click handlers." Not since React 18. Updates in timers, promises, and after await are batched too.
• "An updater gets this render's value." No. It gets the queued value: what the update before it returned, or the last render's state if it's first in the queue.
• "setCount(count + 1) and setCount((c) => c + 1) are the same." Only when it's the only update. With several in the queue, the first replaces with a fixed number, and the second builds on the queued value.
• "React batches two quick clicks together." No. Each click is its own event, and React renders after each one.
• "An updater is a good place to send a request." No. React may call it more than once; StrictMode calls it twice in development. Keep updaters pure.

Practice exercises

Write the queue down first: for each call, a replacement or a function. Then work through it, starting from the state the render had. Press Edit & run to check.

import { useState } from "react";

export default function App() {
  const [count, setCount] = useState(0);

  function handleClick() {
    setCount((c) => c + 2);
    setCount((c) => c + 2);
  }

  return <button onClick={handleClick}>Count: {count}</button>;
}

1import { useState } from "react";2 3export default function App() {4  const [count, setCount] = useState(0);5 6  function handleClick() {7    setCount((c) => c + 2);8    setCount((c) => c + 2);9  }10 11  return <button onClick={handleClick}>Count: {count}</button>;12}

import { useState } from "react";

export default function App() {
  const [points, setPoints] = useState(1);

  function handleClick() {
    setPoints((p) => p + 1);
    setPoints(10);
    setPoints((p) => p * 3);
  }

  return <button onClick={handleClick}>Points: {points}</button>;
}

1import { useState } from "react";2 3export default function App() {4  const [points, setPoints] = useState(1);5 6  function handleClick() {7    setPoints((p) => p + 1);8    setPoints(10);9    setPoints((p) => p * 3);10  }11 12  return <button onClick={handleClick}>Points: {points}</button>;13}

1import { useState } from "react";2 3export default function App() {4  const [eggs, setEggs] = useState(0);5 6  function handleBuyDozen() {7    for (let i = 0; i < 12; i++) {8      setEggs(eggs + 1);9    }10  }11 12  return (13    <>14      <p>Eggs in cart: {eggs}</p>15      <button onClick={handleBuyDozen}>Buy a dozen</button>16    </>17  );18}

1import { useState } from "react";2 3export default function App() {4  const [eggs, setEggs] = useState(0);5 6  function handleBuyDozen() {7    for (let i = 0; i < 12; i++) {8      setEggs((e) => e + 1);9    }10  }11 12  return (13    <>14      <p>Eggs in cart: {eggs}</p>15      <button onClick={handleBuyDozen}>Buy a dozen</button>16    </>17  );18}

1import { useState } from "react";2 3export default function App() {4  const [seconds, setSeconds] = useState(0);5 6  function handleStart() {7    setInterval(() => {8      setSeconds(seconds + 1);9    }, 1000);10  }11 12  return (13    <>14      <p>Time on this page: {seconds} s</p>15      <button onClick={handleStart}>Start</button>16    </>17  );18}

1import { useState } from "react";2 3export default function App() {4  const [seconds, setSeconds] = useState(0);5 6  function handleStart() {7    setInterval(() => {8      setSeconds((s) => s + 1);9    }, 1000);10  }11 12  return (13    <>14      <p>Time on this page: {seconds} s</p>15      <button onClick={handleStart}>Start</button>16    </>17  );18}

function getFinalState(baseState, queue) {
  let finalState = baseState;
  // For each update in the queue: a function gets finalState and
  // returns the next one; any other value replaces finalState.
  return finalState;
}

console.log(getFinalState(10, [15, (p) => p * 2, 50]));
console.log(getFinalState(2, [(p) => p + 1, (p) => p * 3]));

function getFinalState(baseState, queue) {
  let finalState = baseState;
  for (const update of queue) {
    if (typeof update === "function") {
      finalState = update(finalState);
    } else {
      finalState = update;
    }
  }
  return finalState;
}

console.log(getFinalState(10, [15, (p) => p * 2, 50]));
console.log(getFinalState(2, [(p) => p + 1, (p) => p * 3]));

1import { useState } from "react";2 3export default function App() {4  const [items, setItems] = useState(["Tea", "Cake", "Lemonade"]);5 6  function handleRemoveTwo() {7    setItems(items.slice(0, -1));8    setItems(items.slice(0, -1));9  }10 11  return (12    <>13      <p>In your cart: {items.join(", ") || "nothing"}</p>14      <button onClick={handleRemoveTwo}>Remove the last two</button>15    </>16  );17}

1import { useState } from "react";2 3export default function App() {4  const [items, setItems] = useState(["Tea", "Cake", "Lemonade"]);5 6  function handleRemoveTwo() {7    setItems((list) => list.slice(0, -1));8    setItems((list) => list.slice(0, -1));9  }10 11  return (12    <>13      <p>In your cart: {items.join(", ") || "nothing"}</p>14      <button onClick={handleRemoveTwo}>Remove the last two</button>15    </>16  );17}

Check your understanding

For each code question, write down the queue first, then work through it from the starting value.

Key takeaways

• A set function call doesn't render. It adds an update to a queue, and React renders once, after your handler finishes: batching.
• Since React 18, updates are batched everywhere: event handlers, timers, promises, and after await. Separate clicks are never batched together, and flushSync forces a render straight away.
• An updater function, like (c) => c + 1, gets the queued value and returns the next one.
• Any other value means "replace with this value". The last update in the queue wins.
• Updaters must be pure, and their argument is usually named after the state: c, count, or prevCount.

Coming next: Updating objects in state. It shows how to change one field of an object in state, like a profile's name, by making a new object instead of changing the old one.