Busque em todas as páginas da documentação
🤖 Read the SystemsArchitect.io Blog for over 100+ cloud architecture articles 🔥
import { use, Suspense } from "react";
// Lendo uma promise -- deve ser envolvida em Suspense
function UserProfile({ userPromise }: { userPromise: Promise<{ name: string; email: string }> }) {
const user = use(userPromise);
return (
<div>
<h2>{user.name}</h2>
<p>{user.email}</p>
</div>
);
}
// Lendo contexto -- substitui useContext
const ThemeContext = React.createContext<"light" | "dark">("light");
function ThemedButton() {
const theme = use(ThemeContext);
return <button className={theme === "dark" ? "bg-gray-800 text-white" : "bg-white"}>Clique em mim</button>;
}
// Uso
function App() {
const userPromise = fetchUser(1); // crie a promise fora da renderização, ou em um Server Component
return (
<ThemeContext value="dark">
<Suspense fallback={<p>Carregando usuário...</p>}>
<UserProfile userPromise={userPromise} />
</Suspense>
<ThemedButton />
</ThemeContext>
);
}Quando usar isso: Use use() para ler uma promise passada de um Server Component ou componente pai, ou para ler condicionalmente o contexto em branches onde useContext não pode ser chamado.
// Um dashboard que carrega condicionalmente dados diferentes com base na função do usuário
"use client";
import { use, Suspense, createContext } from "react";
type User = { id: string; name: string; role: "admin" | "viewer" };
type Stats = { revenue: number; users: number; orders: number };
type Activity = { id: string; description: string; timestamp: string };
const AuthContext = createContext<User | null>(null);
function DashboardContent({
statsPromise,
activityPromise,
}: {
statsPromise: Promise<Stats>;
activityPromise: Promise<Activity[]>;
}) {
const user = use(AuthContext);
if (!user) {
return <p>Por favor, faça login.</p>;
}
// use() pode ser chamado condicionalmente -- isso é único entre os hooks do React
if (user.role === "admin") {
const stats = use(statsPromise);
return (
<div>
<h2>Dashboard de Admin</h2>
<dl>
<dt>Receita</dt><dd>${stats.revenue.toLocaleString()}</dd>
<dt>Usuários</dt><dd>{stats.users.toLocaleString()}</dd>
<dt>Pedidos</dt><dd>{stats.orders.toLocaleString()}</dd>
</dl>
</div>
);
}
const activity = use(activityPromise);
return (
<div>
<h2>Feed de Atividades</h2>
<ul>
{activity.map((a) => (
<li key={a.id}>
{a.description} <time>{a.timestamp}</time>
</li>
))}
</ul>
</div>
);
}
export default function Dashboard({
user,
statsPromise,
activityPromise,
}: {
user: User | null;
statsPromise: Promise<Stats>;
activityPromise: Promise<Activity[]>;
}) {
return (
<AuthContext value={user}>
<Suspense fallback={<p>Carregando dashboard...</p>}>
<DashboardContent
statsPromise={statsPromise}
activityPromise={activityPromise}
/>
</Suspense>
</AuthContext>
);
}O que isso demonstra:
use(AuthContext) lendo contexto sem useContextuse(promise) chamado condicionalmente dentro de um bloco if -- impossível com hooks tradicionaisuse() não é um hook no sentido tradicional. Ele não segue as "regras dos hooks" -- você pode chamá-lo dentro de loops, condicionais e retornos antecipados. É isso que o diferencia de useContext.use() suspende o componente até que a promise resolva. A fronteira <Suspense> mais próxima mostra o fallback. Se a promise rejeitar, a fronteira de erro mais próxima captura o erro.use() se comporta de forma idêntica a useContext() -- ele lê o valor atual do provedor mais próximo na árvore.use() deve ser estável -- não crie uma nova promise a cada renderização. Promises devem vir de Server Components, ser armazenadas em cache ou criadas fora da função de renderização.use() se integra com os recursos concorrentes do React. Enquanto uma promise está pendente, o React pode continuar renderizando outras partes da árvore.Server Component passando uma promise para um Client Component:
// app/page.tsx (Server Component)
import UserCard from "./UserCard";
export default function Page() {
// Inicia o fetch mas NÃO aguarda -- deixe o cliente resolvê-lo
const userPromise = fetchUser(1);
return <UserCard userPromise={userPromise} />;
}// app/UserCard.tsx
"use client";
import { use } from "react";
export default function UserCard({ userPromise }: { userPromise: Promise<{ name: string }> }) {
const user = use(userPromise);
return <h2>{user.name}</h2>;
}Leitura condicional de contexto:
import { use, createContext } from "react";
const FeatureFlagContext = createContext<Set<string>>(new Set());
function FeatureGate({ flag, children }: { flag: string; children: React.ReactNode }) {
const flags = use(FeatureFlagContext);
if (!flags.has(flag)) return null;
return <>{children}</>;
}Encadeamento de promises:
function OrderDetails({ orderPromise }: { orderPromise: Promise<{ id: string; userId: string }> }) {
const order = use(orderPromise);
// Você pode usar o valor resolvido para criar outra promise
// mas armazene em cache para evitar recriar a cada renderização
const userPromise = useMemo(() => fetchUser(order.userId), [order.userId]);
const user = use(userPromise);
return (
<div>
<p>Pedido #{order.id}</p>
<p>Cliente: {user.name}</p>
</div>
);
}use<T>(promise: Promise<T>): T -- O tipo resolvido é inferido da promise.use<T>(context: React.Context<T>): T -- O tipo do valor do contexto é inferido.userPromise: Promise<User>.use() é importado de "react": import { use } from "react".fetch() ou new Promise() dentro do corpo do componente cria uma nova promise a cada renderização, causando loops de suspense infinitos. Correção: Crie a promise em um Server Component, componente pai, ou use useMemo/cache para estabilizá-la.<Suspense> quando use() lê uma promise, o React lança um erro. Correção: Envolva o componente (ou um ancestral) em <Suspense fallback={...}>.use() com promises.Promise e Context são suportados. Observables, geradores e outros iteráveis assíncronos não são. Correção: Converta outras fontes assíncronas em promises antes de passá-las para use().use(MyContext), observe que <MyContext.Provider> ainda funciona, mas a sintaxe preferida é <MyContext value={v}>. Correção: Migre para a sintaxe mais curta.use() não armazena em cache, desduplica ou revalida. Ele lê uma única promise. Correção: Combine com uma camada de cache (React cache(), cache em nível de framework, ou uma biblioteca como SWR/TanStack Query).| Abordagem | Quando escolher |
|---|---|
use(promise) | Lendo uma promise de um Server Component ou fonte em cache |
useContext(ctx) | Leitura tradicional de contexto (ainda funciona, mas não pode ser chamada condicionalmente) |
use(context) | Leitura condicional de contexto em branches |
| TanStack Query / SWR | Busca de dados completa com cache, revalidação, paginação |
useEffect + useState | Padrão legado de fetch-on-mount (ainda funciona, mas menos ergonômico) |
React.lazy | Code-splitting de componentes (caso de uso diferente de promises de dados) |
use() pode ser chamado dentro de loops, condicionais e retornos antecipados -- ele não segue as "regras dos hooks"useContext só funciona com Contextuse() é o substituto preferido para useContext() daqui para frente<Suspense> quando use() lê uma promise pendente<Suspense fallback={...}>Sim. Esta é a principal diferença em relação a outros hooks:
function Dashboard({ user, statsPromise, activityPromise }) {
if (user.role === "admin") {
const stats = use(statsPromise);
return <AdminView stats={stats} />;
}
const activity = use(activityPromise);
return <ActivityFeed activity={activity} />;
}fetch() ou new Promise() dentro do corpo do componente cria uma nova promise a cada renderizaçãouseMemo/cache// Server Component -- NÃO aguarde
export default function Page() {
const userPromise = fetchUser(1);
return <UserCard userPromise={userPromise} />;
}
// Client Component
"use client";
import { use } from "react";
export default function UserCard({ userPromise }) {
const user = use(userPromise);
return <h2>{user.name}</h2>;
}use() não armazena em cache, desduplica ou revalida dadoscache(), cache do framework, ou uma biblioteca) para necessidades de busca de dados em produçãofunction OrderDetails({ orderPromise }) {
const order = use(orderPromise);
const userPromise = useMemo(
() => fetchUser(order.userId),
[order.userId]
);
const user = use(userPromise);
return <p>Pedido #{order.id} por {user.name}</p>;
}Use useMemo para estabilizar a promise dependente e evitar recriação a cada renderização.
<MyContext.Provider value={v}> está obsoleto<MyContext value={v}> diretamente como o JSX do provedoruse(MyContext) quanto useContext(MyContext) leem de qualquer sintaxePromise e React.Context são suportadosuse()// Promise -- tipo resolvido inferido
const user: User = use<User>(userPromise);
// Contexto -- tipo de valor inferido
const theme: "light" | "dark" = use(ThemeContext);Importe de "react": import { use } from "react".
type Props = {
dataPromise: Promise<{ id: string; name: string }>;
};
function MyComponent({ dataPromise }: Props) {
const data = use(dataPromise);
return <p>{data.name}</p>;
}Revisado por Chris St. John·Última atualização: 16 de jul. de 2026
🤖 Read the SystemsArchitect.io Blog for over 100+ cloud architecture articles 🔥