Hook useDeferredValue

Adie o carregamento de uma parte da UI para manter o restante responsivo durante renderizações caras.

Receita

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

const deferredQuery = useDeferredValue(query);
 
// O componente que usa deferredQuery re-renderiza com menor prioridade
<SearchResults query={deferredQuery} />
 
// Detectar conteúdo desatualizado
const isStale = deferredQuery !== query;

Quando usar isso: Você tem um valor que muda rapidamente (como a entrada de pesquisa) impulsionando uma renderização cara do filho, e você quer que a entrada permaneça responsiva enquanto o filho se atualiza.

Exemplo de Funcionamento

"use client";
 
import { memo, useDeferredValue, useState } from "react";
 
const HeavyList = memo(function HeavyList({ query }: { query: string }) {
  const items = Array.from({ length: 5000 }, (_, i) => `Resultado ${i}: ${query}`);
  return (
    <ul className="max-h-64 overflow-y-auto text-sm">
      {items
        .filter((item) => item.toLowerCase().includes(query.toLowerCase()))
        .slice(0, 100)
        .map((item, i) => (
          <li key={i} className="py-0.5">{item}</li>
        ))}
    </ul>
  );
});
 
export function DeferredSearch() {
  const [query, setQuery] = useState("");
  const deferredQuery = useDeferredValue(query);
  const isStale = deferredQuery !== query;
 
  return (
    <div className="space-y-3">
      <input
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Digite para pesquisar..."
        className="border rounded px-3 py-2 w-full"
      />
      <div className={isStale ? "opacity-50 transition-opacity" : "transition-opacity"}>
        <HeavyList query={deferredQuery} />
      </div>
    </div>
  );
}

O que isso demonstra:

• query atualiza instantaneamente a cada pressionamento de tecla, mantendo a entrada responsiva
• deferredQuery fica para trás, então HeavyList re-renderiza com menor prioridade
• React.memo em HeavyList é essencial - sem ele, o componente re-renderiza com query de qualquer maneira
• Feedback visual de desatualização via opacidade quando deferredQuery !== query

Análise Detalhada

Como Funciona

• useDeferredValue aceita um valor e retorna uma cópia adiada dele
• Na renderização inicial, o valor adiado é igual ao valor original
• Quando o valor original muda, o React primeiro re-renderiza com o valor adiado antigo, depois agenda uma renderização em segundo plano com o novo valor
• A renderização em segundo plano é interrompível - se o valor original mudar novamente, o React abandona a renderização em andamento e inicia uma nova
• Isso funciona com Suspense: se o valor adiado fizer um componente suspender, o usuário verá o conteúdo antigo enquanto o novo conteúdo carrega

Parâmetros e Valores de Retorno

Variações

Adiar conteúdo do Suspense:

function App() {
  const [query, setQuery] = useState("");
  const deferredQuery = useDeferredValue(query);
 
  return (
    <>
      <SearchInput value={query} onChange={setQuery} />
      <Suspense fallback={<Skeleton />}>
        <SearchResults query={deferredQuery} />
      </Suspense>
    </>
  );
}

Valor inicial do React 19 (evitar mostrar conteúdo desatualizado na montagem):

// Mostra resultados vazios inicialmente, depois preenche em baixa prioridade
const deferredItems = useDeferredValue(items, []);

Combinando com transição para estado de carregamento:

const deferredQuery = useDeferredValue(query);
const isStale = deferredQuery !== query;
 
return (
  <div>
    {isStale && <p className="text-sm text-gray-400">Carregando...</p>}
    <Results query={deferredQuery} />
  </div>
);

Notas do TypeScript

// O tipo é inferido do valor de entrada
const deferredQuery = useDeferredValue(query); // string
 
// React 19 com initialValue
const deferredItems = useDeferredValue<Item[]>(items, []);

Armadilhas

• Esquecer React.memo - useDeferredValue só ajuda se o componente filho for memoizado. Caso contrário, o filho re-renderiza com o valor atual na primeira passagem de qualquer maneira. Correção: Envolva o filho caro com React.memo.

• Não é adequado para limitar chamadas de API - useDeferredValue adia a renderização, não a mudança de valor em si. Ele não reduz o número de chamadas de fetch. Correção: Use debounce para chamadas de API; use useDeferredValue para desempenho de renderização.

• Flash de conteúdo desatualizado - O valor adiado fica atrás do valor real, então os usuários veem conteúdo desatualizado brevemente. Correção: Mostre um indicador visual (opacidade, spinner) quando deferredValue !== value.

• Apenas valores primitivos - Passar um novo objeto ou array a cada renderização anula o propósito, pois a comparação Object.is encontra um novo valor a cada vez. Correção: Memoize objetos ou arrays com useMemo antes de passá-los para useDeferredValue.

Alternativas

useDeferredValue vs. useTransition: useTransition envolve a atualização do estado; useDeferredValue envolve o consumo do valor. Use useDeferredValue quando você não controla a atualização do estado (por exemplo, ela vem de uma prop ou de um componente pai).

FAQs

const deferredQuery = useDeferredValue(query);
const isStale = deferredQuery !== query;
 
return (
  <div className={isStale ? "opacity-50" : ""}>
    <Results query={deferredQuery} />
  </div>
);

// A primeira renderização usa [] em vez do array completo de itens
const deferredItems = useDeferredValue(items, []);

// O tipo é inferido do valor de entrada
const deferredQuery = useDeferredValue(query); // string
 
// React 19 com initialValue
const deferredItems = useDeferredValue<Item[]>(items, []);

Relacionados

• useTransition - envolva atualizações de estado em vez de adiar valores
• useMemo - memoize computações caras
• useCallback - estabilize referências para filhos memoizados
• useState - a fonte de estado que impulsiona os valores adiados