Hook useTransition

Marca actualizaciones de estado como no urgentes para que no bloqueen la entrada del usuario.

Receta

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

const [isPending, startTransition] = useTransition();
 
// Envuelve una actualización de estado lenta
startTransition(() => {
  setSearchResults(filterLargeList(query));
});
 
// Muestra el estado pendiente
{isPending && <Spinner />}

Cuándo usarlo: Una actualización de estado provoca un re-renderizado costoso (filtrar una lista grande, cambiar de pestañas con contenido pesado) y quieres que la interfaz se mantenga responsiva durante la actualización.

Ejemplo en funcionamiento

"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: actualiza la entrada inmediatamente
 
    startTransition(() => {
      // No urgente: filtra la 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="Busca entre 10,000 elementos..."
        className="border rounded px-3 py-2 w-full"
      />
      {isPending && <p className="text-sm text-gray-500">Actualizando...</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>
  );
}

Lo que demuestra esto:

• Escribir en la entrada es instantáneo porque setQuery está fuera de startTransition
• El filtrado costoso se ejecuta en una transición, para que React pueda interrumpirlo si el usuario vuelve a escribir
• isPending muestra un indicador de carga mientras la transición está en progreso
• La interfaz nunca se congela, ni siquiera con 10,000 elementos

Exploración profunda

Cómo funciona

• startTransition le dice a React que la actualización de estado dentro es no urgente
• React comienza a renderizar el nuevo estado pero puede interrumpirlo si llegan actualizaciones de mayor prioridad (como escribir)
• Mientras la transición está pendiente, isPending es true, permitiéndote mostrar un indicador de carga
• Las transiciones se integran con Suspense - si un componente dentro de la transición se suspende, React muestra el contenido anterior en lugar de un fallback
• En React 19, startTransition también puede manejar funciones asincronadas, haciendo que sea útil para acciones del servidor

Parámetros y valores de retorno

Variaciones

Cambio de pestañas con 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")}>Inicio</button>
      <button onClick={() => selectTab("posts")}>Publicaciones</button>
    </nav>
    <Suspense fallback={<Spinner />}>
      {tab === "home" ? <Home /> : <Posts />}
    </Suspense>
  </div>
);

Transiciones asincronadas de React 19 con acciones del servidor:

const [isPending, startTransition] = useTransition();
 
function handleSubmit() {
  startTransition(async () => {
    const result = await saveToServer(formData);
    setData(result); // La interfaz se actualiza después de que el servidor responde
  });
}

Notas de TypeScript

// isPending es siempre boolean, startTransition acepta () => void
const [isPending, startTransition] = useTransition();
 
// React 19: startTransition también acepta funciones asincronadas
startTransition(async () => {
  await serverAction();
});

Escollos

• Envolver actualizaciones sincronadas baratas - Usar startTransition para un simple setCount(count + 1) añade sobrecarga sin beneficio. Solución: Solo usa transiciones para actualizaciones que provoquen re-renderizados costosos.

• No separar actualizaciones urgentes de no urgentes - Envolver tanto el estado de la entrada como el estado del filtro en startTransition retrasa la entrada también. Solución: Mantén actualizaciones urgentes (valor de entrada) fuera de startTransition.

• isPending se queda true demasiado tiempo - Si la transición provoca que un límite de Suspense se suspenda, isPending permanece true hasta que el contenido suspendido se resuelva. Solución: Este es el comportamiento esperado; diseña tus estados de carga en consecuencia.

• startTransition debe ser sincronizado (React 18) - En React 18, el callback debe llamar a setState sincronamente, no dentro de un setTimeout o después de un await. Solución: En React 18, dispara la actualización de estado sincronamente. En React 19, los callbacks asincronos son soportados.

• No se puede envolver estado no-React - Las transiciones solo funcionan con actualizaciones de estado de React (useState, useReducer). Actualizar una ref o un store externo dentro de startTransition no tiene efecto. Solución: Asegúrate de que la actualización de estado es un setter de estado de React.

Alternativas

Transiciones vs. debouncing: Debouncing retrasa la actualización completamente. Las transiciones dejan que React comience a renderizar inmediatamente pero interrumpen si algo más urgente llega. Las transiciones mantienen la interfaz anterior visible mientras se renderiza la nueva.

Preguntas frecuentes

const [isPending, startTransition] = useTransition();
// isPending: boolean
// startTransition: (callback: () => void) => void
 
// React 19 también acepta asincronado:
// startTransition: (callback: () => void | Promise<void>) => void

Relacionado

• useDeferredValue - difiere un valor en lugar de envolver una actualización
• useState - actualizaciones de estado envueltas por transiciones
• useActionState - las acciones de formulario de React 19 usan transiciones internamente
• useOptimistic - muestra estado optimista durante transiciones