Fundamentos de Padrões React

11 exemplos para você começar com Padrões React -- 7 básicos e 4 intermediários.

Pré-requisitos

Nenhum pacote extra necessário -- cada padrão nesta página é fornecido com o React. Um projeto React padrão (Next.js, Vite ou CRA) com TypeScript é suficiente.

Os padrões abaixo são formas de pensar sobre componentes -- como eles se compõem, como compartilham estado, onde colocar limites de carregamento/erro. Eles não são APIs que você instala; são formas reutilizáveis que você reconhece.

Exemplos Básicos

1. Composição com Children

Construa componentes de layout e wrapper aceitando children em vez de herdar ou configurar.

function Card({ children }: { children: React.ReactNode }) {
  return <div className="border rounded p-4 shadow">{children}</div>;
}
 
// Uso
function Page() {
  return (
    <Card>
      <h2>Título</h2>
      <p>Qualquer conteúdo que o pai queira passar.</p>
    </Card>
  );
}

• children é o que você coloca entre as tags de abertura e fechamento do componente.
• React.ReactNode aceita strings, números, elementos, fragments ou null -- o tipo "renderizável" mais amplo.
• Prefira composição em vez de props para tudo -- isso mantém a API pequena e permite que os consumidores controlem o layout.
• Quando você precisar de "slots" nomeados (cabeçalho + rodapé), aceite-os como props nomeadas: <Card header={...} footer={...} />.

Relacionado: Composição sobre Herança -- slots, componentes compostos, padrões de layout | Componentes (Fundamentos) -- a prop children em profundidade

2. Controlado vs Não Controlado

Decida quem é o dono do estado do componente: o pai (controlado) ou o próprio componente (não controlado).

import { useState } from "react";
 
// Controlado: o pai é o dono do valor
function ControlledInput({
  value, onChange,
}: {
  value: string;
  onChange: (v: string) => void;
}) {
  return <input value={value} onChange={(e) => onChange(e.target.value)} />;
}
 
// Não controlado: o componente é o dono de seu próprio estado internamente
function UncontrolledInput({ defaultValue = "" }: { defaultValue?: string }) {
  const [value, setValue] = useState(defaultValue);
  return <input value={value} onChange={(e) => setValue(e.target.value)} />;
}

• Controlado permite que o pai valide, transforme ou redefina o valor -- a escolha certa para formulários e wizards.
• Não controlado é mais simples para widgets autônomos que nunca precisam de coordenação externa.
• Ofereça ambos em um componente reutilizável: aceite value/onChange (controlado) ou defaultValue (não controlado), nunca os misture.
• Mudar de modo no meio do ciclo de vida gera um aviso "controlado para não controlado" -- escolha um na montagem e mantenha-o.

Relacionado: Controlado vs Não Controlado -- formato da API, componentes com ambos os modos, casos extremos | Formulários: Controlado vs Não Controlado -- o lado específico de formulários

3. Render Props

Compartilhe comportamento passando uma função como filho ou prop, retornando JSX baseado no estado interno.

import { useState } from "react";
 
function Toggle({
  render,
}: {
  render: (state: { on: boolean; toggle: () => void }) => React.ReactNode;
}) {
  const [on, setOn] = useState(false);
  return <>{render({ on, toggle: () => setOn((v) => !v) })}</>;
}
 
// Uso
function App() {
  return (
    <Toggle
      render={({ on, toggle }) => (
        <button onClick={toggle}>{on ? "ON" : "OFF"}</button>
      )}
    />
  );
}

• A render prop é uma função; o componente compartilhado a chama com estado e helpers.
• Os consumidores decidem o que renderizar -- um componente, muitas apresentações.
• Hooks personalizados cobrem a maioria dos casos que render props resolviam, mas render props ainda brilham para APIs específicas de renderização (bibliotecas de posicionamento, medição, movimento).
• Nomeie a prop render, children ou algo descritivo (renderItem); seja consistente dentro de uma base de código.

Relacionado: Render Props -- quando ainda usá-las, alternativa de hooks | Higher-Order Components -- um padrão de indireção similar

4. Componentes Compostos

Projete componentes multi-parte que compartilham estado implícito através de context -- o pai coordena, os filhos compõem.

import { createContext, useContext, useState } from "react";
 
const TabsCtx = createContext<{ active: string; setActive: (v: string) => void; } | null>(null);
 
function Tabs({ defaultValue, children }: { defaultValue: string; children: React.ReactNode }) {
  const [active, setActive] = useState(defaultValue);
  return <TabsCtx.Provider value={{ active, setActive }}>{children}</TabsCtx.Provider>;
}
 
function Tab({ value, children }: { value: string; children: React.ReactNode }) {
  const ctx = useContext(TabsCtx)!;
  return (
    <button onClick={() => ctx.setActive(value)} aria-pressed={ctx.active === value}>
      {children}
    </button>
  );
}
 
function Panel({ value, children }: { value: string; children: React.ReactNode }) {
  const ctx = useContext(TabsCtx)!;
  return ctx.active === value ? <div>{children}</div> : null;
}
 
// Uso
// <Tabs defaultValue="a">
//   <Tab value="a">A</Tab><Tab value="b">B</Tab>
//   <Panel value="a">Conteúdo A</Panel><Panel value="b">Conteúdo B</Panel>
// </Tabs>

• O pai é o dono do estado; os filhos leem via context -- o consumidor nunca passa props manualmente.
• Exporte os subcomponentes sob o namespace do pai (Tabs.Tab, Tabs.Panel) para uma API limpa.
• Force o limite do pai: gere um erro útil se useContext retornar null, para que o uso indevido falhe ruidosamente.
• Esta é a espinha dorsal dos primitivos shadcn e Radix UI -- aprenda uma vez, reconheça em todo lugar.

Relacionado: Componentes Compostos -- mergulho profundo, tipagem TypeScript | Padrões de Contexto -- melhores práticas de context

5. Padrão de Contexto

Compartilhe dados através de uma subárvore sem prop drilling; divida contextos por frequência de atualização para evitar renderização excessiva.

import { createContext, useContext, useMemo, useState } from "react";
 
type Theme = "light" | "dark";
const ThemeCtx = createContext<Theme>("light");
const SetThemeCtx = createContext<(t: Theme) => void>(() => {});
 
function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setTheme] = useState<Theme>("light");
  const set = useMemo(() => setTheme, []);
  return (
    <ThemeCtx.Provider value={theme}>
      <SetThemeCtx.Provider value={set}>{children}</SetThemeCtx.Provider>
    </ThemeCtx.Provider>
  );
}
 
function ThemeToggle() {
  const theme = useContext(ThemeCtx);
  const setTheme = useContext(SetThemeCtx);
  return (
    <button onClick={() => setTheme(theme === "light" ? "dark" : "light")}>
      {theme}
    </button>
  );
}

• Divida contextos de leitura e escrita -- componentes que apenas chamam setTheme não re-renderizam quando theme muda.
• Envolva o setter em useMemo ou useCallback para que o valor do contexto de escrita permaneça estável referencialmente.
• Nunca coloque valores que mudam frequentemente (posição do mouse, scroll) em context -- todo consumidor re-renderiza.
• Para estado do servidor (usuário, carrinho, tema entre abas), use Zustand ou uma abordagem sincronizada com URL em vez disso.

Relacionado: Padrões de Contexto -- divisão, otimização, componentes de servidor | useContext -- o hook subjacente | Context vs. Zustand -- quando usar cada um

6. Error Boundary

Capture erros em tempo de renderização em uma subárvore e renderize um fallback em vez de uma tela branca.

"use client";
import { Component, type ReactNode } from "react";
 
interface State { error: Error | null; }
 
class ErrorBoundary extends Component<{ children: ReactNode }, State> {
  state: State = { error: null };
 
  static getDerivedStateFromError(error: Error): State {
    return { error };
  }
 
  componentDidCatch(error: Error) {
    console.error("Erro na UI:", error);
  }
 
  render() {
    if (this.state.error) {
      return <p role="alert">Algo deu errado: {this.state.error.message}</p>;
    }
    return this.props.children;
  }
}
 
// Uso
// <ErrorBoundary><BuggyChart /></ErrorBoundary>

• Error boundaries devem ser componentes de classe -- getDerivedStateFromError ainda não tem um equivalente em hook.
• Eles capturam erros durante a renderização, métodos de ciclo de vida e construtores -- não manipuladores de eventos, código assíncrono ou componentes de servidor.
• Coloque-os em limites significativos: por rota, por painel, por widget. Um grande boundary no topo esconde demais.
• Para aplicativos de produção, use react-error-boundary (mais leve, API amigável a hooks) e registre no Sentry/Datadog em componentDidCatch.

Relacionado: Error Boundaries -- react-error-boundary, error.tsx do Next.js, logging | Suspense -- a contraparte de carregamento

7. Portal

Renderize filhos em um nó DOM fora da árvore do pai -- escape de overflow: hidden e armadilhas de z-index.

"use client";
import { createPortal } from "react-dom";
 
function Modal({
  open, onClose, children,
}: {
  open: boolean;
  onClose: () => void;
  children: React.ReactNode;
}) {
  if (!open || typeof document === "undefined") return null;
 
  return createPortal(
    <div
      onClick={onClose}
      style={{
        position: "fixed", inset: 0, background: "rgba(0,0,0,0.5)",
        display: "grid", placeItems: "center",
      }}
    >
      <div onClick={(e) => e.stopPropagation()} style={{ background: "white", padding: 24 }}>
        {children}
      </div>
    </div>,
    document.body,
  );
}

• createPortal(node, container) monta node dentro de container, mas eventos ainda borbulham para o pai React.
• Perfeito para modais, tooltips e dropdowns -- eles renderizam no topo do DOM independentemente de onde você os escreveu.
• Proteja com typeof document === "undefined" para que seja seguro em SSR; caso contrário, document gera um erro no servidor.
• Gerencie o foco: prenda-o no modal ao abrir, restaure-o ao abridor ao fechar -- a acessibilidade depende disso.

Relacionado: React Portals -- armadilha de foco, acessibilidade, receitas de z-index | Componente Modal -- padrões de modal de produção

Exemplos Intermediários

8. Suspense para UI Assíncrona

Mostre declarativamente um fallback enquanto um filho assíncrono resolve -- sem passar prop isLoading.

"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>;
}
 
export default function UserPage({
  userPromise,
}: {
  userPromise: Promise<User>;
}) {
  return (
    <Suspense fallback={<p>Carregando usuário...</p>}>
      <UserCard userPromise={userPromise} />
    </Suspense>
  );
}

• <Suspense fallback={...}> captura componentes filhos que "suspendem" (Componentes de Servidor aguardando dados, Componentes de Cliente lendo uma promise com use).
• O fallback renderiza imediatamente; o conteúdo real o substitui quando o trabalho assíncrono termina.
• Crie a promise em um pai (geralmente um Componente de Servidor) e passe-a para baixo -- não a recrie a cada renderização.
• Combine com um <ErrorBoundary> para que promises rejeitadas mostrem uma UI de erro em vez de propagar pela árvore.

Relacionado: Suspense Boundaries -- posicionamento, streaming, casos extremos | hook use -- lendo promises e context | Streaming do Next.js -- Suspense em Componentes de Servidor

9. Higher-Order Component

Envolva um componente para injetar comportamento compartilhado -- autenticação, logging, flags de funcionalidade.

"use client";
import { useEffect } from "react";
 
function withLogging<P extends object>(
  Component: React.ComponentType<P>,
  label: string
) {
  return function LoggedComponent(props: P) {
    useEffect(() => {
      console.log(`[${label}] montado`);
      return () => console.log(`[${label}] desmontado`);
    }, []);
    return <Component {...props} />;
  };
}
 
// Uso
function Dashboard({ userId }: { userId: string }) {
  return <p>Dashboard para {userId}</p>;
}
 
const LoggedDashboard = withLogging(Dashboard, "Dashboard");

• Um HOC é uma função que recebe um componente e retorna um novo com comportamento extra.
• Use genéricos (<P extends object>) para que o componente envolvido mantenha seus tipos de prop originais.
• Hooks personalizados geralmente substituem HOCs no React moderno -- use HOCs apenas quando precisar injetar JSX ou envolver componentes de classe.
• Nomeie o componente retornado (function LoggedComponent(...)) para que o React DevTools mostre algo útil.

Relacionado: Higher-Order Components -- tipagem, armadilhas, quando preferir hooks | Render Props -- o outro padrão de "indireção"

10. Máquina de Estado para Lógica de UI

Modele estados complexos de UI como transições explícitas -- sem mais combinações de props "impossíveis".

import { useReducer } from "react";
 
type Status =
  | { kind: "idle" }
  | { kind: "loading" }
  | { kind: "success"; data: string }
  | { kind: "error"; message: string };
 
type Event =
  | { type: "FETCH" }
  | { type: "RESOLVE"; data: string }
  | { type: "REJECT"; message: string }
  | { type: "RESET" };
 
function reducer(state: Status, event: Event): Status {
  switch (state.kind) {
    case "idle":    return event.type === "FETCH" ? { kind: "loading" } : state;
    case "loading": return event.type === "RESOLVE" ? { kind: "success", data: event.data }
                  : event.type === "REJECT" ? { kind: "error", message: event.message }
                  : state;
    case "success":
    case "error":   return event.type === "RESET" ? { kind: "idle" } : state;
  }
}
 
export default function DataPanel() {
  const [state, dispatch] = useReducer(reducer, { kind: "idle" } as Status);
 
  return (
    <div>
      {state.kind === "idle" && <button onClick={() => dispatch({ type: "FETCH" })}>Carregar</button>}
      {state.kind === "loading" && <p>Carregando...</p>}
      {state.kind === "success" && <p>Recebido: {state.data}</p>}
      {state.kind === "error" && <p>Erro: {state.message}</p>}
    </div>
  );
}

• Uma união discriminada torna combinações inválidas (loading: true, error: "...", data: "x", isLoading: true) impossíveis.
• O reducer é o único lugar onde as transições vivem -- trivial de testar unitariamente e de desenhar como um diagrama.
• Para gráficos de estado maiores (estados hierárquicos, guards, efeitos colaterais), avance para XState; a versão pequena aqui cobre a maioria das UIs.
• Combine com useTransition ou useActionState para disparar mudanças de estado a partir de trabalho assíncrono.

Relacionado: Máquinas de Estado para Lógica de UI -- exemplos mais aprofundados, integração com XState | useReducer -- o hook por trás disso

11. Performance: React.memo + Props Estáveis

Evite que um filho re-renderize quando seu pai re-renderiza, mas suas props não mudaram.

import { memo, useCallback, useState } from "react";
 
const Row = memo(function Row({
  label, onSelect,
}: {
  label: string;
  onSelect: (label: string) => void;
}) {
  return <li onClick={() => onSelect(label)}>{label}</li>;
});
 
export default function List({ items }: { items: string[] }) {
  const [selected, setSelected] = useState<string | null>(null);
 
  // Identidade estável -- useCallback mantém as linhas memoizadas de re-renderizar
  const onSelect = useCallback((label: string) => setSelected(label), []);
 
  return (
    <>
      <p>Selecionado: {selected ?? "nenhum"}</p>
      <ul>
        {items.map((item) => (
          <Row key={item} label={item} onSelect={onSelect} />
        ))}
      </ul>
    </>
  );
}

• memo(Component) pula re-renderizações quando as props são referencialmente iguais à renderização anterior.
• Uma função de seta inline criaria uma nova referência a cada renderização -- useCallback dá a ela uma identidade estável para que memo possa realmente otimizar.
• Meça primeiro: o React DevTools Profiler diz quais componentes são caros antes de você usar memo.
• Com o React Compiler (React 19+), você pode frequentemente deletar memo/useCallback/useMemo inteiramente -- o compilador cuida disso.

Relacionado: Otimização de Performance do React -- profiling, keys, virtualização de listas | Re-renders -- o que dispara renderizações e como reduzi-las | React Compiler -- auto-memoização