Optimistic Updates

Make "optimistic" declarative

useOptimistic lets you show the expected outcome of an action before the server confirms. The hook gives you a temporary "pretend" state that reverts automatically if the action fails.

Shape

const [optimistic, addOptimistic] = useOptimistic(realState, reducer). Call addOptimistic with the change, then run the action. The optimistic state holds until the action resolves and the cache revalidates.

Patterns where it pays

Likes, hearts, favorites — immediate feedback feels essential.
Toggles where the round-trip is >100ms.
Adding items to a list (with a sending… indicator).

Define an identity and reconciliation rule for every optimistic item. A temporary list entry needs a temporary key, a visible sending state, and a deterministic replacement when the server returns the real record. Failures need a retry or undo path.

Immediate feedback is not the same as pretending every operation succeeded. Payments and permission changes should react immediately with progress, but confirmation must wait for the server. Optimism is appropriate when rollback is natural and the predicted result is unambiguous. Throttle the network and exercise success, failure, and rapid repeated input. Watch ordering, duplicate IDs, rollback, and cache revalidation. The UI should never briefly claim a durable result that the product cannot safely retract.

Code

Optimistic todo list·tsx

'use client';
import { useOptimistic } from 'react';
import { addTodo } from '@/app/actions';

type Todo = { id: string; text: string; sending?: boolean };

export function TodoList({ todos }: { todos: Todo[] }) {
  const [optimistic, addOptimistic] = useOptimistic(
    todos,
    (state, newText: string) => [
      ...state,
      { id: crypto.randomUUID(), text: newText, sending: true },
    ]
  );

  async function handleSubmit(formData: FormData) {
    const text = formData.get('text') as string;
    addOptimistic(text);          // instantly visible
    await addTodo(formData);      // background
  }

  return (
    <>
      <ul>
        {optimistic.map(t => (
          <li key={t.id} style={{ opacity: t.sending ? 0.5 : 1 }}>
            {t.text}{t.sending && <span className="ml-2 text-xs">saving&hellip;</span>}
          </li>
        ))}
      </ul>
      <form action={handleSubmit}>
        <input name="text" required />
        <button>Add</button>
      </form>
    </>
  );
}

Make "optimistic" declarative

Shape

Patterns where it pays

Code

External links

Exercise

Progress

Comments 0