Optimistic UI: useOptimistic, useActionState, and the Pending State Pattern

How useOptimistic Works Internally

useOptimistic takes two arguments:

1. The real state (synced with the server)
2. An update function: (currentState, optimisticValue) => newState

When you call addOptimistic(value):

• The component immediately re-renders with updateFn(currentState, value)
• While the associated async operation is pending, React shows the optimistic state
• When the async operation completes (or if the component re-renders with new real state), the optimistic state is discarded and the real state takes over

The rollback is automatic — if your Server Action throws, React reverts the optimistic update because the pending state resolves.

---

Combining All Three: A Complete Example

The canonical pattern: useActionState for form management + useOptimistic for immediate list updates:

'use client';
 
import { useActionState, useOptimistic, useRef } from 'react';
import { addTodo } from './actions';
 
type Todo = { id: string; text: string; completed: boolean };
type State = { error?: string };
 
export function TodoList({ initialTodos }: { initialTodos: Todo[] }) {
  const formRef = useRef<HTMLFormElement>(null);
 
  // Real todo list (from server)
  const [todos, setTodos] = React.useState(initialTodos);
 
  // Optimistic todo list (shown immediately)
  const [optimisticTodos, addOptimisticTodo] = useOptimistic(
    todos,
    (current, newTodo: Todo) => [...current, newTodo]
  );
 
  const [state, action, isPending] = useActionState<State, FormData>(
    async (prevState, formData) => {
      const text = formData.get('text') as string;
 
      // Optimistic update: add todo immediately
      addOptimisticTodo({
        id: `temp-${Date.now()}`,  // temporary ID
        text,
        completed: false,
      });
 
      // Reset form immediately
      formRef.current?.reset();
 
      // Call the actual server action
      const result = await addTodo(formData);
 
      if (result.error) {
        return { error: result.error };
        // useOptimistic will revert because the real todos haven't changed
      }
 
      // Sync real state with server result
      setTodos(result.todos);
      return {};
    },
    {}
  );
 
  return (
    <div>
      <ul>
        {optimisticTodos.map((todo) => (
          <li
            key={todo.id}
            className={todo.id.startsWith('temp-') ? 'opacity-60' : ''}
          >
            {todo.text}
            {todo.id.startsWith('temp-') && <span> (saving...)</span>}
          </li>
        ))}
      </ul>
 
      <form ref={formRef} action={action}>
        <input name="text" required placeholder="New todo..." />
        {state.error && <p className="text-red-500">{state.error}</p>}
        <button type="submit" disabled={isPending}>
          {isPending ? 'Adding...' : 'Add'}
        </button>
      </form>
    </div>
  );
}

The temporary items render with reduced opacity and a "(saving...)" tag. When the server responds, setTodos(result.todos) updates the real state with the server-assigned IDs, and the optimistic overlay is replaced.

---

The Pending State Pattern

Beyond spinners, a well-designed pending state communicates exactly what is happening and prevents double-submission.

Disable the Trigger

Always disable the submit button (or the entire form) while isPending is true:

<button type="submit" disabled={isPending} aria-busy={isPending}>
  {isPending ? (
    <>
      <Spinner className="w-4 h-4 animate-spin" />
      Saving...
    </>
  ) : (
    'Save'
  )}
</button>

Skeleton vs Spinner

For content that takes > 300ms, a skeleton is better UX than a spinner. Use Suspense boundaries with skeleton fallbacks for the loading state:

// For slow operations, use Suspense + skeleton
<Suspense fallback={<CommentSkeleton />}>
  <CommentList postId={postId} />
</Suspense>
 
// For fast optimistic operations, use inline pending state
<LikeButton isPending={isPending} />

useFormStatus for Deep Components

useFormStatus (from react-dom) reads the pending state of the nearest parent <form> — useful for submit buttons nested inside form components:

'use client';
import { useFormStatus } from 'react-dom';
 
// This component doesn't need to receive isPending as a prop
export function SubmitButton({ children }: { children: React.ReactNode }) {
  const { pending } = useFormStatus();
 
  return (
    <button type="submit" disabled={pending} aria-busy={pending}>
      {pending ? 'Saving...' : children}
    </button>
  );
}
 
// Usage: works automatically inside any form
<form action={myAction}>
  <input name="title" />
  <SubmitButton>Create Post</SubmitButton>
</form>

---

Error Handling and Rollback Patterns

Explicit Rollback with Error Boundaries

For operations that must roll back cleanly (financial, irreversible):

async function handleDelete(id: string) {
  // Store the item before optimistic removal
  const itemToRestore = items.find(item => item.id === id);
 
  // Optimistic: remove immediately
  addOptimisticItems(items.filter(item => item.id !== id));
 
  try {
    await deleteItem(id);
    setItems(prev => prev.filter(item => item.id !== id));
  } catch {
    // Explicit rollback: restore the removed item
    setItems(prev => [...prev, itemToRestore!]);
    toast.error('Failed to delete. Please try again.');
  }
}

Toasts for Async Feedback

Optimistic UI removes the "loading" state, but users still need to know when something fails:

const [state, action] = useActionState(async (prev, formData) => {
  const result = await createPost(formData);
  if (result.error) {
    toast.error(result.error);
    return { error: result.error };
  }
  toast.success('Post created!');
  return { success: true };
}, {});

---

When NOT to Use Optimistic UI

Optimistic UI is a UX enhancement, not a correctness guarantee. Do not use it when:

• The operation is not idempotent — if showing the wrong result before server confirmation causes confusion (e.g., payment confirmations, inventory deduction)
• Rollback is disorienting — if the rollback experience is worse than waiting (e.g., the user navigated away expecting success)
• The operation is fast — if the server responds in < 100ms, optimistic UI adds complexity with no UX benefit
• You need the server response to continue — if the UI flow depends on a server-assigned ID or token, you must wait for the response

---

The useTransition Alternative

For non-form async operations (button clicks that trigger state transitions), useTransition provides isPending without the form machinery:

'use client';
import { useTransition } from 'react';
import { publishPost } from './actions';
 
export function PublishButton({ postId }: { postId: string }) {
  const [isPending, startTransition] = useTransition();
 
  function handlePublish() {
    startTransition(async () => {
      await publishPost(postId);
    });
  }
 
  return (
    <button onClick={handlePublish} disabled={isPending}>
      {isPending ? 'Publishing...' : 'Publish'}
    </button>
  );
}

useTransition marks the state update as non-urgent — React can interrupt it if higher-priority updates arrive (user input). Useful for transitions that should not block typing or other interactions.

---

Summary

• useActionState — connects a Server Action to component state; gives you state, action, and isPending; Server Action signature gains prevState as first param
• useOptimistic — shows an immediate temporary value; auto-reverts to real state when the async operation completes; rollback is automatic on error
• useFormStatus — reads pending state from the nearest parent form; avoids prop-drilling isPending into nested submit buttons
• useTransition — marks async state updates as non-urgent; provides isPending for non-form button interactions
• The pattern: optimistic update → async server call → sync real state on success → auto-rollback on failure
• When to skip it: payment flows, irreversible operations, fast operations (< 100ms), flows that depend on server-assigned values

Next: P-4 — Authentication with Auth.js v5 — session management, OAuth providers, database sessions, and protecting routes with middleware.

---