Pending and optimistic UI

A cart that counts before the server answers

A Server Action is a request to the server, and a request takes time. On a fast connection, the visitor hardly notices. On a weak phone signal, they click Add a box and nothing changes. Did it work? Should they click again? Two things help them:

• A pending state: the page shows that the action is running, like a button that says Adding….
• An optimistic update: the page shows the result the action will most likely have, before the server answers. Then it shows the server's real answer, and goes back if the server says no.

Here is the tea shop's Jasmine tea page, with both. It's a real Next.js 16.4.3 project, built with next build and run with next start. Real Chrome then made the network slow (every request waited before it went out, like on a weak signal) and clicked Add a box. The Steps tab opens on the page right after that click.

1"use client";2 3import { useOptimistic, useState, useTransition } from "react";4import { addBox } from "./actions";5 6export default function AddBox({ boxes }: { boxes: number }) {7  const [shownBoxes, setShownBoxes] = useOptimistic(boxes);8  const [isPending, startTransition] = useTransition();9  const [message, setMessage] = useState("");10 11  function add() {12    startTransition(async () => {13      setShownBoxes(shownBoxes + 1);14      const result = await addBox();15      startTransition(() => setMessage(result.message));16    });17  }18 19  return (20    <div>21      <p>In your cart: {shownBoxes} {shownBoxes === 1 ? "box" : "boxes"}</p>22      <button onClick={add} disabled={isPending}>23        {isPending ? "Adding…" : "Add a box"}24      </button>25      <p aria-live="polite">{message}</p>26    </div>27  );28}

After step 3, the request was still on its way, and the page already said In your cart: 1 box. The button said Adding…, and the total still said Total: $0. Pick step 4: the server has answered, the button says Add a box again, and the total is $5.

The count and the total come from different places. The total, on line 10 of app/teas/jasmine/page.tsx, is rendered on the server, from the cart cookie. The count, on line 21 of add-box.tsx, is shownBoxes: a value the browser shows while the action runs. So the count changed at the click, and the total only when the server answered.

Three ways to know an action is running

A pending state needs one true or false: is the action still running? React has three hooks that give it, each for a different place in the code. Here is the cart button without any optimistic count, written three ways. Each was recorded on the same slow network:

1"use client";2 3import { useTransition } from "react";4import { addBox } from "./actions";5 6export default function AddBox({ boxes }: { boxes: number }) {7  const [isPending, startTransition] = useTransition();8 9  function add() {10    startTransition(async () => {11      await addBox();12    });13  }14 15  return (16    <div>17      <p>In your cart: {boxes} {boxes === 1 ? "box" : "boxes"}</p>18      <button onClick={add} disabled={isPending}>19        {isPending ? "Adding…" : "Add a box"}20      </button>21    </div>22  );23}

All three showed Adding… after the click, and In your cart: 0 boxes, because nothing in them changes the count before the server answers. Step 4, in each, is the page after the answer: 1 box and $5. Each row says where the hook goes, and what it gives:

How to pick one:

• A button that isn't in a form, with its own onClick: useTransition is the simplest, as the optimistic cart above shows. useActionState works there too, if you call its action inside startTransition; only useFormStatus needs a form around it.
• A form whose answer you show: useActionState. You already have it for the answer, so its isPending costs nothing more.
• A button component you reuse in many forms: useFormStatus. It needs no props, because it finds the form it's in (Forms in Next.js showed why it must be inside the form).

Form actions and Transitions, in the React course, teach these hooks on their own.

useOptimistic: a value to show while the action runs

A pending state says "wait". An optimistic update says "done", a little early. Here is the cart's button with both:

1"use client";2 3import { useOptimistic, useState, useTransition } from "react";4import { addBox } from "./actions";5 6export default function AddBox({ boxes }: { boxes: number }) {7  const [shownBoxes, setShownBoxes] = useOptimistic(boxes);8  const [isPending, startTransition] = useTransition();9  const [message, setMessage] = useState("");10 11  function add() {12    startTransition(async () => {13      setShownBoxes(shownBoxes + 1);14      const result = await addBox();15      startTransition(() => setMessage(result.message));16    });17  }18 19  return (20    <div>21      <p>In your cart: {shownBoxes} {shownBoxes === 1 ? "box" : "boxes"}</p>22      <button onClick={add} disabled={isPending}>23        {isPending ? "Adding…" : "Add a box"}24      </button>25      <p aria-live="polite">{message}</p>26    </div>27  );28}29 

Line 1 makes it a Client Component, because useOptimistic, useTransition and useState keep state in the browser, which only Client Components can. On line 6, AddBox gets boxes, the number of boxes in the cart, from the server: line 9 of page.tsx reads it from the cookie and passes it in.

Line 7 is the new hook. useOptimistic(boxes) gives back two things:

• shownBoxes: the value to show. When no action is running, it's boxes, exactly.
• setShownBoxes: sets another value, for as long as the current action runs.

Line 13 calls setShownBoxes(shownBoxes + 1) inside an action, before the request leaves. React draws the new count at once. Line 21 shows shownBoxes, never boxes. When the action ends, shownBoxes is boxes again: the server's number, whatever it is by then. There's nothing to undo by hand. (Optimistic updates, in the React course, teaches the hook with plain functions.)

Compare the page with and without the optimistic count, right after the click:

1"use client";2 3import { useTransition } from "react";4import { addBox } from "./actions";5 6export default function AddBox({ boxes }: { boxes: number }) {7  const [isPending, startTransition] = useTransition();8 9  function add() {10    startTransition(async () => {11      await addBox();12    });13  }14 15  return (16    <div>17      <p>In your cart: {boxes} {boxes === 1 ? "box" : "boxes"}</p>18      <button onClick={add} disabled={isPending}>19        {isPending ? "Adding…" : "Add a box"}20      </button>21    </div>22  );23}

Each row is one moment in the cart's recording, and the two values then:

Where did the server's new boxes come from? Line 13 of actions.ts sets the cart cookie. When an action changes a cookie, Next.js renders the page again on the server, and sends it back in the same response as the action's answer. So boxes arrived as 1 at the same moment the action ended. Updating the UI after a mutation covers every way to send fresh data after an action.

Actions need a transition

An optimistic value lasts "while the action runs". React has to know when that is. An action, in React, is a function that runs inside a transition: an update React treats as one piece of work that may take a while, with a start and an end. The optimistic value lives from the start to the end.

Line 8 of add-box.tsx calls useTransition. It gives isPending and startTransition. On line 12, startTransition runs an async function: from that moment until the function and the updates it started are done, isPending is true, and line 22 turns the button off. Inside it:

1. Line 13 sets the optimistic count, inside the transition.
2. Line 14 calls the Server Action and awaits its answer.
3. Line 15 stores the action's message. It's wrapped in startTransition again, because React doesn't count a state update after an await as part of the transition. React's docs call this a current limit, and the Next.js docs wrap such updates the same way, so they show together with the rest of the transition's result.

Why not call setShownBoxes in a plain click handler? React's docs say the setter must be called inside an action. Outside one, React prints a warning in development, and the optimistic value only shows for a moment, since there's no transition for it to last through.

Some places are transitions already, so the setter works there without startTransition:

• A function given to a form's action, or to a button's formAction, like the wishlist's form.
• The action given to useActionState.

When the server says no

Optimism can be wrong. The shop has only 2 boxes of Jasmine tea, and the action checks it on the server, where the stock is:

1"use server";2 3import { cookies } from "next/headers";4 5const boxesLeft = 2;6 7export async function addBox() {8  const cookieStore = await cookies();9  const boxes = Number(cookieStore.get("boxes")?.value ?? 0);10  if (boxes >= boxesLeft) {11    return { message: `Sorry, only ${boxesLeft} boxes are left.` };12  }13  cookieStore.set("boxes", String(boxes + 1));14  return { message: "" };15}16 

Line 9 reads the boxes already in the cart cookie, or 0. Line 10 compares them with boxesLeft, from line 5. With 2 boxes in the cart, line 11 returns a message, and the cookie doesn't change. Otherwise, line 13 stores one more box, and line 14 returns an empty message.

The recording went on: step 6 added a second box, on a normal network, and step 8 clicked a third time, slowly. Open the cart's Steps tab above and pick step 8: In your cart: 3 boxes and Adding…, because the browser couldn't know. Step 9 is the server's no: In your cart: 2 boxes, and Sorry, only 2 boxes are left. under the button. Nobody wrote code to undo the 3. The transition ended, boxes was still 2, so shownBoxes was 2. This is called rolling back.

Step through both trips, the yes and the no. Before you start, guess: in which step does the no reach the page?

Nothing on the screen changes while the request travels and the server works: the visitor sees the optimistic count the whole time. In both trips, the page changes again only in the last step, when the transition ends.

Returning the problem, or throwing it

The action could also throw when the shop has run out. Then there's no message to show: an error thrown inside the transition goes to the nearest error.tsx, as the Next.js docs say. Compare the two versions, after the third click:

1"use server";2 3import { cookies } from "next/headers";4 5const boxesLeft = 2;6 7export async function addBox() {8  const cookieStore = await cookies();9  const boxes = Number(cookieStore.get("boxes")?.value ?? 0);10  if (boxes >= boxesLeft) {11    return { message: `Sorry, only ${boxesLeft} boxes are left.` };12  }13  cookieStore.set("boxes", String(boxes + 1));14  return { message: "" };15}

When it returns the message, the page stays, with the count rolled back and the reason under the button. When it throws, the request answered 500, and app/teas/jasmine/error.tsx took the page's place. Chrome's console shows React's error #441: in production, the error's own message stays on the server. A sold-out tea is an expected problem, so return it, as Error handling recommends; keep throwing for what shouldn't happen at all.

A wishlist that shows a new tea at once

An optimistic list is common too: a new comment, a new note, a tea added to a wishlist. The new item shows at once, marked as saving, until the server has it. Here the visitor types Jasmine tea and clicks Add to wishlist, on a slow network:

1"use client";2 3import { useOptimistic } from "react";4import { addToWishlist } from "./actions";5 6type Tea = { name: string; saving: boolean };7 8export default function Wishlist({ names }: { names: string[] }) {9  const saved = names.map((name) => ({ name, saving: false }));10  const [teas, addTea] = useOptimistic(saved, (current: Tea[], name: string) => [...current, { name, saving: true }]);11 12  async function addAction(formData: FormData) {13    const name = String(formData.get("tea") ?? "").trim();14    addTea(name);15    await addToWishlist(name);16  }17 18  return (19    <>20      <ul>21        {teas.map((tea) => (22          <li key={tea.name}>{tea.saving ? `${tea.name} (saving…)` : tea.name}</li>23        ))}24      </ul>25      <form action={addAction}>26        <label htmlFor="tea">Tea</label> <input id="tea" name="tea" /> <button>Add to wishlist</button>27      </form>28    </>29  );30}

After step 4, the list showed Jasmine tea (saving…), while the server still said Saved teas: 0. After step 5, the server's answer: Jasmine tea without the mark, and Saved teas: 1. The box was emptied too, because React resets a form after its action finishes.

app/wishlist/wishlist.tsx uses useOptimistic with a second argument, a reducer: a function that makes the optimistic value from the current one and what you pass to the setter. On line 10, it takes the list and a tea's name, and returns the list with a new tea marked saving: true. Line 14 calls addTea(name). The reducer helps when the server's list changes while an action runs: React runs it again on the new list, so the new tea stays on top of it. Line 22 shows the mark.

addAction calls addTea without startTransition: it's given to the form's action on line 25, and React runs form actions in a transition. addAction itself runs in the browser, and calls the Server Action addToWishlist on line 15.

Not every action should be optimistic. If showing the result early could make the visitor do the wrong thing, show a pending state and wait. Sort these actions:

Common mix-ups

• "useOptimistic saves the value." No. It only shows a value while an action runs. The Server Action saves, and the page shows the server's value when the action ends.
• "You have to undo the optimistic value when the action fails." No. When the transition ends, the hook returns the value passed in again. If the server changed nothing, that's the old value.
• "The setter works in any click handler." No. Call it inside an action: in startTransition, a form action, or the action of useActionState.
• "A pending state and an optimistic update are the same." No. One says the action is running; the other shows its result early. The cart shows both.
• "A failed action should throw." No. A problem the shop expects, like a sold-out tea, is a value to return and show. A thrown error replaces the page with error.tsx.
• "Every action should be optimistic." No. Payments, bookings others may take, and changes that can't be undone should wait for the server.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page.

"use client";

import { useOptimistic, useState, useTransition } from "react";
import { addBox } from "./actions";

export default function AddBox({ boxes }: { boxes: number }) {
  const [shownBoxes, setShownBoxes] = useOptimistic(boxes);
  const [isPending, startTransition] = useTransition();
  const [message, setMessage] = useState("");

  function add() {
    startTransition(async () => {
      setShownBoxes(shownBoxes + 1);
      const result = await addBox();
      startTransition(() => setMessage(result.message));
    });
  }

  return (
    <div>
      <p>In your cart: {shownBoxes} {shownBoxes === 1 ? "box" : "boxes"}</p>
      <button onClick={add} disabled={isPending}>
        {isPending ? "Adding…" : "Add a box"}
      </button>
      <p aria-live="polite">{message}</p>
    </div>
  );
}

"use server";

import { cookies } from "next/headers";

const boxesLeft = 2;

export async function addBox() {
  const cookieStore = await cookies();
  const boxes = Number(cookieStore.get("boxes")?.value ?? 0);
  if (boxes >= boxesLeft) {
    return { message: `Sorry, only ${boxesLeft} boxes are left.` };
  }
  cookieStore.set("boxes", String(boxes + 1));
  return { message: "" };
}

"use client";

import { useTransition } from "react";
import { addBox } from "./actions";

export default function AddBox({ boxes }: { boxes: number }) {
  const [isPending, startTransition] = useTransition();

  function add() {
    startTransition(async () => {
      await addBox();
    });
  }

  return (
    <div>
      <p>In your cart: {boxes} {boxes === 1 ? "box" : "boxes"}</p>
      <button onClick={add} disabled={isPending}>
        {isPending ? "Adding…" : "Add a box"}
      </button>
    </div>
  );
}

"use client";

import { useOptimistic, useState, useTransition } from "react";
import { addBox } from "./actions";

export default function AddBox({ boxes }: { boxes: number }) {
  const [shownBoxes, setShownBoxes] = useOptimistic(boxes);
  const [isPending, startTransition] = useTransition();
  const [message, setMessage] = useState("");

  function add() {
    startTransition(async () => {
      setShownBoxes(shownBoxes + 1);
      const result = await addBox();
      startTransition(() => setMessage(result.message));
    });
  }

  return (
    <div>
      <p>In your cart: {shownBoxes} {shownBoxes === 1 ? "box" : "boxes"}</p>
      <button onClick={add} disabled={isPending}>
        {isPending ? "Adding…" : "Add a box"}
      </button>
      <p aria-live="polite">{message}</p>
    </div>
  );
}

"use client";

import { useOptimistic } from "react";
import { addToWishlist } from "./actions";

type Tea = { name: string; saving: boolean };

export default function Wishlist({ names }: { names: string[] }) {
  const saved = names.map((name) => ({ name, saving: false }));
  // Make teas, which shows a new tea at once, marked as saving.

  async function addAction(formData: FormData) {
    const name = String(formData.get("tea") ?? "").trim();
    addTea(name);
    await addToWishlist(name);
  }

  return (
    <>
      <ul>
        {teas.map((tea) => (
          <li key={tea.name}>{tea.saving ? `${tea.name} (saving…)` : tea.name}</li>
        ))}
      </ul>
      <form action={addAction}>
        <label htmlFor="tea">Tea</label> <input id="tea" name="tea" /> <button>Add to wishlist</button>
      </form>
    </>
  );
}

"use client";

import { useOptimistic } from "react";
import { addToWishlist } from "./actions";

type Tea = { name: string; saving: boolean };

export default function Wishlist({ names }: { names: string[] }) {
  const saved = names.map((name) => ({ name, saving: false }));
  const [teas, addTea] = useOptimistic(saved, (current: Tea[], name: string) => [...current, { name, saving: true }]);

  async function addAction(formData: FormData) {
    const name = String(formData.get("tea") ?? "").trim();
    addTea(name);
    await addToWishlist(name);
  }

  return (
    <>
      <ul>
        {teas.map((tea) => (
          <li key={tea.name}>{tea.saving ? `${tea.name} (saving…)` : tea.name}</li>
        ))}
      </ul>
      <form action={addAction}>
        <label htmlFor="tea">Tea</label> <input id="tea" name="tea" /> <button>Add to wishlist</button>
      </form>
    </>
  );
}

"use server";

import { cookies } from "next/headers";

const boxesLeft = 2;

export async function addBox() {
  const cookieStore = await cookies();
  const boxes = Number(cookieStore.get("boxes")?.value ?? 0);
  if (boxes >= boxesLeft) {
    throw new Error(`Sorry, only ${boxesLeft} boxes are left.`);
  }
  cookieStore.set("boxes", String(boxes + 1));
  return { message: "" };
}

Check your understanding

For each question, ask which value comes from the server, and which one the browser shows while it waits.

Key takeaways

• A pending state says an action is running: isPending from useTransition or useActionState, or pending from useFormStatus in a component inside the form.
• useOptimistic(value) returns value, except while an action runs: then it returns what you set inside that action.
• Call the optimistic setter inside an action: startTransition, a form action, or useActionState's action. Wrap state updates after an await in startTransition too.
• When the action ends, the page shows the server's value: the new one if it worked, the old one if not. Rolling back needs no code.
• Return expected problems and show them; a thrown error replaces the page with the nearest error.tsx.
• Be optimistic about small changes that almost always work; wait for payments, bookings and anything that can't be undone.

Coming next: Updating the UI after a mutation. It covers updateTag, revalidatePath, refresh() and redirect: the ways an action brings fresh data to the page.