Hook use

Lee el valor de una promesa o contexto durante el renderizado — la nueva primitiva de React 19 para datos asíncronos y contexto condicional.

Receta

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

// Lee una promesa (se suspende hasta que se resuelva)
const data = use(dataPromise);
 
// Lee contexto (funciona en condiciones y bucles — a diferencia de useContext)
if (showTheme) {
  const theme = use(ThemeContext);
}

Cuándo usarlo: Tienes una promesa creada fuera del componente (pasada como prop o desde una caché) y quieres leer su valor con Suspense, o necesitas leer contexto condicionalmente.

Ejemplo en funcionamiento

"use client";
 
import { Suspense, use, useState } from "react";
 
interface User {
  id: number;
  name: string;
  email: string;
}
 
function fetchUser(id: number): Promise<User> {
  return fetch(`https://jsonplaceholder.typicode.com/users/${id}`).then((res) =>
    res.json()
  );
}
 
function UserProfile({ userPromise }: { userPromise: Promise<User> }) {
  const user = use(userPromise);
 
  return (
    <div className="border rounded p-4">
      <h3 className="font-semibold">{user.name}</h3>
      <p className="text-sm text-gray-600">{user.email}</p>
    </div>
  );
}
 
export function UserLoader() {
  const [userId, setUserId] = useState(1);
  const [userPromise, setUserPromise] = useState(() => fetchUser(1));
 
  function handleLoadUser(id: number) {
    setUserId(id);
    setUserPromise(fetchUser(id));
  }
 
  return (
    <div className="space-y-3">
      <div className="flex gap-2">
        {[1, 2, 3].map((id) => (
          <button
            key={id}
            onClick={() => handleLoadUser(id)}
            className={`px-3 py-1 border rounded ${
              userId === id ? "bg-blue-600 text-white" : ""
            }`}
          >
            User {id}
          </button>
        ))}
      </div>
 
      <Suspense fallback={<p className="text-sm text-gray-500">Cargando usuario...</p>}>
        <UserProfile userPromise={userPromise} />
      </Suspense>
    </div>
  );
}

Lo que esto demuestra:

• use(userPromise) suspende UserProfile hasta que la promesa se resuelva
• El límite de Suspense muestra un fallback mientras la promesa está pendiente
• Crear una nueva promesa (a través de setUserPromise) activa una nueva suspensión
• La promesa se crea en el padre y se pasa como prop — no se crea durante el renderizado

Análisis profundo

Cómo funciona

• use puede leer dos tipos de valores: Promesas y Contextos de React
• Para promesas: use suspende el componente hasta que la promesa se resuelva, luego devuelve el valor resuelto. Si la promesa se rechaza, lanza hacia el límite de error más cercano
• Para contexto: use lee el valor del proveedor más cercano, al igual que useContext, pero a diferencia de useContext, puede llamarse dentro de condiciones, bucles y retornos tempranos
• use no es técnicamente un hook — no sigue las "reglas de hooks" respecto a llamadas condicionales. Sin embargo, solo puede llamarse durante el renderizado (no en manejadores de eventos o efectos)
• La promesa debe crearse fuera del componente de renderizado o estar en caché — crear una nueva promesa en cada renderizado causa suspensión infinita

Parámetros y valores de retorno

Variaciones

Lectura de contexto condicional:

function Toolbar({ isLoggedIn }: { isLoggedIn: boolean }) {
  if (isLoggedIn) {
    const user = use(UserContext); // Esto está permitido — a diferencia de useContext
    return <p>Bienvenida, {user.name}</p>;
  }
  return <p>Por favor inicia sesión</p>;
}

Leyendo una promesa en caché (patrón común):

// Guarda la promesa en caché para que no se recree en cada renderizado
const cache = new Map<string, Promise<Data>>();
 
function getData(key: string): Promise<Data> {
  if (!cache.has(key)) {
    cache.set(key, fetch(`/api/${key}`).then((r) => r.json()));
  }
  return cache.get(key)!;
}
 
function DataDisplay({ dataKey }: { dataKey: string }) {
  const data = use(getData(dataKey));
  return <div>{data.title}</div>;
}

Con límite de error:

<ErrorBoundary fallback={<p>Algo salió mal</p>}>
  <Suspense fallback={<Spinner />}>
    <AsyncComponent dataPromise={promise} />
  </Suspense>
</ErrorBoundary>

Componente de servidor pasando promesa a componente de cliente:

// Componente de servidor
async function Page() {
  const dataPromise = fetchData(); // No esperes — pasa la promesa
  return (
    <Suspense fallback={<Loading />}>
      <ClientComponent dataPromise={dataPromise} />
    </Suspense>
  );
}
 
// Componente de cliente
"use client";
function ClientComponent({ dataPromise }: { dataPromise: Promise<Data> }) {
  const data = use(dataPromise);
  return <div>{data.title}</div>;
}

Notas de TypeScript

// El tipo se infiere de la promesa o contexto
const user = use(userPromise);    // User (inferida de Promise<User>)
const theme = use(ThemeContext);   // Theme (inferida de Context<Theme>)
 
// Tipado explícito cuando sea necesario
const data = use<ApiResponse>(dataPromise);
 
// La reducción de tipo de contexto funciona igual que useContext
const ctx = use(MyContext);
if (!ctx) throw new Error("Missing provider");

Trampas

• Crear promesas durante el renderizado — Escribir use(fetch("/api/data")) dentro de un componente crea una nueva promesa en cada renderizado, causando suspensión infinita. Solución: Crea la promesa fuera del componente, en un padre, o en una caché.

• Sin manejo de rechazo en el componente — Si la promesa se rechaza, use lanza el error. Sin un límite de error, esto bloquea la aplicación. Solución: Siempre envuelve los componentes que consumen use en un límite de error.

• No es un hook completo — use puede llamarse condicionalmente, pero aún solo puede llamarse durante el renderizado. Llamarlo en un manejador de eventos o useEffect no funciona. Solución: Llama a use solo en el cuerpo del componente durante el renderizado.

• La identidad de la promesa importa — Si pasas un nuevo objeto de promesa (misma URL pero nueva llamada fetch), React lo trata como un nuevo recurso y re-suspende. Solución: Guarda en caché o memoriza tus promesas para que la misma solicitud lógica devuelva el mismo objeto de promesa.

• No es un reemplazo para bibliotecas de obtención de datos — use maneja la lectura de una promesa con Suspense, pero no proporciona almacenamiento en caché, deduplicación o revalidación. Solución: Usa use con una capa de almacenamiento en caché, o usa una biblioteca de obtención de datos como TanStack Query.

Alternativas

¿Cuándo usar use vs useEffect para obtener datos? Prefiere use cuando quieras transmisión basada en Suspense y la promesa se cree fuera del componente de renderizado. Usa useEffect cuando necesites control detallado sobre estados de carga/error o necesites obtener datos en función de interacciones del lado del cliente.

Preguntas frecuentes

const cache = new Map<string, Promise<Data>>();
 
function getData(key: string): Promise<Data> {
  if (!cache.has(key)) {
    cache.set(key, fetch(`/api/${key}`).then(r => r.json()));
  }
  return cache.get(key)!;
}
 
function DataDisplay({ dataKey }: { dataKey: string }) {
  const data = use(getData(dataKey)); // mismo objeto de promesa
  return <div>{data.title}</div>;
}

// El tipo se infiere de la promesa o contexto
const user = use(userPromise);    // User (de Promise<User>)
const theme = use(ThemeContext);   // Theme (de Context<Theme>)
 
// Generic explícito cuando sea necesario
const data = use<ApiResponse>(dataPromise);

// Componente de servidor
async function Page() {
  const dataPromise = fetchData(); // No esperes
  return (
    <Suspense fallback={<Loading />}>
      <ClientComponent dataPromise={dataPromise} />
    </Suspense>
  );
}
 
// Componente de cliente
"use client";
function ClientComponent({ dataPromise }: { dataPromise: Promise<Data> }) {
  const data = use(dataPromise);
  return <div>{data.title}</div>;
}

Relacionado

• useContext — lectura de contexto tradicional (no puede ser condicional)
• useActionState — acciones de formulario que producen promesas
• useTransition — envuelve actualizaciones de estado que crean nuevas promesas
• useOptimistic — muestra el estado predicho mientras las promesas se resuelven