Noções Básicas de Hooks do React

11 exemplos para você começar com os Hooks do React -- 7 básicos e 4 intermediários.

Pré-requisitos

Os Hooks vêm com o próprio React -- nenhuma dependência extra é necessária. Um projeto React com TypeScript (Next.js, Vite ou CRA) é suficiente para executar todos os exemplos abaixo.

# If you do not already have a project:
npx create-next-app@latest my-app --typescript --tailwind --app
cd my-app
npm run dev

Duas regras se aplicam a todos os hooks nesta página:

1. Chame hooks apenas no nível superior de um componente ou de outro hook -- nunca dentro de loops, condições ou funções aninhadas.
2. Chame hooks apenas de componentes de função React ou hooks customizados, nunca de funções JavaScript regulares.

Exemplos Básicos

1. useState

Armazene um valor que aciona uma re-renderização sempre que ele muda.

import { useState } from "react";
 
function Counter() {
  const [count, setCount] = useState(0);
 
  return (
    <button onClick={() => setCount((c) => c + 1)}>
      Count: {count}
    </button>
  );
}

• useState retorna um par [valor, setter].
• Chamar o setter agenda uma re-renderização com o novo valor.
• Use o formulário atualizador ((c) => c + 1) quando o novo valor depender do anterior -- ele evita closures obsoletos.
• O argumento para useState(0) é o valor inicial, usado apenas na primeira renderização.

Relacionado: useState -- funções atualizadoras, inicialização preguiçosa, batching | Tipando Estado -- tipando formas complexas de estado

2. useEffect

Execute um efeito colateral após a renderização -- assinando, agendando ou tocando APIs não-React.

import { useEffect, useState } from "react";
 
function Clock() {
  const [now, setNow] = useState(() => new Date());
 
  useEffect(() => {
    const id = setInterval(() => setNow(new Date()), 1000);
    return () => clearInterval(id);
  }, []);
 
  return <p>{now.toLocaleTimeString()}</p>;
}

• O efeito é executado após o DOM ser pintado, não durante a renderização.
• Retorne uma função de limpeza para desmontar assinaturas, timers ou listeners.
• O array de dependências [] significa "executar uma vez ao montar"; listar variáveis significa "re-executar quando qualquer uma delas mudar".
• Não use useEffect para dados que você pode buscar em um Server Component -- isso causa waterfalls e flicker de carregamento.

Relacionado: useEffect -- limpeza, arrays de dependências, erros comuns | Busca Básica com SWR -- prefira isso para dados do lado do cliente

3. useRef

Mantenha um valor entre renderizações sem acionar uma re-renderização, ou referencie um nó DOM.

import { useEffect, useRef } from "react";
 
function AutoFocusInput() {
  const inputRef = useRef<HTMLInputElement>(null);
 
  useEffect(() => {
    inputRef.current?.focus();
  }, []);
 
  return <input ref={inputRef} placeholder="Auto-focused" />;
}

• useRef retorna um objeto { current } que persiste entre renderizações.
• Mutar ref.current não aciona uma re-renderização -- ao contrário do estado.
• Passe a ref para a prop ref para obter um handle para o elemento DOM subjacente.
• Usos típicos: acesso DOM, IDs de timer que você precisa limpar, armazenando o último valor de uma prop ou callback.

Relacionado: useRef -- padrões de ref, encaminhamento, refs de callback | Tipando Refs -- tipos de ref para elementos e instâncias

4. useContext

Leia um valor de contexto em qualquer lugar da árvore sem prop drilling.

import { createContext, useContext } from "react";
 
const ThemeContext = createContext<"light" | "dark">("light");
 
function ThemedLabel() {
  const theme = useContext(ThemeContext);
  return (
    <span className={theme === "dark" ? "text-white" : "text-black"}>Hi</span>
  );
}
 
function App() {
  return (
    <ThemeContext.Provider value="dark">
      <ThemedLabel />
    </ThemeContext.Provider>
  );
}

• Cada chamada para useContext assina o componente ao contexto -- ele re-renderiza sempre que o value do provider muda.
• O valor padrão ("light" aqui) é usado apenas quando não há um provider correspondente acima na árvore.
• Para estado frequentemente atualizado, um store dedicado evita re-renderizar todos os consumidores.

Relacionado: useContext -- providers, valores padrão, divisão de contextos | Padrões de Contexto -- quando e como dividir contextos | Contexto vs. Zustand -- escolhendo entre eles

5. useReducer

Gerencie transições de estado complexas com atualizações baseadas em ações.

import { useReducer } from "react";
 
type Action = { type: "increment" } | { type: "decrement" } | { type: "reset" };
 
function reducer(state: number, action: Action): number {
  switch (action.type) {
    case "increment":
      return state + 1;
    case "decrement":
      return state - 1;
    case "reset":
      return 0;
  }
}
 
function Counter() {
  const [count, dispatch] = useReducer(reducer, 0);
  return (
    <div>
      <button onClick={() => dispatch({ type: "decrement" })}>-</button>
      <span>{count}</span>
      <button onClick={() => dispatch({ type: "increment" })}>+</button>
    </div>
  );
}

• Use useReducer quando o estado tiver múltiplos campos relacionados ou transições complexas que abrangeriam muitas chamadas useState.
• O reducer é uma função pura -- mesma entrada, mesma saída, sem efeitos colaterais.
• Tipar ações como uma união discriminada permite que o TypeScript capture chamadas dispatch inválidas.
• Se você estiver usando mais de 3-4 chamadas useState em um componente, considere useReducer em vez disso.

Relacionado: useReducer -- padrões de ação, inicialização preguiçosa, estado aninhado | Uniões Discriminadas -- formas de ação type-safe

6. useMemo

Memorize um cálculo caro para que ele só re-execute quando suas entradas mudarem.

import { useMemo, useState } from "react";
 
function ProductList({ products }: { products: { id: number; price: number }[] }) {
  const [filter, setFilter] = useState("");
 
  const total = useMemo(
    () => products.reduce((sum, p) => sum + p.price, 0),
    [products]
  );
 
  return (
    <div>
      <input value={filter} onChange={(e) => setFilter(e.target.value)} />
      <p>Total: ${total}</p>
    </div>
  );
}

• useMemo recalcula o valor apenas quando as dependências mudam, pulando trabalho em re-renderizações não relacionadas.
• Use-o para cálculos caros ou para manter a identidade referencial estável para props passadas para filhos memorizados.
• Não envolva todos os valores -- useMemo prematuro adiciona sobrecarga de código sem ganho de performance.
• Com o Compilador React (React 19+), muitas chamadas useMemo se tornam desnecessárias -- o compilador memoriza automaticamente.

Relacionado: useMemo -- quando a memorização realmente ajuda | Compilador React -- auto-memorização no React 19 | Memorização -- padrões de performance mais amplos

7. useCallback

Memorize uma referência de função para que ela permaneça estável entre renderizações.

import { useCallback, useState } from "react";
 
function SearchBox({ onSearch }: { onSearch: (q: string) => void }) {
  return <input onChange={(e) => onSearch(e.target.value)} />;
}
 
function App() {
  const [query, setQuery] = useState("");
 
  const handleSearch = useCallback((q: string) => {
    setQuery(q);
  }, []);
 
  return (
    <>
      <SearchBox onSearch={handleSearch} />
      <p>Query: {query}</p>
    </>
  );
}

• useCallback(fn, deps) é equivalente a useMemo(() => fn, deps).
• Útil ao passar um callback para um filho memorizado (React.memo) ou listá-lo como dependência em useEffect.
• Sem memorização, cada re-renderização cria uma nova referência de função e invalida filhos e efeitos.
• Assim como useMemo, evite uso prematuro -- o Compilador React lida com a maioria dos casos no React 19.

Relacionado: useCallback -- padrões e armadilhas | useMemo -- primitivo irmão | Re-renderizações -- quando a identidade do callback importa

Exemplos Intermediários

8. Custom Hook

Extraia lógica com estado para uma função reutilizável.

import { useEffect, useState } from "react";
 
function useOnlineStatus() {
  const [isOnline, setIsOnline] = useState(() =>
    typeof navigator === "undefined" ? true : navigator.onLine
  );
 
  useEffect(() => {
    const on = () => setIsOnline(true);
    const off = () => setIsOnline(false);
    window.addEventListener("online", on);
    window.addEventListener("offline", off);
    return () => {
      window.removeEventListener("online", on);
      window.removeEventListener("offline", off);
    };
  }, []);
 
  return isOnline;
}
 
function StatusBanner() {
  const isOnline = useOnlineStatus();
  return <p>You are {isOnline ? "online" : "offline"}</p>;
}

• Um hook customizado é qualquer função cujo nome começa com use e pode chamar outros hooks.
• Ele permite compartilhar lógica entre componentes sem um componente wrapper ou higher-order component.
• Cada componente que chama o hook obtém seu próprio estado independente -- nada é compartilhado entre os locais de chamada.
• Lide com SSR com cuidado -- APIs exclusivas do navegador (navigator, window) precisam de guardas para a renderização do servidor.

Relacionado: Custom Hooks -- regras, testes, padrões | Guia de Custom Hooks -- padrões mais amplos | useToggle -- um hook customizado do mundo real

9. useTransition

Marque uma atualização de estado como não urgente para que a UI permaneça responsiva.

import { useState, useTransition } from "react";
 
function FilterableList({ items }: { items: string[] }) {
  const [query, setQuery] = useState("");
  const [filtered, setFiltered] = useState(items);
  const [isPending, startTransition] = useTransition();
 
  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    setQuery(e.target.value);
    startTransition(() => {
      setFiltered(items.filter((i) => i.includes(e.target.value)));
    });
  };
 
  return (
    <div>
      <input value={query} onChange={handleChange} />
      {isPending && <p>Updating...</p>}
      <ul>
        {filtered.map((i) => (
          <li key={i}>{i}</li>
        ))}
      </ul>
    </div>
  );
}

• Atualizações dentro de startTransition são de baixa prioridade -- o React pode interrompê-las se o usuário digitar novamente.
• isPending permite mostrar um indicador de carregamento sutil durante o trabalho adiado.
• Use-o para filtragem pesada, ordenação ou atualizações de gráficos que, de outra forma, bloqueariam a digitação.
• O React 19 envolve envios de <form action={...}> em uma transição automaticamente -- nenhum startTransition explícito é necessário para ações de formulário.

Relacionado: useTransition -- padrões e armadilhas | useDeferredValue -- hook irmão para adiar um valor em vez de uma atualização

10. useActionState (React 19)

Controle uma ação de formulário e rastreie seu estado pendente e resultado em uma única chamada.

"use client";
import { useActionState } from "react";
 
async function submitFeedback(_prev: string | null, formData: FormData) {
  const message = formData.get("message") as string;
  if (!message) return "Message is required.";
  await fetch("/api/feedback", { method: "POST", body: formData });
  return null;
}
 
function FeedbackForm() {
  const [error, action, isPending] = useActionState(submitFeedback, null);
 
  return (
    <form action={action}>
      <textarea name="message" />
      {error && <p>{error}</p>}
      <button type="submit" disabled={isPending}>
        {isPending ? "Sending..." : "Send"}
      </button>
    </form>
  );
}

• Retorna [state, action, isPending] -- conecte a action diretamente a <form action={action}>.
• A função de ação recebe o estado anterior e o FormData; seu valor de retorno se torna o próximo estado.
• Emparelhe com server actions para aprimoramento progressivo -- o formulário funciona mesmo antes do JS carregar.
• Renomeado de useFormState do React 18 -- mesma API, novo nome.

Relacionado: useActionState -- API completa e padrões | Server Actions -- o lado do servidor do par | Formulários de Server Action -- padrões de formulário ponta a ponta

11. use (React 19)

Leia uma promise ou contexto inline -- sem .then, sem useEffect.

"use client";
import { Suspense, use } from "react";
 
interface User {
  id: number;
  name: string;
}
 
function UserCard({ userPromise }: { userPromise: Promise<User> }) {
  const user = use(userPromise);
  return <h2>{user.name}</h2>;
}
 
function UserPage({ userPromise }: { userPromise: Promise<User> }) {
  return (
    <Suspense fallback={<p>Loading...</p>}>
      <UserCard userPromise={userPromise} />
    </Suspense>
  );
}

• use(promise) suspende o componente até que a promise resolva -- o <Suspense> pai mostra o fallback.
• use(context) lê um valor de contexto e, ao contrário de useContext, pode ser chamado condicionalmente dentro de blocos if.
• Crie a promise em um componente pai (geralmente um Server Component) e passe-a para baixo -- não a crie dentro do componente de renderização, ou ela será recriada a cada renderização.
• Combine com Server Components de streaming para uma história de busca de dados sem useEffect.

Relacionado: use -- detalhes completos da API | Suspense -- o mecanismo de fallback | Server Components -- de onde as promises geralmente se originam