Optimistic updates

A like button that makes you wait

When you like a photo, the app has to tell its server, and the server takes time to answer. Here is a like button that does the simple thing: it asks the server and waits. The server is pretend: the api.js tab holds a saveLike function that answers after one second. Click Like in the result.

1import { useState } from "react";2import { saveLike } from "./api.js";3 4export default function App() {5  const [liked, setLiked] = useState(false);6  const [saving, setSaving] = useState(false);7 8  async function handleClick() {9    setSaving(true);10    const saved = await saveLike(!liked);11    setLiked(saved);12    setSaving(false);13  }14 15  return (16    <>17      <button onClick={handleClick} disabled={saving}>18        {saving ? "Saving…" : liked ? "Liked" : "Like"}19      </button>20      <p>{liked ? 13 : 12} likes</p>21    </>22  );23}

Line 5 keeps whether you liked the post, and line 6 keeps whether a save is running. handleClick (lines 8 to 13) sets saving on line 9, then waits for the server on line 10 with await. Line 11 stores the server's answer, and line 12 ends the wait. While saving is true, line 18 shows Saving… and line 17 turns the button off.

For one whole second, the button says Saving… and the count stays at 12. On a phone with a weak signal that can be several seconds. Yet the server says yes to almost every like, so the wait shows the person nothing they didn't already know.

An optimistic update shows the result before the server confirms it, on the bet that it will. React 19 added a hook for it, useOptimistic (announced in the React 19 release post). Here is the same button with it, talking to the same slow server:

1import { startTransition, useOptimistic, useState } from "react";2import { saveLike } from "./api.js";3 4export default function App() {5  const [liked, setLiked] = useState(false);6  const [optimisticLiked, setOptimisticLiked] = useOptimistic(liked);7 8  function handleClick() {9    startTransition(async () => {10      setOptimisticLiked(!optimisticLiked);11      const saved = await saveLike(!optimisticLiked);12      startTransition(() => setLiked(saved));13    });14  }15 16  return (17    <>18      <button onClick={handleClick}>{optimisticLiked ? "Liked" : "Like"}</button>19      <p>{optimisticLiked ? 13 : 12} likes</p>20    </>21  );22}

Click Like: the button says Liked and the count says 13 likes at once. The server still takes a second, but nothing on the screen waits for it. Click again to unlike, and that's instant too. The next section explains every line.

useOptimistic, line by line

The hook takes one value and gives back two things, like useState:

const [optimisticValue, setOptimisticValue] = useOptimistic(value);

• value is the real value, usually a piece of state or a prop. While no action is running, the hook gives it back as it is.
• optimisticValue is the value to show. It equals value, except while an action is running and you have set it.
• setOptimisticValue sets that temporary value. You can only call it inside an action.

An action is a function React runs inside a transition: a group of updates React treats as one piece of work, and keeps track of until it finishes. You get one in two ways. You pass a function to startTransition, which you import from react, or you give a function to a form's action prop, which React starts in a transition for you, as Form actions shows. An async function counts: the action lasts until its last await is done. Transitions get a full lesson of their own later, Transitions.

Here is the optimistic like button again, so you can follow it line by line:

1import { startTransition, useOptimistic, useState } from "react";2import { saveLike } from "./api.js";3 4export default function App() {5  const [liked, setLiked] = useState(false);6  const [optimisticLiked, setOptimisticLiked] = useOptimistic(liked);7 8  function handleClick() {9    startTransition(async () => {10      setOptimisticLiked(!optimisticLiked);11      const saved = await saveLike(!optimisticLiked);12      startTransition(() => setLiked(saved));13    });14  }15 16  return (17    <>18      <button onClick={handleClick}>{optimisticLiked ? "Liked" : "Like"}</button>19      <p>{optimisticLiked ? 13 : 12} likes</p>20    </>21  );22}

1. Line 5 is the real state, liked. Only the server's answer changes it.
2. Line 6 passes liked to useOptimistic and gets optimisticLiked and its setter. Lines 18 and 19 show optimisticLiked, never liked.
3. Line 9 starts an action: startTransition gets an async function and runs it right away.
4. Line 10 sets the temporary value. React renders at once with optimisticLiked as true, so the button says Liked.
5. Line 11 waits one second for the server, which answers with the value it saved.
6. Line 12 puts the answer in the real state, inside another startTransition.

Why a second startTransition on line 12? Inside an async function, React can't yet tell that the code after an await still belongs to the action: JavaScript gives React no way to follow it across the wait. So React's docs ask you to wrap state updates after an await in startTransition, which keeps them part of the action. The chat later in this lesson shows what goes wrong without it.

When the async function finishes, the action ends, and React renders with the real state. liked is true by then, so optimisticLiked is true too, and nothing on the screen moves.

function updateOptimisticImpl<S, A>(
  hook: Hook,
  current: Hook | null,
  passthrough: S,
  reducer: ?(S, A) => S,
): [S, (A) => void] {
  // Optimistic updates are always rebased on top of the latest value passed in
  // as an argument. It's called a passthrough because if there are no pending
  // updates, it will be returned as-is.
  //
  // Reset the base state to the passthrough. Future updates will be applied
  // on top of this.
  hook.baseState = passthrough;

  // If a reducer is not provided, default to the same one used by useState.
  const resolvedReducer: (S, A) => S =
    typeof reducer === 'function' ? reducer : (basicStateReducer as any);

  return updateReducerImpl(hook, currentHook as any as Hook, resolvedReducer);
}

Line 13 resets the starting point to passthrough, the value you gave the hook. Line 19 then applies the optimistic updates that are still waiting on top of it, with your reducer, or with the same one useState uses (lines 16 and 17).

The setter must run inside an action. Here is the same button with handleClick written as a plain async function, a mistake on purpose. Click Like:

1import { startTransition, useOptimistic, useState } from "react";2import { saveLike } from "./api.js";3 4export default function App() {5  const [liked, setLiked] = useState(false);6  const [optimisticLiked, setOptimisticLiked] = useOptimistic(liked);7 8  async function handleClick() {9    setOptimisticLiked(!optimisticLiked);10    const saved = await saveLike(!optimisticLiked);11    startTransition(() => setLiked(saved));12  }13 14  return (15    <>16      <button onClick={handleClick}>{optimisticLiked ? "Liked" : "Like"}</button>17      <p>{optimisticLiked ? 13 : 12} likes</p>18    </>19  );20}

Nothing changes for a second, then the button says Liked. Line 9 runs in a plain click handler, not in an action, so React has no action to keep the value for: it renders true and goes straight back to liked, too fast to see. The like only shows when line 11 sets the real state. The console under the result shows React's warning:

An optimistic state update occurred outside a transition or action. To fix, move the update to an action, or wrap with startTransition.

It means the setter ran when no action was running. Press Edit & run and wrap lines 9 to 11 in startTransition(async () => { … }), as in the button above, and the like shows at once again.

Two values: the real one and the one on screen

While the action runs, the component has two values. liked is what the server has saved, as far as the app knows. optimisticLiked is what the screen shows. They differ only while the action runs:

React works out optimisticLiked on every render. If no action is running, it's liked. If an action is running and you've set it, it's your value. Nothing clears the temporary value: when the action ends, React simply stops using it. And because setLiked(saved) on line 12 is part of the same action, the render after the action already has the new liked, so the screen never flicks back to Like on the way.

Watch it happen. This post runs the like button with React's real useOptimistic, and the table lists both values after every render. Press Like, wait a second, then choose Fails and press it again.

With Saves the like, the table has three rows: false, false at first, false, true right after the click, and true, true one second later. With Fails, the last row is false, false: the action ended, liked never changed, and the screen went back to it.

How to read the table: each row is one moment in the like button's life, and the screen always shows the last column.

This also tells you when a save is running: optimisticLiked !== liked is true only during an action. You could use it to fade the button a little while the server works.

When the server says no

Servers fail. The network drops, a server is down, or a rule says no. This like button has an Offline box that makes the pretend server fail after its one-second wait. Tick Offline, then click Like.

1import { startTransition, useOptimistic, useState } from "react";2import { saveLike } from "./api.js";3 4export default function App() {5  const [liked, setLiked] = useState(false);6  const [optimisticLiked, setOptimisticLiked] = useOptimistic(liked);7  const [offline, setOffline] = useState(false);8  const [error, setError] = useState("");9 10  function handleClick() {11    setError("");12    startTransition(async () => {13      setOptimisticLiked(!optimisticLiked);14      try {15        const saved = await saveLike(!optimisticLiked, offline);16        startTransition(() => setLiked(saved));17      } catch (e) {18        setError(e.message);19      }20    });21  }22 23  return (24    <>25      <label>26        <input type="checkbox" checked={offline} onChange={(e) => setOffline(e.target.checked)} /> Offline27      </label>{" "}28      <button onClick={handleClick}>{optimisticLiked ? "Liked" : "Like"}</button>29      <p>{optimisticLiked ? 13 : 12} likes</p>30      {error && <p role="alert">{error}</p>}31    </>32  );33}

The button says Liked for one second, then Like again, the count goes back to 12, and a message explains why. Line 7 keeps the Offline box, and line 15 passes it to saveLike, which throws an error when it's true (line 4 of api.js). The try and catch on lines 14 to 19 catches it: line 16 never runs, so liked stays false, and line 18 keeps the message, which line 30 shows. Line 11 clears an old message when you try again.

Look for the line that puts Like back: there isn't one. The action ended, React rendered with the real state, and the real state never changed. This going back is called a rollback, and with useOptimistic you get it for free, because the optimistic value only lasts as long as the action.

Catch the error anyway. Without the try, the like still goes back when the action ends, but nothing tells the person why, and the error shows up in the browser's console as an uncaught error. A short message next to the button, as line 30 shows, tells them the like didn't stick.

Adding to a list with a reducer

In a chat, a message should appear the moment you press Send, marked as sending until the server has it. The optimistic value is now a list, and each send adds one message to it. For that, useOptimistic takes a second argument: a reducer, a pure function like the ones in Extracting state logic into a reducer. It gets the current list and whatever you pass to the setter, and returns the list to show. Send a few messages; the pretend server fails every third one.

1import { startTransition, useOptimistic, useState } from "react";2import { sendMessage } from "./api.js";3 4function addPending(messages, newMessage) {5  return [...messages, { ...newMessage, sending: true }];6}7 8export default function App() {9  const [messages, setMessages] = useState([{ id: "m1", text: "Is the shop open?" }]);10  const [optimisticMessages, addOptimisticMessage] = useOptimistic(messages, addPending);11  const [error, setError] = useState("");12 13  async function send(formData) {14    const newMessage = { id: crypto.randomUUID(), text: formData.get("text") };15    addOptimisticMessage(newMessage);16    try {17      const saved = await sendMessage(newMessage);18      startTransition(() => {19        setMessages((list) => [...list, saved]);20        setError("");21      });22    } catch (e) {23      setError(e.message);24    }25  }26 27  return (28    <form action={send}>29      <ul>30        {optimisticMessages.map((message) => (31          <li key={message.id}>32            {message.text} {message.sending && <small>(sending…)</small>}33          </li>34        ))}35      </ul>36      <input name="text" aria-label="Message" required /> <button>Send</button>37      {error && <p role="alert">{error}</p>}38    </form>39  );40}

1. Lines 4 to 6 are the reducer, addPending. It returns a new list with the new message at the end, marked sending: true, using spread twice.
2. Line 10 passes the real messages and addPending. The setter takes one message, so it's named addOptimisticMessage.
3. Line 13, send, is the form's action (line 28). React already runs it in a transition, so line 15 needs no startTransition.
4. Line 14 makes the message with an id from crypto.randomUUID(), which returns a random id string. The server sends the same message back, so the key on line 31 stays the same when it's saved.
5. Line 15 adds it to the screen at once. Line 17 waits for the server, and lines 18 to 21 add the saved message to the real list and clear an old error, in a transition.
6. Line 32 shows (sending…) only on a message that addPending marked.

The third message you send shows (sending…) for a second, then disappears, and the error appears: the same rollback as the like. The form empties after each send, as Form actions explains, so type the failed message again to retry.

Why a reducer instead of setting the whole list? React runs addPending on every render while the action runs, each time with the newest messages. If the real list changes during the wait, say a friend's reply arrives, your pending message is added to the new list, not to an old copy. And each call to the setter adds one message to a queue, so two sends that overlap both show. Try three ways of writing the chat, each sending two messages 0.3 seconds apart:

const [optimisticMessages, setOptimisticMessages] = useOptimistic(messages);

// in send(text), inside startTransition(async () => { … }):
setOptimisticMessages([...messages, { ...newMessage, sending: true }]);
const saved = await sendMessage(newMessage);
startTransition(() => setMessages((list) => [...list, saved]));

With A plain value, the second send replaces the whole optimistic list, built from messages, which doesn't have the first message yet. Tea at 4? disappears while it's still on its way. With A reducer, both stay. With A reducer, no second startTransition, the saved Tea at 4? shows at 1 second next to its pending copy: the message shows twice. That's why line 18 wraps setMessages in startTransition.

Notice one more thing in every timeline: Tea at 4? stays (sending…) until 1.3 seconds, though its answer came at 1 second. While actions overlap, React waits until all of them have finished, then shows their results in one render.

How to read the table: each row is one way to set the optimistic value, from the simplest to the most flexible.

A note on the updater row. React's useOptimistic reference (checked in October 2026) says an updater function only sees the value from when the action started. In React 19.3.1, the version these examples run, an updater builds on the newest value, the same as a reducer. React keeps each updater in the hook's queue, just as it keeps each message you pass to a reducer, and on every render it runs the whole queue again, starting from the newest real value: that's what updateOptimisticImpl, shown earlier, does. So if a friend's reply arrives while your message is sending, an updater keeps the reply on the screen too. A reducer is still the clearer choice for a list, because each setter call only has to say what changed.

When to be optimistic, and when to wait

An optimistic update is a guess. It pays off when the guess is almost always right and a wrong guess is cheap: the person sees the like disappear and a message, and taps again. It hurts when a wrong guess costs money or trust: a payment shown as done that then fails, or a train seat shown as booked that someone else got first.

How to read the table: ask each question about the action you're building.

When you decide to wait, show that something is happening instead: a pending state, like the isPending from useActionState in Form actions, and a button that can't be pressed twice.

Common mix-ups

• "useOptimistic saves to the server." No. It only changes what the screen shows. Your action still calls the server and sets the real state.
• "When the save fails, I have to put the old value back." No. When the action ends, React shows the real state again, and the real state never changed.
• "The optimistic value stays after the action." No. It only lasts while the action runs. If you forget to set the real state, the screen goes back to the old value even after a successful save.
• "I can call the setter in any click handler." No. Only inside an action. Anywhere else React warns, and the value shows for an instant at most.
• "A plain value works for lists too." Only while sends never overlap. Each call replaces the whole list, so a second send can hide the first. A reducer adds to the newest list.
• "Optimistic is always the better choice." No. For payments, bookings, deleting an account, or a result only the server knows, wait and show that you're waiting.

Practice exercises

import { startTransition, useOptimistic, useState } from "react";
import { saveLike } from "./api.js";

export default function App() {
  const [likes, setLikes] = useState(12);
  const [optimisticLikes, setOptimisticLikes] = useOptimistic(likes);

  function handleClick() {
    startTransition(async () => {
      setOptimisticLikes(likes + 1);
      await saveLike(true);
      startTransition(() => setLikes(likes + 1));
    });
  }

  return (
    <>
      <button onClick={handleClick}>Like</button>
      <p>{optimisticLikes} likes</p>
    </>
  );
}

1import { startTransition, useOptimistic, useState } from "react";2import { saveLike } from "./api.js";3 4export default function App() {5  const [likes, setLikes] = useState(12);6  const [optimisticLikes, setOptimisticLikes] = useOptimistic(likes);7 8  function handleClick() {9    startTransition(async () => {10      setOptimisticLikes(likes + 1);11      await saveLike(true);12      startTransition(() => setLikes(likes + 1));13    });14  }15 16  return (17    <>18      <button onClick={handleClick}>Like</button>19      <p>{optimisticLikes} likes</p>20    </>21  );22}

import { startTransition, useOptimistic, useState } from "react";
import { saveLike } from "./api.js";

export default function App() {
  const [likes, setLikes] = useState(12);
  const [optimisticLikes, setOptimisticLikes] = useOptimistic(likes);

  function handleClick() {
    startTransition(async () => {
      setOptimisticLikes(likes + 1);
      try {
        await saveLike(true, true);
        startTransition(() => setLikes(likes + 1));
      } catch {
        // The server failed. There's nothing to undo here.
      }
    });
  }

  return (
    <>
      <button onClick={handleClick}>Like</button>
      <p>{optimisticLikes} likes</p>
    </>
  );
}

1import { startTransition, useOptimistic, useState } from "react";2import { saveLike } from "./api.js";3 4export default function App() {5  const [likes, setLikes] = useState(12);6  const [optimisticLikes, setOptimisticLikes] = useOptimistic(likes);7 8  function handleClick() {9    startTransition(async () => {10      setOptimisticLikes(likes + 1);11      try {12        await saveLike(true, true);13        startTransition(() => setLikes(likes + 1));14      } catch {15        // The server failed. There's nothing to undo here.16      }17    });18  }19 20  return (21    <>22      <button onClick={handleClick}>Like</button>23      <p>{optimisticLikes} likes</p>24    </>25  );26}

1import { useState } from "react";2import { saveFollow } from "./api.js";3 4export default function App() {5  const [following, setFollowing] = useState(false);6  const [saving, setSaving] = useState(false);7 8  async function handleClick() {9    setSaving(true);10    const saved = await saveFollow(!following);11    setFollowing(saved);12    setSaving(false);13  }14 15  return (16    <>17      <h3>Asha's Tea Room</h3>18      <button onClick={handleClick} disabled={saving}>19        {saving ? "Saving…" : following ? "Following" : "Follow"}20      </button>21    </>22  );23}

1import { startTransition, useOptimistic, useState } from "react";2import { saveFollow } from "./api.js";3 4export default function App() {5  const [following, setFollowing] = useState(false);6  const [optimisticFollowing, setOptimisticFollowing] = useOptimistic(following);7 8  function handleClick() {9    startTransition(async () => {10      setOptimisticFollowing(!optimisticFollowing);11      const saved = await saveFollow(!optimisticFollowing);12      startTransition(() => setFollowing(saved));13    });14  }15 16  return (17    <>18      <h3>Asha's Tea Room</h3>19      <button onClick={handleClick}>{optimisticFollowing ? "Following" : "Follow"}</button>20    </>21  );22}

1import { startTransition, useOptimistic, useState } from "react";2import { saveQuantity } from "./api.js";3 4export default function App() {5  const [quantity, setQuantity] = useState(3);6  const [optimisticQuantity, setOptimisticQuantity] = useOptimistic(3);7 8  function addOne() {9    startTransition(async () => {10      setOptimisticQuantity(quantity + 1);11      const saved = await saveQuantity(quantity + 1);12      startTransition(() => setQuantity(saved));13    });14  }15 16  return (17    <p>18      Green tea × {optimisticQuantity} <button onClick={addOne}>Add one</button>19    </p>20  );21}

1import { startTransition, useOptimistic, useState } from "react";2import { saveQuantity } from "./api.js";3 4export default function App() {5  const [quantity, setQuantity] = useState(3);6  const [optimisticQuantity, setOptimisticQuantity] = useOptimistic(quantity);7 8  function addOne() {9    startTransition(async () => {10      setOptimisticQuantity(quantity + 1);11      const saved = await saveQuantity(quantity + 1);12      startTransition(() => setQuantity(saved));13    });14  }15 16  return (17    <p>18      Green tea × {optimisticQuantity} <button onClick={addOne}>Add one</button>19    </p>20  );21}

1import { startTransition, useOptimistic, useState } from "react";2import { saveTodo } from "./api.js";3 4function addPending(todos, newTodo) {5  // Return a new list with newTodo at the end, marked as saving.6  return todos;7}8 9export default function App() {10  const [todos, setTodos] = useState([{ id: "t1", text: "Buy tea" }]);11  const [optimisticTodos, addOptimisticTodo] = useOptimistic(todos, addPending);12 13  async function add(formData) {14    const newTodo = { id: crypto.randomUUID(), text: formData.get("text") };15    addOptimisticTodo(newTodo);16    const saved = await saveTodo(newTodo);17    startTransition(() => setTodos((list) => [...list, saved]));18  }19 20  return (21    <form action={add}>22      <ul>23        {optimisticTodos.map((todo) => (24          <li key={todo.id}>25            {todo.text} {todo.saving && <small>(saving…)</small>}26          </li>27        ))}28      </ul>29      <input name="text" aria-label="New to-do" required /> <button>Add</button>30    </form>31  );32}

1import { startTransition, useOptimistic, useState } from "react";2import { saveTodo } from "./api.js";3 4function addPending(todos, newTodo) {5  return [...todos, { ...newTodo, saving: true }];6}7 8export default function App() {9  const [todos, setTodos] = useState([{ id: "t1", text: "Buy tea" }]);10  const [optimisticTodos, addOptimisticTodo] = useOptimistic(todos, addPending);11 12  async function add(formData) {13    const newTodo = { id: crypto.randomUUID(), text: formData.get("text") };14    addOptimisticTodo(newTodo);15    const saved = await saveTodo(newTodo);16    startTransition(() => setTodos((list) => [...list, saved]));17  }18 19  return (20    <form action={add}>21      <ul>22        {optimisticTodos.map((todo) => (23          <li key={todo.id}>24            {todo.text} {todo.saving && <small>(saving…)</small>}25          </li>26        ))}27      </ul>28      <input name="text" aria-label="New to-do" required /> <button>Add</button>29    </form>30  );31}

1import { startTransition, useState } from "react";2import { removeAddress } from "./api.js";3 4export default function App() {5  const [addresses, setAddresses] = useState([6    { id: "home", label: "Home: 4 Tea Street" },7    { id: "work", label: "Work: 9 Cake Road" },8  ]);9 10  function remove(id) {11    startTransition(async () => {12      await removeAddress(id);13      startTransition(() => setAddresses((list) => list.filter((address) => address.id !== id)));14    });15  }16 17  return (18    <ul>19      {addresses.map((address) => (20        <li key={address.id}>21          {address.label} <button onClick={() => remove(address.id)}>Remove</button>22        </li>23      ))}24    </ul>25  );26}

1import { startTransition, useOptimistic, useState } from "react";2import { removeAddress } from "./api.js";3 4function withoutAddress(addresses, id) {5  return addresses.filter((address) => address.id !== id);6}7 8export default function App() {9  const [addresses, setAddresses] = useState([10    { id: "home", label: "Home: 4 Tea Street" },11    { id: "work", label: "Work: 9 Cake Road" },12  ]);13  const [optimisticAddresses, removeOptimistic] = useOptimistic(addresses, withoutAddress);14  const [error, setError] = useState("");15 16  function remove(id) {17    setError("");18    startTransition(async () => {19      removeOptimistic(id);20      try {21        await removeAddress(id);22        startTransition(() => setAddresses((list) => withoutAddress(list, id)));23      } catch (e) {24        setError(e.message);25      }26    });27  }28 29  return (30    <>31      <ul>32        {optimisticAddresses.map((address) => (33          <li key={address.id}>34            {address.label} <button onClick={() => remove(address.id)}>Remove</button>35          </li>36        ))}37      </ul>38      {error && <p role="alert">{error}</p>}39    </>40  );41}

Check your understanding

Key takeaways

• An optimistic update shows an action's result before the server confirms it.
• useOptimistic(value) gives back value, except while an action runs and you've set a temporary value.
• Call the setter inside an action: in startTransition, or in a form's action. Wrap state updates after an await in startTransition again.
• Set the real state when the server says yes. When the action ends, React shows the real state.
• A failed save rolls back by itself, because the real state never changed. Catch the error to say what happened.
• Use a reducer to add to a list, so overlapping actions build on the newest list.
• Wait instead when a wrong guess would cost money or trust, or when only the server knows the result.

Coming next: Referencing values with refs. It opens the next stage with values a component remembers without showing them.