Hook useDeferredValue

Diferir la actualización de una parte de la interfaz para mantener el resto responsivo durante renders costosos.

Receta

Tarjeta de referencia rápida — lista para copiar y pegar.

const deferredQuery = useDeferredValue(query);
 
// El componente que usa deferredQuery se re-renderiza con menor prioridad
<SearchResults query={deferredQuery} />
 
// Detectar contenido obsoleto
const isStale = deferredQuery !== query;

Cuándo usarlo: Tienes un value que cambia rápidamente (como entrada de búsqueda) impulsando un render hijo costoso, y quieres que la entrada permanezca receptiva mientras el hijo se pone al día.

Ejemplo en Funcionamiento

"use client";
 
import { memo, useDeferredValue, useState } from "react";
 
const HeavyList = memo(function HeavyList({ query }: { query: string }) {
  const items = Array.from({ length: 5000 }, (_, i) => `Result ${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="Escribe para buscar..."
        className="border rounded px-3 py-2 w-full"
      />
      <div className={isStale ? "opacity-50 transition-opacity" : "transition-opacity"}>
        <HeavyList query={deferredQuery} />
      </div>
    </div>
  );
}

Lo que esto demuestra:

• query se actualiza instantáneamente en cada pulsación de tecla, manteniendo la entrada receptiva
• deferredQuery se retrasa, por lo que HeavyList se re-renderiza con menor prioridad
• React.memo en HeavyList es esencial — sin él, el componente se re-renderiza con query de todas formas
• Retroalimentación de obsolescencia visual mediante opacidad cuando deferredQuery !== query

Profundización

Cómo Funciona

• useDeferredValue acepta un value y devuelve una copia diferida del mismo
• En el renderizado inicial, el value diferido es igual al value original
• Cuando el value original cambia, React primero re-renderiza con el value diferido antiguo, luego programa un re-renderizado de fondo con el nuevo value
• El re-renderizado de fondo es interrumpible — si el value original cambia nuevamente, React abandona el renderizado en curso y comienza uno nuevo
• Esto funciona con Suspense: si el value diferido hace que un componente se suspenda, el usuario ve el contenido antiguo mientras se carga el contenido nuevo

Parámetros y Valores de Retorno

Variaciones

Diferir contenido de Suspense:

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

React 19 initialValue (evitar mostrar contenido obsoleto al montar):

// Mostrar resultados vacíos inicialmente, luego llenar con baja prioridad
const deferredItems = useDeferredValue(items, []);

Combinando con transition para estado de carga:

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

Notas de TypeScript

// El tipo se infiere del value de entrada
const deferredQuery = useDeferredValue(query); // string
 
// React 19 con initialValue
const deferredItems = useDeferredValue<Item[]>(items, []);

Gotchas

• Olvidar React.memo — useDeferredValue solo ayuda si el componente hijo está memoizado. De lo contrario, el hijo se re-renderiza con el value actual en el primer paso de todas formas. Solución: Envuelve el hijo costoso en React.memo.

• No apto para limitar llamadas API — useDeferredValue diferir el renderizado, no el cambio del value en sí. No reduce el número de llamadas fetch. Solución: Usa debounce para llamadas API; usa useDeferredValue para rendimiento de renderizado.

• Flash de contenido obsoleto — El value diferido se retrasa detrás del value real, así que los usuarios ven contenido obsoleto brevemente. Solución: Muestra un indicador visual (opacidad, spinner) cuando deferredValue !== value.

• Solo valores primitivos — Pasar un nuevo objeto o array en cada renderizado anula el propósito, porque la comparación Object.is encuentra un nuevo value cada vez. Solución: Memoiza objetos o arrays con useMemo antes de pasarlos a useDeferredValue.

Alternativas

useDeferredValue vs. useTransition: useTransition envuelve la actualización de estado; useDeferredValue envuelve el consumo del value. Usa useDeferredValue cuando no controlas la actualización de estado (por ejemplo, viene de una prop o padre).

Preguntas Frecuentes

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

// El primer renderizado usa [] en lugar del array de items completo
const deferredItems = useDeferredValue(items, []);

// El tipo se infiere del value de entrada
const deferredQuery = useDeferredValue(query); // string
 
// React 19 con initialValue
const deferredItems = useDeferredValue<Item[]>(items, []);

Relacionado

• useTransition — envuelve actualizaciones de estado en lugar de diferir values
• useMemo — memoiza computaciones costosas
• useCallback — estabilizar referencias para hijos memoizados
• useState — la fuente de estado impulsando values diferidos