Hook use

Leia o valor de uma promise ou contexto durante a renderização - a nova primitiva do React 19 para dados assíncronos e contexto condicional.

Receita

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

// Lê uma promise (suspende até ser resolvida)
const data = use(dataPromise);
 
// Lê o contexto (funciona em condições e loops - diferente de useContext)
if (showTheme) {
  const theme = use(ThemeContext);
}

Quando usar isso: Você tem uma promise criada fora do componente (passada como prop ou de um cache) e quer ler seu valor com Suspense, ou precisa ler o contexto condicionalmente.

Exemplo de Trabalho

"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">Carregando usuário...</p>}>
        <UserProfile userPromise={userPromise} />
      </Suspense>
    </div>
  );
}

O que isso demonstra:

• use(userPromise) suspende UserProfile até que a promise seja resolvida.
• O boundary Suspense mostra um fallback enquanto a promise está pendente.
• Criar uma nova promise (via setUserPromise) dispara uma nova suspensão.
• A promise é criada no pai e passada como prop - não criada durante a renderização.

Análise Detalhada

Como Funciona

• use pode ler dois tipos de valores: Promises e Contextos do React.
• Para promises: use suspende o componente até que a promise seja resolvida, então retorna o valor resolvido. Se a promise rejeitar, ela lança para o boundary de erro mais próximo.
• Para contexto: use lê o valor do provider mais próximo, assim como useContext, mas diferente de useContext, ele pode ser chamado dentro de condições, loops e retornos antecipados.
• use não é tecnicamente um hook - ele não segue as "regras dos hooks" para chamadas condicionais. No entanto, ele só pode ser chamado durante a renderização (não em manipuladores de eventos ou efeitos).
• A promise deve ser criada fora do componente de renderização ou cacheada - criar uma nova promise a cada renderização causa suspensão infinita.

Parâmetros e Valores de Retorno

Variações

Leitura condicional de contexto:

function Toolbar({ isLoggedIn }: { isLoggedIn: boolean }) {
  if (isLoggedIn) {
    const user = use(UserContext); // Isso é permitido - diferente de useContext
    return <p>Bem-vindo, {user.name}</p>;
  }
  return <p>Por favor, faça login</p>;
}

Lendo uma promise cacheada (padrão comum):

// Cacheia a promise para que ela não seja recriada a cada renderização
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>;
}

Com boundary de erro:

<ErrorBoundary fallback={<p>Algo deu errado</p>}>
  <Suspense fallback={<Spinner />}>
    <AsyncComponent dataPromise={promise} />
  </Suspense>
</ErrorBoundary>

Componente de servidor passando promise para componente de cliente:

// Componente de Servidor
async function Page() {
  const dataPromise = fetchData(); // Não aguarde - passe a promise
  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 TypeScript

// O tipo é inferido da promise ou do contexto
const user = use(userPromise);    // User (inferido de Promise<User>)
const theme = use(ThemeContext);   // Theme (inferido de Context<Theme>)
 
// Tipagem explícita quando necessário
const data = use<ApiResponse>(dataPromise);
 
// O estreitamento do tipo de contexto funciona da mesma forma que useContext
const ctx = use(MyContext);
if (!ctx) throw new Error("Provedor ausente");

Armadilhas

• Criar promises durante a renderização - Escrever use(fetch("/api/data")) dentro de um componente cria uma nova promise a cada renderização, causando suspensão infinita. Correção: Crie a promise fora do componente, em um pai, ou em um cache.

• Sem tratamento de rejeição no componente - Se a promise rejeitar, use lança o erro. Sem um boundary de erro, isso trava o aplicativo. Correção: Sempre envolva componentes que consomem use em um boundary de erro.

• Não é um hook completo - use pode ser chamado condicionalmente, mas ainda assim só pode ser chamado durante a renderização. Chamá-lo em um manipulador de evento ou useEffect não funciona. Correção: Chame use apenas no corpo do componente durante a renderização.

• Identidade da promise importa - Se você passar um novo objeto de promise (mesma URL, mas nova chamada fetch), o React o trata como um novo recurso e re-suspende. Correção: Cacheie ou memoize suas promises para que a mesma requisição lógica retorne o mesmo objeto de promise.

• Não é um substituto para bibliotecas de busca de dados - use lida com a leitura de uma promise com Suspense, mas não fornece cache, deduplicação ou revalidação. Correção: Use use com uma camada de cache, ou use uma biblioteca de busca de dados como TanStack Query.

Alternativas

Quando usar use vs useEffect para dados? Prefira use quando quiser streaming baseado em Suspense e a promise for criada fora do componente de renderização. Use useEffect quando precisar de controle granular sobre os estados de carregamento/erro ou precisar buscar com base em interações do cliente.

FAQs

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)); // mesmo objeto de promise
  return <div>{data.title}</div>;
}

// O tipo é inferido da promise ou do contexto
const user = use(userPromise);    // User (de Promise<User>)
const theme = use(ThemeContext);   // Theme (de Context<Theme>)
 
// Genérico explícito quando necessário
const data = use<ApiResponse>(dataPromise);

// Componente de Servidor
async function Page() {
  const dataPromise = fetchData(); // Não aguarde
  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>;
}

Relacionados

• useContext - leitura tradicional de contexto (não pode ser condicional)
• useActionState - ações de formulário que produzem promises
• useTransition - envolve atualizações de estado que criam novas promises
• useOptimistic - mostra o estado previsto enquanto as promises são resolvidas