Optimistic UI Pattern in React 19

User taps Like
  → spinner (150–400ms)
  → count updates

User taps Like
  → count updates immediately (0ms perceived)
  → server confirms or rolls back in background

const [optimisticState, addOptimistic] = useOptimistic(realState, updateFn)

'use client'
 
import { useOptimistic } from 'react'
 
type Todo = { id: string; text: string; pending?: boolean }
 
function TodoList({ todos }: { todos: Todo[] }) {
  const [optimisticTodos, addOptimisticTodo] = useOptimistic(todos, (currentTodos, newTodo: Todo) => [
    ...currentTodos,
    { ...newTodo, pending: true },
  ])
 
  // Render optimisticTodos — not todos — so pending items appear instantly
  return (
    <ul>
      {optimisticTodos.map((todo) => (
        <li key={todo.id} className={todo.pending ? 'opacity-60' : ''}>
          {todo.text}
        </li>
      ))}
    </ul>
  )
}

'use client'
 
import { useOptimistic, useState, startTransition } from 'react'
 
type Item = { id: string; label: string }
 
export function OptimisticList() {
  // Step 1 — real state
  const [items, setItems] = useState<Item[]>([])
 
  // Step 2 — optimistic pair
  const [optimisticItems, addOptimisticItem] = useOptimistic(items, (current, newItem: Item) => [...current, newItem])
 
  async function handleAdd(label: string) {
    const temp: Item = { id: crypto.randomUUID(), label }
 
    startTransition(async () => {
      // Step 5 — immediate UI
      addOptimisticItem(temp)
 
      // Step 6 — server
      const saved = await fetch('/api/items', {
        method: 'POST',
        body: JSON.stringify({ label }),
      }).then((r) => r.json())
 
      // Step 7 — sync real state
      setItems((prev) => [...prev, saved])
    })
  }
 
  // Step 3 — render optimistic
  return (
    <ul>
      {optimisticItems.map((item) => (
        <li key={item.id}>{item.label}</li>
      ))}
      <button type="button" onClick={() => handleAdd('New item')}>
        Add
      </button>
    </ul>
  )
}

'use client'
 
import { useOptimistic, useState, startTransition } from 'react'
 
type LikeState = {
  count: number
  likedByMe: boolean
}
 
async function toggleLikeApi(postId: string, liked: boolean): Promise<LikeState> {
  const res = await fetch(`/api/posts/${postId}/like`, {
    method: liked ? 'POST' : 'DELETE',
  })
  if (!res.ok) throw new Error('Like failed')
  return res.json()
}
 
export function LikeButton({ postId, initial }: { postId: string; initial: LikeState }) {
  const [likes, setLikes] = useState(initial)
 
  const [optimisticLikes, addOptimisticLike] = useOptimistic(likes, (current, delta: number) => ({
    count: Math.max(0, current.count + delta),
    likedByMe: delta > 0,
  }))
 
  function handleClick() {
    const nextLiked = !optimisticLikes.likedByMe
    const delta = nextLiked ? 1 : -1
 
    startTransition(async () => {
      addOptimisticLike(delta)
 
      try {
        const serverState = await toggleLikeApi(postId, nextLiked)
        setLikes(serverState)
      } catch {
        // Real state unchanged — optimistic overlay reverts when transition ends
      }
    })
  }
 
  return (
    <button
      type="button"
      aria-pressed={optimisticLikes.likedByMe}
      onClick={handleClick}
      className={optimisticLikes.likedByMe ? 'text-red-500' : ''}>
      ♥ {optimisticLikes.count}
    </button>
  )
}

'use client'
 
import { useOptimistic, useState, startTransition } from 'react'
 
type Message = {
  id: string
  text: string
  author: 'me' | 'them'
  pending?: boolean
  failed?: boolean
}
 
async function sendMessageApi(text: string): Promise<Message> {
  const res = await fetch('/api/messages', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ text }),
  })
  if (!res.ok) throw new Error('Send failed')
  return res.json()
}
 
export function ChatThread({ initialMessages }: { initialMessages: Message[] }) {
  const [messages, setMessages] = useState(initialMessages)
 
  const [optimisticMessages, addOptimisticMessage] = useOptimistic(messages, (current, msg: Message) => [
    ...current,
    msg,
  ])
 
  function handleSend(text: string) {
    const tempId = crypto.randomUUID()
    const optimisticMsg: Message = { id: tempId, text, author: 'me', pending: true }
 
    startTransition(async () => {
      addOptimisticMessage(optimisticMsg)
 
      try {
        const saved = await sendMessageApi(text)
        setMessages((prev) => [...prev.filter((m) => m.id !== tempId), saved])
      } catch {
        setMessages((prev) => prev.map((m) => (m.id === tempId ? { ...m, pending: false, failed: true } : m)))
      }
    })
  }
 
  return (
    <div className="flex flex-col gap-2">
      {optimisticMessages.map((msg) => (
        <div
          key={msg.id}
          className={`max-w-xs rounded px-3 py-2 ${msg.author === 'me' ? 'ml-auto bg-blue-500 text-white' : 'bg-neutral-200'} ${msg.pending ? 'opacity-70' : ''} ${msg.failed ? 'line-through opacity-50' : ''}`}>
          {msg.text}
          {msg.pending && <span className="ml-1 text-xs">…</span>}
          {msg.failed && <span className="ml-1 text-xs">failed</span>}
        </div>
      ))}
      <ChatInput onSend={handleSend} />
    </div>
  )
}
 
function ChatInput({ onSend }: { onSend: (text: string) => void }) {
  return (
    <form
      onSubmit={(e) => {
        e.preventDefault()
        const fd = new FormData(e.currentTarget)
        const text = String(fd.get('text') ?? '').trim()
        if (!text) return
        onSend(text)
        e.currentTarget.reset()
      }}>
      <input name="text" placeholder="Type a message…" className="flex-1 rounded border px-3 py-2" />
      <button type="submit">Send</button>
    </form>
  )
}

'use client'
 
import { useOptimistic, useState, startTransition } from 'react'
 
type CartItem = { productId: string; name: string; qty: number }
 
type CartAction = { type: 'add'; productId: string; name: string } | { type: 'remove'; productId: string }
 
function applyCartAction(items: CartItem[], action: CartAction): CartItem[] {
  switch (action.type) {
    case 'add': {
      const existing = items.find((i) => i.productId === action.productId)
      if (existing) {
        return items.map((i) => (i.productId === action.productId ? { ...i, qty: i.qty + 1 } : i))
      }
      return [...items, { productId: action.productId, name: action.name, qty: 1 }]
    }
    case 'remove':
      return items
        .map((i) => (i.productId === action.productId ? { ...i, qty: i.qty - 1 } : i))
        .filter((i) => i.qty > 0)
    default:
      return items
  }
}
 
async function syncCart(action: CartAction): Promise<CartItem[]> {
  const res = await fetch('/api/cart', {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(action),
  })
  if (!res.ok) throw new Error('Cart sync failed')
  return res.json()
}
 
export function CartProviderDemo({ initialItems }: { initialItems: CartItem[] }) {
  const [cart, setCart] = useState(initialItems)
 
  const [optimisticCart, addOptimisticCart] = useOptimistic(cart, applyCartAction)
 
  function mutate(action: CartAction) {
    startTransition(async () => {
      addOptimisticCart(action)
 
      try {
        const serverCart = await syncCart(action)
        setCart(serverCart)
      } catch {
        // Rollback: real cart unchanged; optional toast in section 7
      }
    })
  }
 
  const total = optimisticCart.reduce((sum, i) => sum + i.qty, 0)
 
  return (
    <div>
      <p className="font-bold">Cart ({total} items)</p>
      <ul>
        {optimisticCart.map((item) => (
          <li key={item.productId} className="flex items-center gap-2">
            {item.name} × {item.qty}
            <button type="button" onClick={() => mutate({ type: 'remove', productId: item.productId })}>
              −
            </button>
          </li>
        ))}
      </ul>
      <button type="button" onClick={() => mutate({ type: 'add', productId: 'sku-1', name: 'Headphones' })}>
        Add Headphones
      </button>
    </div>
  )
}

'use client'
 
import { useOptimistic, useState, startTransition } from 'react'
 
type VoteState = { optionId: string; votes: number }
 
export function PollOption({
  optionId,
  initial,
  onVote,
}: {
  optionId: string
  initial: VoteState
  onVote: (id: string) => Promise<VoteState>
}) {
  const [vote, setVote] = useState(initial)
  const [optimisticVote, addOptimisticVote] = useOptimistic(vote, (_, next: VoteState) => next)
  const [error, setError] = useState<string | null>(null)
 
  function handleVote() {
    setError(null)
    const optimisticNext = { optionId, votes: vote.votes + 1 }
 
    startTransition(async () => {
      addOptimisticVote(optimisticNext)
 
      try {
        const confirmed = await onVote(optionId)
        setVote(confirmed)
      } catch (err) {
        // Real state stays at `vote` — optimistic resyncs automatically
        setError(err instanceof Error ? err.message : 'Vote failed — try again')
        showToast('Could not register vote. Please retry.')
      }
    })
  }
 
  return (
    <div>
      <button type="button" onClick={handleVote}>
        {optimisticVote.optionId} ({optimisticVote.votes})
      </button>
      {error && <p className="text-sm text-red-600">{error}</p>}
    </div>
  )
}
 
function showToast(message: string) {
  // wire to your toast library — sonner, react-hot-toast, etc.
  console.warn(message)
}

addOptimistic(next)     → UI shows next immediately
await server()          → pending transition
success: setReal(server) → optimistic === real
failure: real unchanged  → transition ends → optimistic reverts to real

// Optimistic: apply local patch immediately
addOptimisticPatch({ type: 'insert', pos: cursor, text: 'hello' })
 
// Server: operational transform or CRDT merge
const merged = await syncDocumentPatch(patch)
setDocument(merged) // real state replaces optimistic

// Show "thinking…" or partial tokens optimistically while awaiting first chunk
addOptimisticMessage({ id: 'stream', text: '▍', author: 'ai', pending: true })
 
const stream = await fetch('/api/chat/stream')
// Replace optimistic placeholder as tokens arrive via setState on real messages