React: Decoded

Core Definition

useOptimistic() is a React Hook that lets you apply an optimistic update to state while an asynchronous action is in progress. It accepts the current state and an update function that describes the optimistic change. The state is immediately updated optimistically, and once the asynchronous action completes, the state is reconciled with the actual result.

Key Characteristics

Immediate UI Feedback: updates the UI instantly without waiting for the server response, making the application feel faster and more responsive.
Automatic Reversion: if the asynchronous action fails, the UI automatically reverts to the last known actual state, ensuring data consistency.
State Management: it takes the current state and an update function, returning an optimistic version of the state that you can render in your component.

When to use?

Use it for actions that have a high likelihood of success and where immediate feedback is beneficial. Common cases include submitting forms (like sending a message), liking a post, or adding an item to a shopping cart.

Examples

Optimistic Form Submission: this example shows a message list that optimistically adds a new message to the UI while the server request is in progress. If the request fails, the message is removed.

Code Examples

https://codesandbox.io/p/sandbox/form-fpxjyl

Optimistic Form

 // App.tsx 
'use client'

import { useOptimistic, useRef, useState } from 'react'
import sendMessage from './actions/sendMessage'

type Message = {
  text: string
  key: number
  sending?: boolean
}

export default function App() {
  const [messages, setMessages] = useState<Message[]>([])
  const [optimisticMessages, addOptimisticMessage] = useOptimistic(
    messages,
    (state: Message[], newMessage: string) => [
      ...state,
      { text: newMessage, key: state.length, sending: true },
    ]
  )
  const formRef = useRef<HTMLFormElement>(null)

  async function formAction(formData: FormData) {
    const message = formData.get('message')?.toString()
    if (!message) return

    addOptimisticMessage(message)
    formRef.current?.reset()

    try {
      const sentMessage = await sendMessage(message)
      setMessages((currentMessages) => [
        ...currentMessages,
        { text: sentMessage, key: messages.length },
      ])
    } catch (error) {
      console.error(error)
    }
  }

  return (
    <div>
      <p>
        Typing in message and clicking "Send" will use optimistic update.
        <br />
        To demonstrate failed operation type in "error" and click send.
      </p>
      <div>
        {optimisticMessages.map((message) => (
          <div key={message.key}>
            {message.text}
            {message.sending && <small> (Sending...)</small>}
          </div>
        ))}
      </div>
      <form action={formAction} ref={formRef}>
        <input type="text" name="message" placeholder="Type a message..." />
        <button type="submit">Send</button>
      </form>
    </div>
  )
}

 // sendMessage.tsx 
export default async function sendMessage(message: string) {
  // mock API call
  await new Promise((res) => setTimeout(res, 1000))
  if (message.toLowerCase().includes('error')) {
    throw new Error("Couldn't send message")
  }
  return message
}