name	implementing-optimistic-updates
description	Teaches useOptimistic hook for immediate UI updates during async operations in React 19. Use when implementing optimistic UI patterns, instant feedback, or reducing perceived latency.
allowed-tools	Read, Write, Edit
version	1.0.0

Optimistic UI Updates with useOptimistic

This skill teaches you how to use React 19's `useOptimistic` hook for immediate UI feedback during async operations.

- User mentions optimistic updates, instant feedback, or perceived performance - Working with mutations that should feel instant (likes, comments, todos) - Need to show pending states before server confirmation

`useOptimistic` enables immediate UI updates that revert if the operation fails:

Shows anticipated result immediately
Reverts to actual state when async completes
Provides better UX than waiting for server
Works with startTransition for async operations

## Basic Pattern

import { useOptimistic, startTransition } from 'react';

function MessageList({ messages, sendMessage }) {
  const [optimisticMessages, addOptimisticMessage] = useOptimistic(
    messages,
    (state, newMessage) => [...state, { ...newMessage, sending: true }]
  );

  const handleSend = async (text) => {
    addOptimisticMessage({ id: Date.now(), text });

    startTransition(async () => {
      await sendMessage(text);
    });
  };

  return (
    <ul>
      {optimisticMessages.map((msg) => (
        <li key={msg.id}>
          {msg.text} {msg.sending && <small>(Sending...)</small>}
        </li>
      ))}
    </ul>
  );
}

## Like Button Example

function LikeButton({ postId, initialLikes }) {
  const [optimisticLikes, addOptimisticLike] = useOptimistic(
    initialLikes,
    (state, amount) => state + amount
  );

  const handleLike = async () => {
    addOptimisticLike(1);

    startTransition(async () => {
      await fetch(`/api/posts/${postId}/like`, { method: 'POST' });
    });
  };

  return (
    <button onClick={handleLike}>
      ❤️ {optimisticLikes}
    </button>
  );
}

For comprehensive useOptimistic documentation, see: research/react-19-comprehensive.md lines 182-240.

## MUST - Keep update function pure (no side effects) - Pair with `startTransition` for async operations - Provide visual feedback for pending states

NEVER

Mutate state directly in update function
Use for critical operations that must succeed
Skip error handling for failed optimistic updates

## Related Skills

If handling Prisma transaction errors in optimistic updates, use the handling-transaction-errors skill from prisma-6 for graceful P-code error handling.

implementing-optimistic-updates

Install Skill

SKILL.md

Optimistic UI Updates with useOptimistic

NEVER