Hook useTransition

Marque atualizações de estado como não urgentes para que não bloqueiem a entrada do usuário.

Receita

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

const [isPending, startTransition] = useTransition();
 
// Envolva uma atualização de estado lenta
startTransition(() => {
  setSearchResults(filterLargeList(query));
});
 
// Mostre o estado pendente
{isPending && <Spinner />}

Quando usar isso: Uma atualização de estado causa re-renderização cara (filtrar uma lista grande, alternar abas com conteúdo pesado) e você quer que a UI permaneça responsiva durante a atualização.

Exemplo de Trabalho

"use client";
 
import { useState, useTransition } from "react";
 
const ALL_ITEMS = Array.from({ length: 10000 }, (_, i) => ({
  id: i,
  name: `Item ${i}`,
  category: ["Electronics", "Books", "Clothing", "Food"][i % 4],
}));
 
export function FilterableList() {
  const [query, setQuery] = useState("");
  const [filtered, setFiltered] = useState(ALL_ITEMS);
  const [isPending, startTransition] = useTransition();
 
  function handleChange(e: React.ChangeEvent<HTMLInputElement>) {
    const value = e.target.value;
    setQuery(value); // Urgente: atualize o input imediatamente
 
    startTransition(() => {
      // Não urgente: filtre a lista grande
      setFiltered(
        ALL_ITEMS.filter((item) =>
          item.name.toLowerCase().includes(value.toLowerCase())
        )
      );
    });
  }
 
  return (
    <div className="space-y-3">
      <input
        value={query}
        onChange={handleChange}
        placeholder="Pesquisar 10.000 itens..."
        className="border rounded px-3 py-2 w-full"
      />
      {isPending && <p className="text-sm text-gray-500">Atualizando...</p>}
      <ul className="max-h-64 overflow-y-auto text-sm">
        {filtered.slice(0, 100).map((item) => (
          <li key={item.id} className="py-0.5">
            {item.name} - {item.category}
          </li>
        ))}
      </ul>
      <p className="text-xs text-gray-400">{filtered.length} resultados</p>
    </div>
  );
}

O que isso demonstra:

• Digitar no input é instantâneo porque setQuery está fora de startTransition
• A filtragem cara é executada em uma transição, então o React pode interrompê-la se o usuário digitar novamente
• isPending mostra um indicador de carregamento enquanto a transição está em andamento
• A UI nunca trava, mesmo com 10.000 itens

Análise Detalhada

Como Funciona

• startTransition informa ao React que a atualização de estado interna é não urgente.
• O React começa a renderizar o novo estado, mas pode interrompê-lo se atualizações de maior prioridade chegarem (como digitar).
• Enquanto a transição está pendente, isPending é true, permitindo que você mostre um indicador de carregamento.
• Transições se integram com Suspense - se um componente dentro da transição suspender, o React mostrará o conteúdo antigo em vez de um fallback.
• No React 19, startTransition também pode lidar com funções assíncronas, tornando-o útil para server actions.

Parâmetros e Valores de Retorno

Variações

Alternância de abas com Suspense:

const [tab, setTab] = useState("home");
const [isPending, startTransition] = useTransition();
 
function selectTab(nextTab: string) {
  startTransition(() => {
    setTab(nextTab);
  });
}
 
return (
  <div>
    <nav className={isPending ? "opacity-50" : ""}>
      <button onClick={() => selectTab("home")}>Home</button>
      <button onClick={() => selectTab("posts")}>Posts</button>
    </nav>
    <Suspense fallback={<Spinner />}>
      {tab === "home" ? <Home /> : <Posts />}
    </Suspense>
  </div>
);

Transições assíncronas do React 19 com server actions:

const [isPending, startTransition] = useTransition();
 
function handleSubmit() {
  startTransition(async () => {
    const result = await saveToServer(formData);
    setData(result); // Atualizações da UI após a resposta do servidor
  });
}

Notas de TypeScript

// isPending é sempre booleano, startTransition aceita () => void
const [isPending, startTransition] = useTransition();
 
// React 19: startTransition também aceita funções assíncronas
startTransition(async () => {
  await serverAction();
});

Armadilhas

• Envolver atualizações síncronas baratas - Usar startTransition para um simples setCount(count + 1) adiciona sobrecarga sem benefício. Correção: Use transições apenas para atualizações que causam re-renderizações caras.

• Não separar o urgente do não urgente - Envolver tanto o estado do input quanto o estado do filtro em startTransition atrasa o input também. Correção: Mantenha atualizações urgentes (valor do input) fora de startTransition.

• isPending permanece true por muito tempo - Se a transição causar a suspensão de um limite do Suspense, isPending permanecerá true até que o conteúdo suspenso seja resolvido. Correção: Este é o comportamento esperado; projete seus estados de carregamento de acordo.

• startTransition deve ser síncrono (React 18) - No React 18, o callback deve chamar setState de forma síncrona, não dentro de um setTimeout ou após um await. Correção: No React 18, acione a atualização de estado de forma síncrona. No React 19, callbacks assíncronos são suportados.

• Não é possível envolver estado não-React - Transições funcionam apenas com atualizações de estado do React (useState, useReducer). Atualizar um ref ou store externo dentro de startTransition não tem efeito. Correção: Certifique-se de que a atualização de estado seja um setter de estado do React.

Alternativas

Transições vs. debouncing: Debouncing atrasa a atualização inteiramente. Transições permitem que o React comece a renderizar imediatamente, mas interrompe se algo mais urgente chegar. Transições mantêm a UI antiga visível enquanto renderizam a nova.

FAQs

const [isPending, startTransition] = useTransition();
// isPending: boolean
// startTransition: (callback: () => void) => void
 
// React 19 também aceita assíncrono:
// startTransition: (callback: () => void | Promise<void>) => void

Relacionados

• useDeferredValue - adia um valor em vez de envolver uma atualização
• useState - atualizações de estado envolvidas por transições
• useActionState - ações de formulário do React 19 usam transições internamente
• useOptimistic - mostra estado otimista durante transições