React useOptimistic Hook Guide

The useOptimistic hook enables optimistic UI updates that show immediately while async operations complete. Here's how to use it.

Basic Usage#

import { useOptimistic, useState } from 'react';

function TodoList({ todos, addTodo }) {
  const [optimisticTodos, setOptimisticTodos] = useOptimistic(
    todos,
    (state, newTodo) => [...state, { ...newTodo, pending: true }]
  );

  async function handleSubmit(formData) {
    const newTodo = {
      id: Date.now(),
      text: formData.get('text'),
    };

    // Show immediately
    setOptimisticTodos(newTodo);

    // Actual async operation
    await addTodo(newTodo);
  }

  return (
    <div>
      <form action={handleSubmit}>
        <input name="text" />
        <button type="submit">Add</button>
      </form>

      <ul>
        {optimisticTodos.map((todo) => (
          <li key={todo.id} style={{ opacity: todo.pending ? 0.5 : 1 }}>
            {todo.text}
            {todo.pending && ' (saving...)'}
          </li>
        ))}
      </ul>
    </div>
  );
}

Like Button#

import { useOptimistic } from 'react';

function LikeButton({ postId, initialLiked, initialCount, onLike }) {
  const [optimistic, setOptimistic] = useOptimistic(
    { liked: initialLiked, count: initialCount },
    (state, newLiked) => ({
      liked: newLiked,
      count: newLiked ? state.count + 1 : state.count - 1,
    })
  );

  async function handleClick() {
    const newLiked = !optimistic.liked;

    // Update UI immediately
    setOptimistic(newLiked);

    // Sync with server
    await onLike(postId, newLiked);
  }

  return (
    <button onClick={handleClick}>
      {optimistic.liked ? '❤️' : '🤍'} {optimistic.count}
    </button>
  );
}

Message Sending#

import { useOptimistic, useState } from 'react';

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

  async function handleSend(formData) {
    const text = formData.get('message');
    const tempId = `temp-${Date.now()}`;

    const newMessage = {
      id: tempId,
      text,
      sender: 'me',
      timestamp: new Date(),
    };

    // Show message immediately
    addOptimisticMessage(newMessage);

    // Send to server
    await sendMessage(text);
  }

  return (
    <div className="chat">
      <div className="messages">
        {optimisticMessages.map((msg) => (
          <div
            key={msg.id}
            className={`message ${msg.sender} ${msg.sending ? 'sending' : ''}`}
          >
            {msg.text}
            {msg.sending && <span className="status">Sending...</span>}
          </div>
        ))}
      </div>

      <form action={handleSend}>
        <input name="message" placeholder="Type a message..." />
        <button type="submit">Send</button>
      </form>
    </div>
  );
}

Delete with Undo#

import { useOptimistic, useState } from 'react';

function ItemList({ items, deleteItem }) {
  const [deletedIds, setDeletedIds] = useState(new Set());

  const [optimisticItems, setOptimisticItems] = useOptimistic(
    items.filter((item) => !deletedIds.has(item.id)),
    (state, deletedId) => state.filter((item) => item.id !== deletedId)
  );

  async function handleDelete(id) {
    // Show deletion immediately
    setOptimisticItems(id);

    // Start undo timer
    const undoTimeout = setTimeout(async () => {
      setDeletedIds((prev) => new Set([...prev, id]));
      await deleteItem(id);
    }, 5000);

    // Return undo function
    return () => clearTimeout(undoTimeout);
  }

  return (
    <ul>
      {optimisticItems.map((item) => (
        <li key={item.id}>
          {item.name}
          <button onClick={() => handleDelete(item.id)}>Delete</button>
        </li>
      ))}
    </ul>
  );
}

Form Submission#

import { useOptimistic, useActionState } from 'react';

function CommentForm({ postId, comments, addComment }) {
  const [optimisticComments, addOptimisticComment] = useOptimistic(
    comments,
    (state, newComment) => [
      ...state,
      { ...newComment, pending: true },
    ]
  );

  async function submitComment(formData) {
    const comment = {
      id: `temp-${Date.now()}`,
      text: formData.get('comment'),
      author: 'Current User',
      createdAt: new Date(),
    };

    addOptimisticComment(comment);

    await addComment(postId, comment.text);
  }

  return (
    <div>
      <ul className="comments">
        {optimisticComments.map((comment) => (
          <li
            key={comment.id}
            className={comment.pending ? 'pending' : ''}
          >
            <strong>{comment.author}</strong>
            <p>{comment.text}</p>
            {comment.pending && <span>Posting...</span>}
          </li>
        ))}
      </ul>

      <form action={submitComment}>
        <textarea name="comment" required />
        <button type="submit">Post Comment</button>
      </form>
    </div>
  );
}

Toggle with Multiple States#

import { useOptimistic } from 'react';

function BookmarkButton({ itemId, status, onToggle }) {
  // status: 'none' | 'bookmarked' | 'favorited'
  const [optimisticStatus, setOptimisticStatus] = useOptimistic(
    status,
    (_, newStatus) => newStatus
  );

  async function handleToggle(newStatus) {
    setOptimisticStatus(newStatus);
    await onToggle(itemId, newStatus);
  }

  return (
    <div className="bookmark-actions">
      <button
        className={optimisticStatus === 'bookmarked' ? 'active' : ''}
        onClick={() =>
          handleToggle(optimisticStatus === 'bookmarked' ? 'none' : 'bookmarked')
        }
      >
        🔖 Bookmark
      </button>
      <button
        className={optimisticStatus === 'favorited' ? 'active' : ''}
        onClick={() =>
          handleToggle(optimisticStatus === 'favorited' ? 'none' : 'favorited')
        }
      >
        ⭐ Favorite
      </button>
    </div>
  );
}

Cart Updates#

import { useOptimistic } from 'react';

function CartItem({ item, updateQuantity, removeItem }) {
  const [optimisticItem, setOptimisticItem] = useOptimistic(
    item,
    (state, update) => ({
      ...state,
      ...update,
      updating: true,
    })
  );

  async function handleQuantityChange(newQuantity) {
    if (newQuantity === 0) {
      setOptimisticItem({ removed: true });
      await removeItem(item.id);
    } else {
      setOptimisticItem({ quantity: newQuantity });
      await updateQuantity(item.id, newQuantity);
    }
  }

  if (optimisticItem.removed) {
    return null;
  }

  return (
    <div className={`cart-item ${optimisticItem.updating ? 'updating' : ''}`}>
      <span>{item.name}</span>
      <div className="quantity-controls">
        <button onClick={() => handleQuantityChange(optimisticItem.quantity - 1)}>
          -
        </button>
        <span>{optimisticItem.quantity}</span>
        <button onClick={() => handleQuantityChange(optimisticItem.quantity + 1)}>
          +
        </button>
      </div>
      <span>${(item.price * optimisticItem.quantity).toFixed(2)}</span>
    </div>
  );
}

Error Handling#

import { useOptimistic, useState } from 'react';

function EditableItem({ item, updateItem }) {
  const [error, setError] = useState(null);

  const [optimisticItem, setOptimisticItem] = useOptimistic(
    item,
    (state, newValue) => ({ ...state, value: newValue, saving: true })
  );

  async function handleSave(newValue) {
    setError(null);
    setOptimisticItem(newValue);

    try {
      await updateItem(item.id, newValue);
    } catch (err) {
      setError(err.message);
      // The optimistic update will be reverted when
      // the actual item prop updates
    }
  }

  return (
    <div>
      <input
        value={optimisticItem.value}
        onChange={(e) => handleSave(e.target.value)}
        disabled={optimisticItem.saving}
      />
      {optimisticItem.saving && <span>Saving...</span>}
      {error && <span className="error">{error}</span>}
    </div>
  );
}

Batch Operations#

import { useOptimistic } from 'react';

function BulkActions({ items, selectedIds, onBulkDelete, onBulkArchive }) {
  const [optimisticItems, setOptimisticItems] = useOptimistic(
    items,
    (state, action) => {
      switch (action.type) {
        case 'delete':
          return state.filter((item) => !action.ids.includes(item.id));
        case 'archive':
          return state.map((item) =>
            action.ids.includes(item.id)
              ? { ...item, archived: true, pending: true }
              : item
          );
        default:
          return state;
      }
    }
  );

  async function handleBulkDelete() {
    setOptimisticItems({ type: 'delete', ids: [...selectedIds] });
    await onBulkDelete([...selectedIds]);
  }

  async function handleBulkArchive() {
    setOptimisticItems({ type: 'archive', ids: [...selectedIds] });
    await onBulkArchive([...selectedIds]);
  }

  return (
    <div>
      <div className="actions">
        <button onClick={handleBulkDelete} disabled={selectedIds.size === 0}>
          Delete Selected
        </button>
        <button onClick={handleBulkArchive} disabled={selectedIds.size === 0}>
          Archive Selected
        </button>
      </div>

      <ul>
        {optimisticItems.map((item) => (
          <li key={item.id} className={item.pending ? 'pending' : ''}>
            {item.name}
          </li>
        ))}
      </ul>
    </div>
  );
}

Best Practices#

When to Use:
✓ Likes/favorites/bookmarks
✓ Adding items to lists
✓ Form submissions
✓ Toggle states
✓ Real-time updates

Patterns:
✓ Show pending state visually
✓ Handle errors gracefully
✓ Revert on failure
✓ Use with server actions

Visual Feedback:
✓ Reduce opacity for pending
✓ Show loading indicators
✓ Disable during update
✓ Clear error states

Avoid:
✗ Critical data without confirmation
✗ Complex multi-step operations
✗ Operations that can't be reverted
✗ Ignoring error states

The useOptimistic hook provides immediate UI feedback while async operations complete in the background. Use it for actions like likes, adding items, and form submissions where instant feedback improves perceived performance. Always provide visual indicators for pending states and handle errors gracefully by reverting the UI when operations fail. Combine with server actions for a seamless optimistic update pattern.