Hook useOptimistic

Q: Como useOptimistic difere de gerenciar estado otimista manualmente com useState?

useOptimistic reverte automaticamente em caso de falha e mescla corretamente quando o estado real é atualizado. Implementações manuais exigem que você rastreie o estado original, lide com o rollback e mescle os resultados sozinho. useOptimistic é menos propenso a erros para padrões comuns como adicionar, alternar ou excluir itens.

Q: Armadilha: O que acontece se eu mutar o array de estado dentro da updateFn?

Mutar o array (por exemplo, state.push(item)) causa bugs porque o React espera atualizações imutáveis. Sempre retorne um novo array ou objeto de updateFn.

Q: Quando devo usar useOptimistic em vez de apenas mostrar um spinner com isPending?

Use useOptimistic quando os usuários esperam feedback instantâneo (mensagens, curtidas, alternâncias). Use um spinner quando o resultado for incerto e mostrar um estado previsto puder ser enganoso. Para ações de baixa latência, um spinner é bom; para ações de alta latência, a UI otimista parece muito mais rápida.

Mostra um estado otimista (previsto) enquanto uma ação assíncrona está em andamento, e depois reconcilia quando ela é concluída.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

const [optimisticMessages, addOptimistic] = useOptimistic(
  messages,
  (currentState, newMessage: string) => [
    ...currentState,
    { text: newMessage, sending: true },
  ]
);
 
// Call inside an action or transition
startTransition(() => {
  addOptimistic("Hello!");
  await sendMessage("Hello!");
});

Quando usar isso: Você quer que a interface do usuário seja atualizada instantaneamente quando um usuário realiza uma ação (como enviar uma mensagem, curtir uma postagem ou adicionar um item) enquanto o servidor processa a solicitação em segundo plano.

Exemplo de Trabalho

"use client";
 
import { useOptimistic, useActionState, useRef } from "react";
 
interface Message {
  id: number;
  text: string;
  sending?: boolean;
}
 
async function sendMessageAction(
  prevState: Message[],
  formData: FormData
): Promise<Message[]> {
  const text = formData.get("message") as string;
 
  // Simulate server delay
  await new Promise((resolve) => setTimeout(resolve, 1500));
 
  return [
    ...prevState,
    { id: Date.now(), text, sending: false },
  ];
}
 
export function Chat() {
  const [messages, formAction, isPending] = useActionState(sendMessageAction, [
    { id: 1, text: "Welcome to the chat!", sending: false },
  ]);
 
  const [optimisticMessages, addOptimistic] = useOptimistic(
    messages,
    (state, newMessage: string) => [
      ...state,
      { id: Date.now(), text: newMessage, sending: true },
    ]
  );
 
  const formRef = useRef<HTMLFormElement>(null);
 
  async function handleSubmit(formData: FormData) {
    const text = formData.get("message") as string;
    if (!text.trim()) return;
    formRef.current?.reset();
    addOptimistic(text);
    await formAction(formData);
  }
 
  return (
    <div className="space-y-3 max-w-sm">
      <ul className="space-y-2">
        {optimisticMessages.map((msg) => (
          <li
            key={msg.id}
            className={`text-sm px-3 py-2 rounded ${
              msg.sending
                ? "bg-gray-100 text-gray-400 italic"
                : "bg-blue-50 text-gray-900"
            }`}
          >
            {msg.text}
            {msg.sending && <span className="ml-2 text-xs">(sending...)</span>}
          </li>
        ))}
      </ul>
 
      <form ref={formRef} action={handleSubmit} className="flex gap-2">
        <input
          name="message"
          className="flex-1 border rounded px-3 py-2"
          placeholder="Type a message..."
          required
        />
        <button
          type="submit"
          disabled={isPending}
          className="px-4 py-2 bg-blue-600 text-white rounded disabled:opacity-50"
        >
          Send
        </button>
      </form>
    </div>
  );
}

O que isso demonstra:

As mensagens aparecem instantaneamente com um estado visual de "enviando".
Assim que a ação do servidor é concluída, o estado otimista é substituído pelo estado real.
Se a ação falhar, o estado otimista reverte automaticamente.
O formulário é redefinido imediatamente para uma sensação ágil, não após a resposta do servidor.

Mergulho Profundo

Como Funciona

useOptimistic recebe o estado real e uma função de atualização que descreve como aplicar uma mudança otimista.
Quando você chama addOptimistic(valor), o React imediatamente mostra o estado otimista mesclado.
O estado otimista é temporário - ele sobrepõe o estado real apenas enquanto uma ação assíncrona (transição) está pendente.
Quando a ação é concluída e o estado real é atualizado, a sobreposição otimista é removida e o estado real assume o controle.
Se a ação falhar, o estado otimista é automaticamente descartado, revertendo para o estado real.

Parâmetros e Valores de Retorno

Parâmetro	Tipo	Descrição
`state`	`T`	O valor de estado real (fonte da verdade)
`updateFn`	`(currentState: T, optimisticValue: V) => T`	Função pura que mescla o valor otimista no estado atual

Retorno	Tipo	Descrição
`optimisticState`	`T`	Estado atual com atualizações otimistas aplicadas (igual a `state` quando nenhuma ação está pendente)
`addOptimistic`	`(value: V) => void`	Função para acionar uma atualização otimista

Variações

Botão de curtir otimista:

const [optimisticLikes, addLike] = useOptimistic(
  likes,
  (current, _: null) => current + 1
);
 
async function handleLike() {
  startTransition(async () => {
    addLike(null);
    await likePost(postId);
  });
}
 
return (
  <button onClick={handleLike}>
    {optimisticLikes} Likes
  </button>
);

Alternância otimista de tarefa:

const [optimisticTodos, toggleOptimistic] = useOptimistic(
  todos,
  (state, toggledId: number) =>
    state.map((todo) =>
      todo.id === toggledId ? { ...todo, done: !todo.done } : todo
    )
);

Exclusão otimista:

const [optimisticItems, removeOptimistic] = useOptimistic(
  items,
  (state, removedId: string) => state.filter((item) => item.id !== removedId)
);

Notas TypeScript

// The generic types are inferred from parameters
const [optimistic, add] = useOptimistic(
  messages,                    // T = Message[]
  (state, text: string) => ... // V = string
);
// add: (value: string) => void
// optimistic: Message[]
 
// Explicit generics when needed
const [optimistic, add] = useOptimistic<Todo[], number>(
  todos,
  (state, toggledId) => state.map(t =>
    t.id === toggledId ? { ...t, done: !t.done } : t
  )
);

Armadilhas

Chamar addOptimistic fora de uma transição - O estado otimista só funciona corretamente dentro de uma ação assíncrona ou startTransition. Fora disso, a sobreposição é removida imediatamente. Correção: Sempre chame addOptimistic dentro de startTransition ou de uma ação de formulário.
Mutar estado em updateFn - Mutar o array de estado atual (por exemplo, state.push(item)) causa bugs. Correção: Retorne um novo array ou objeto de updateFn.
Sem callback de erro - Não há uma maneira integrada de mostrar um toast de erro quando o estado otimista reverte. Correção: Trate os erros na sua função de ação e atualize o estado com uma mensagem de erro.
Múltiplas atualizações otimistas rápidas - Cada chamada para addOptimistic é aplicada sobre o estado otimista anterior, o que pode levar a resultados inesperados se a função de atualização não for composível. Correção: Projete sua updateFn para ser idempotente ou aditiva.
Estado real obsoleto - Se o prop de estado real mudar de outra fonte enquanto uma ação estiver pendente, a sobreposição otimista recalcula sobre o novo estado real. Correção: Este é geralmente o comportamento correto, mas esteja ciente disso ao depurar.

Alternativas

Alternativa	Use Quando	Não Use Quando
`useState` com rollback manual	Você precisa de lógica de rollback ou tratamento de erros personalizado	Padrões otimistas simples onde o rollback automático é suficiente
`useTransition` com isPending	Você só precisa de um indicador de carregamento, não de um valor otimista	Você quer que a interface do usuário reflita o resultado esperado imediatamente
TanStack Query `onMutate`	Você usa TanStack Query e precisa de atualizações otimistas com invalidação de cache	Você está usando ações de servidor e quer uma solução leve
Desabilitar e spinner	A simplicidade é preferida e a latência é baixa	Os usuários esperam feedback instantâneo

Por que usar useOptimistic em vez de estado manual? useOptimistic reverte automaticamente em caso de falha e mescla corretamente com o estado real quando a ação é concluída. Implementações manuais são propensas a erros e verbosas.

FAQs

O que acontece com o estado otimista se a ação assíncrona falhar?

O estado otimista é automaticamente descartado quando a ação é concluída (sucesso ou falha).
A interface do usuário reverte para o estado real, efetivamente "revertendo" a atualização otimista.
Não há um callback de erro integrado - trate os erros na sua função de ação.

Por que devo chamar addOptimistic dentro de uma transição ou ação de formulário?

A sobreposição otimista só persiste enquanto uma ação assíncrona (transição) está pendente.
Se chamado fora de uma transição, a sobreposição é removida imediatamente na próxima renderização.
Sempre use startTransition ou uma ação de formulário para manter o estado otimista visível.

Como useOptimistic difere de gerenciar estado otimista manualmente com useState?

useOptimistic reverte automaticamente em caso de falha e mescla corretamente quando o estado real é atualizado.
Implementações manuais exigem que você rastreie o estado original, lide com o rollback e mescle os resultados sozinho.
useOptimistic é menos propenso a erros para padrões comuns como adicionar, alternar ou excluir itens.

Armadilha: O que acontece se eu mutar o array de estado dentro da updateFn?

Mutar o array (por exemplo, state.push(item)) causa bugs porque o React espera atualizações imutáveis.
Sempre retorne um novo array ou objeto de updateFn.

// Wrong
(state, newItem) => { state.push(newItem); return state; }
 
// Correct
(state, newItem) => [...state, newItem]

Posso chamar addOptimistic várias vezes antes que a ação seja concluída?

Sim. Cada chamada é aplicada sobre o estado otimista anterior.
Certifique-se de que sua updateFn seja composível - cada chamada deve produzir um resultado válido quando empilhada.
Todas as sobreposições otimistas são descartadas quando a ação é concluída.

Como mostro um toast de erro quando uma atualização otimista reverte?

Não há um callback integrado para detecção de rollback.
Trate os erros na sua função de ação e atualize o estado real com uma mensagem de erro.
Compare o estado real antes e depois da ação para detectar um rollback na interface do usuário.

Como eu digito useOptimistic com TypeScript?

const [optimistic, add] = useOptimistic(
  messages,                         // T = Message[]
  (state, text: string) => [        // V = string
    ...state,
    { id: Date.now(), text, sending: true },
  ]
);
// add: (value: string) => void
// optimistic: Message[]

Armadilha: O que acontece se o estado real mudar de outra fonte enquanto uma ação está pendente?

A sobreposição otimista recalcula sobre o novo estado real.
Este é geralmente o comportamento correto - a sobreposição se adapta à realidade mais recente.
Esteja ciente disso ao depurar valores otimistas inesperados.

Posso usar useOptimistic para um simples alternador de curtir/descurtir?

const [optimisticLikes, addLike] = useOptimistic(
  likes,
  (current, _: null) => current + 1
);
 
async function handleLike() {
  startTransition(async () => {
    addLike(null);
    await likePost(postId);
  });
}

Sim. O valor otimista é mostrado imediatamente; a contagem real é atualizada quando o servidor responde.

Quando devo usar useOptimistic em vez de apenas mostrar um spinner com isPending?

Use useOptimistic quando os usuários esperam feedback instantâneo (mensagens, curtidas, alternâncias).
Use um spinner quando o resultado for incerto e mostrar um estado previsto puder ser enganoso.
Para ações de baixa latência, um spinner é bom; para ações de alta latência, a UI otimista parece muito mais rápida.

Relacionados

useActionState - gerencia o estado do formulário que impulsiona atualizações otimistas
useTransition - transições alimentam o estado pendente do qual as atualizações otimistas dependem
use - primitivo do React 19 para consumir valores assíncronos
useState - o estado subjacente que useOptimistic sobrepõe

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

const [optimisticMessages, addOptimistic] = useOptimistic(
  messages,
  (currentState, newMessage: string) => [
    ...currentState,
    { text: newMessage, sending: true },
  ]
);
 
// Call inside an action or transition
startTransition(() => {
  addOptimistic("Hello!");
  await sendMessage("Hello!");
});

Exemplo de Trabalho

"use client";
 
import { useOptimistic, useActionState, useRef } from "react";
 
interface Message {
  id: number;
  text: string;
  sending?: boolean;
}
 
async function sendMessageAction(
  prevState: Message[],
  formData: FormData
): Promise<Message[]> {
  const text = formData.get("message") as string;
 
  // Simulate server delay
  await new Promise((resolve) => setTimeout(resolve, 1500));
 
  return [
    ...prevState,
    { id: Date.now(), text, sending: false },
  ];
}
 
export function Chat() {
  const [messages, formAction, isPending] = useActionState(sendMessageAction, [
    { id: 1, text: "Welcome to the chat!", sending: false },
  ]);
 
  const [optimisticMessages, addOptimistic] = useOptimistic(
    messages,
    (state, newMessage: string) => [
      ...state,
      { id: Date.now(), text: newMessage, sending: true },
    ]
  );
 
  const formRef = useRef<HTMLFormElement>(null);
 
  async function handleSubmit(formData: FormData) {
    const text = formData.get("message") as string;
    if (!text.trim()) return;
    formRef.current?.reset();
    addOptimistic(text);
    await formAction(formData);
  }
 
  return (
    <div className="space-y-3 max-w-sm">
      <ul className="space-y-2">
        {optimisticMessages.map((msg) => (
          <li
            key={msg.id}
            className={`text-sm px-3 py-2 rounded ${
              msg.sending
                ? "bg-gray-100 text-gray-400 italic"
                : "bg-blue-50 text-gray-900"
            }`}
          >
            {msg.text}
            {msg.sending && <span className="ml-2 text-xs">(sending...)</span>}
          </li>
        ))}
      </ul>
 
      <form ref={formRef} action={handleSubmit} className="flex gap-2">
        <input
          name="message"
          className="flex-1 border rounded px-3 py-2"
          placeholder="Type a message..."
          required
        />
        <button
          type="submit"
          disabled={isPending}
          className="px-4 py-2 bg-blue-600 text-white rounded disabled:opacity-50"
        >
          Send
        </button>
      </form>
    </div>
  );
}

O que isso demonstra:

As mensagens aparecem instantaneamente com um estado visual de "enviando".
Assim que a ação do servidor é concluída, o estado otimista é substituído pelo estado real.
Se a ação falhar, o estado otimista reverte automaticamente.
O formulário é redefinido imediatamente para uma sensação ágil, não após a resposta do servidor.

Mergulho Profundo

Como Funciona

useOptimistic recebe o estado real e uma função de atualização que descreve como aplicar uma mudança otimista.
Quando você chama addOptimistic(valor), o React imediatamente mostra o estado otimista mesclado.
O estado otimista é temporário - ele sobrepõe o estado real apenas enquanto uma ação assíncrona (transição) está pendente.
Quando a ação é concluída e o estado real é atualizado, a sobreposição otimista é removida e o estado real assume o controle.
Se a ação falhar, o estado otimista é automaticamente descartado, revertendo para o estado real.

Parâmetros e Valores de Retorno

Parâmetro	Tipo	Descrição
`state`	`T`	O valor de estado real (fonte da verdade)
`updateFn`	`(currentState: T, optimisticValue: V) => T`	Função pura que mescla o valor otimista no estado atual

Retorno	Tipo	Descrição
`optimisticState`	`T`	Estado atual com atualizações otimistas aplicadas (igual a `state` quando nenhuma ação está pendente)
`addOptimistic`	`(value: V) => void`	Função para acionar uma atualização otimista

Variações

Botão de curtir otimista:

const [optimisticLikes, addLike] = useOptimistic(
  likes,
  (current, _: null) => current + 1
);
 
async function handleLike() {
  startTransition(async () => {
    addLike(null);
    await likePost(postId);
  });
}
 
return (
  <button onClick={handleLike}>
    {optimisticLikes} Likes
  </button>
);

Alternância otimista de tarefa:

const [optimisticTodos, toggleOptimistic] = useOptimistic(
  todos,
  (state, toggledId: number) =>
    state.map((todo) =>
      todo.id === toggledId ? { ...todo, done: !todo.done } : todo
    )
);

Exclusão otimista:

const [optimisticItems, removeOptimistic] = useOptimistic(
  items,
  (state, removedId: string) => state.filter((item) => item.id !== removedId)
);

Notas TypeScript

// The generic types are inferred from parameters
const [optimistic, add] = useOptimistic(
  messages,                    // T = Message[]
  (state, text: string) => ... // V = string
);
// add: (value: string) => void
// optimistic: Message[]
 
// Explicit generics when needed
const [optimistic, add] = useOptimistic<Todo[], number>(
  todos,
  (state, toggledId) => state.map(t =>
    t.id === toggledId ? { ...t, done: !t.done } : t
  )
);

Armadilhas

Chamar addOptimistic fora de uma transição - O estado otimista só funciona corretamente dentro de uma ação assíncrona ou startTransition. Fora disso, a sobreposição é removida imediatamente. Correção: Sempre chame addOptimistic dentro de startTransition ou de uma ação de formulário.
Mutar estado em updateFn - Mutar o array de estado atual (por exemplo, state.push(item)) causa bugs. Correção: Retorne um novo array ou objeto de updateFn.
Sem callback de erro - Não há uma maneira integrada de mostrar um toast de erro quando o estado otimista reverte. Correção: Trate os erros na sua função de ação e atualize o estado com uma mensagem de erro.
Múltiplas atualizações otimistas rápidas - Cada chamada para addOptimistic é aplicada sobre o estado otimista anterior, o que pode levar a resultados inesperados se a função de atualização não for composível. Correção: Projete sua updateFn para ser idempotente ou aditiva.
Estado real obsoleto - Se o prop de estado real mudar de outra fonte enquanto uma ação estiver pendente, a sobreposição otimista recalcula sobre o novo estado real. Correção: Este é geralmente o comportamento correto, mas esteja ciente disso ao depurar.

Alternativas

Alternativa	Use Quando	Não Use Quando
`useState` com rollback manual	Você precisa de lógica de rollback ou tratamento de erros personalizado	Padrões otimistas simples onde o rollback automático é suficiente
`useTransition` com isPending	Você só precisa de um indicador de carregamento, não de um valor otimista	Você quer que a interface do usuário reflita o resultado esperado imediatamente
TanStack Query `onMutate`	Você usa TanStack Query e precisa de atualizações otimistas com invalidação de cache	Você está usando ações de servidor e quer uma solução leve
Desabilitar e spinner	A simplicidade é preferida e a latência é baixa	Os usuários esperam feedback instantâneo

FAQs

O que acontece com o estado otimista se a ação assíncrona falhar?

O estado otimista é automaticamente descartado quando a ação é concluída (sucesso ou falha).
A interface do usuário reverte para o estado real, efetivamente "revertendo" a atualização otimista.
Não há um callback de erro integrado - trate os erros na sua função de ação.

Por que devo chamar addOptimistic dentro de uma transição ou ação de formulário?

A sobreposição otimista só persiste enquanto uma ação assíncrona (transição) está pendente.
Se chamado fora de uma transição, a sobreposição é removida imediatamente na próxima renderização.
Sempre use startTransition ou uma ação de formulário para manter o estado otimista visível.

Como useOptimistic difere de gerenciar estado otimista manualmente com useState?

useOptimistic reverte automaticamente em caso de falha e mescla corretamente quando o estado real é atualizado.
Implementações manuais exigem que você rastreie o estado original, lide com o rollback e mescle os resultados sozinho.
useOptimistic é menos propenso a erros para padrões comuns como adicionar, alternar ou excluir itens.

Armadilha: O que acontece se eu mutar o array de estado dentro da updateFn?

Mutar o array (por exemplo, state.push(item)) causa bugs porque o React espera atualizações imutáveis.
Sempre retorne um novo array ou objeto de updateFn.

// Wrong
(state, newItem) => { state.push(newItem); return state; }
 
// Correct
(state, newItem) => [...state, newItem]

Posso chamar addOptimistic várias vezes antes que a ação seja concluída?

Sim. Cada chamada é aplicada sobre o estado otimista anterior.
Certifique-se de que sua updateFn seja composível - cada chamada deve produzir um resultado válido quando empilhada.
Todas as sobreposições otimistas são descartadas quando a ação é concluída.

Como mostro um toast de erro quando uma atualização otimista reverte?

Não há um callback integrado para detecção de rollback.
Trate os erros na sua função de ação e atualize o estado real com uma mensagem de erro.
Compare o estado real antes e depois da ação para detectar um rollback na interface do usuário.

Como eu digito useOptimistic com TypeScript?

const [optimistic, add] = useOptimistic(
  messages,                         // T = Message[]
  (state, text: string) => [        // V = string
    ...state,
    { id: Date.now(), text, sending: true },
  ]
);
// add: (value: string) => void
// optimistic: Message[]

Armadilha: O que acontece se o estado real mudar de outra fonte enquanto uma ação está pendente?

A sobreposição otimista recalcula sobre o novo estado real.
Este é geralmente o comportamento correto - a sobreposição se adapta à realidade mais recente.
Esteja ciente disso ao depurar valores otimistas inesperados.

Posso usar useOptimistic para um simples alternador de curtir/descurtir?

const [optimisticLikes, addLike] = useOptimistic(
  likes,
  (current, _: null) => current + 1
);
 
async function handleLike() {
  startTransition(async () => {
    addLike(null);
    await likePost(postId);
  });
}

Sim. O valor otimista é mostrado imediatamente; a contagem real é atualizada quando o servidor responde.

Quando devo usar useOptimistic em vez de apenas mostrar um spinner com isPending?

Use useOptimistic quando os usuários esperam feedback instantâneo (mensagens, curtidas, alternâncias).
Use um spinner quando o resultado for incerto e mostrar um estado previsto puder ser enganoso.
Para ações de baixa latência, um spinner é bom; para ações de alta latência, a UI otimista parece muito mais rápida.

Relacionados

useActionState - gerencia o estado do formulário que impulsiona atualizações otimistas
useTransition - transições alimentam o estado pendente do qual as atualizações otimistas dependem
use - primitivo do React 19 para consumir valores assíncronos
useState - o estado subjacente que useOptimistic sobrepõe

Hook useOptimistic

Buscar na documentação

Hook useOptimistic