Guia Prático

React Design Patterns

// arquitetura, composição e boas práticas

Patterns arquiteturais de React usados em projetos profissionais: Compound Components, Custom Hooks, Render Props, HOCs e mais — com exemplos práticos.

Composição & Componentes

// patterns para componentes flexíveis

Patterns que tornam seus componentes mais flexíveis, reutilizáveis e fáceis de manter.

Compound Components

Componentes que trabalham juntos compartilhando estado implícito via Context. Permite API declarativa e flexível.

React / TypeScript

// API declarativa e limpa
<Select>
  <Select.Trigger>Escolha uma opção</Select.Trigger>
  <Select.Content>
    <Select.Item value="react">React</Select.Item>
    <Select.Item value="vue">Vue</Select.Item>
    <Select.Item value="angular">Angular</Select.Item>
  </Select.Content>
</Select>
 
// Implementação com Context
const SelectContext = createContext<SelectState | null>(null);
 
function Select({ children }: { children: ReactNode }) {
  const [value, setValue] = useState('');
  return (
    <SelectContext.Provider value={{ value, setValue }}>
      {children}
    </SelectContext.Provider>
  );
}
 
Select.Trigger = function Trigger({ children }) { /* ... */ };
Select.Content = function Content({ children }) { /* ... */ };
Select.Item = function Item({ value, children }) { /* ... */ };

Quando usar:

Selects, Tabs, Accordions

Menus e Dropdowns

Form Fields compostos

Render Props

Passa uma função como prop (ou children) que recebe dados e retorna JSX. Útil para injetar lógica sem impor UI.

React / TypeScript

// O componente fornece dados, o consumidor decide a UI
function MouseTracker({ children }: {
  children: (pos: { x: number; y: number }) => ReactNode
}) {
  const [pos, setPos] = useState({ x: 0, y: 0 });
 
  useEffect(() => {
    const handler = (e: MouseEvent) =>
      setPos({ x: e.clientX, y: e.clientY });
    window.addEventListener('mousemove', handler);
    return () => window.removeEventListener('mousemove', handler);
  }, []);
 
  return <>{children(pos)}</>;
}
 
// Uso
<MouseTracker>
  {({ x, y }) => (
    <div>Mouse: {x}, {y}</div>
  )}
</MouseTracker>

Quando usar:

Injeção de dados sem impor layout

Componentes headless

Libs de formulário

Container / Presentational

Separe lógica (Container) de apresentação (Presentational). O Container busca dados e gerencia estado, o Presentational só renderiza.

React / TypeScript

// Container — lógica e dados
function UserListContainer() {
  const { data, isLoading } = useQuery({
    queryKey: ['users'],
    queryFn: fetchUsers
  });
 
  if (isLoading) return <Skeleton />;
  return <UserList users={data ?? []} />;
}
 
// Presentational — só UI, sem lógica
function UserList({ users }: { users: User[] }) {
  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

Quando usar:

Separação de responsabilidades

Componentes testáveis

Reuso da camada visual

Custom Hooks

// extraia e reutilize lógica

Custom hooks encapsulam lógica reutilizável. São a forma mais idiomática de compartilhar comportamento entre componentes no React.

useLocalStorage

Persiste estado no localStorage com sincronização automática.

Hook

function useLocalStorage<T>(key: string, initial: T) {
  const [value, setValue] = useState<T>(() => {
    if (typeof window === 'undefined') return initial;
    const stored = localStorage.getItem(key);
    return stored ? JSON.parse(stored) : initial;
  });
 
  useEffect(() => {
    localStorage.setItem(key, JSON.stringify(value));
  }, [key, value]);
 
  return [value, setValue] as const;
}
 
// Uso
const [theme, setTheme] = useLocalStorage('theme', 'dark');

useDebounce

Atrasa a atualização de um valor — ideal para buscas e inputs.

Hook

function useDebounce<T>(value: T, delay: number): T {
  const [debounced, setDebounced] = useState(value);
 
  useEffect(() => {
    const timer = setTimeout(() => setDebounced(value), delay);
    return () => clearTimeout(timer);
  }, [value, delay]);
 
  return debounced;
}
 
// Uso
const [search, setSearch] = useState('');
const debouncedSearch = useDebounce(search, 300);
 
useEffect(() => {
  fetchResults(debouncedSearch);
}, [debouncedSearch]);

useMediaQuery

Reage a mudanças de media query (responsividade) no JavaScript.

Hook

function useMediaQuery(query: string): boolean {
  const [matches, setMatches] = useState(false);
 
  useEffect(() => {
    const media = window.matchMedia(query);
    setMatches(media.matches);
 
    const listener = (e: MediaQueryListEvent) =>
      setMatches(e.matches);
    media.addEventListener('change', listener);
    return () => media.removeEventListener('change', listener);
  }, [query]);
 
  return matches;
}
 
// Uso
const isMobile = useMediaQuery('(max-width: 768px)');

useClickOutside

Detecta cliques fora de um elemento — perfeito para modais e dropdowns.

Hook

function useClickOutside(
  ref: RefObject<HTMLElement | null>,
  handler: () => void
) {
  useEffect(() => {
    const listener = (e: MouseEvent | TouchEvent) => {
      if (!ref.current?.contains(e.target as Node)) {
        handler();
      }
    };
    document.addEventListener('mousedown', listener);
    document.addEventListener('touchstart', listener);
    return () => {
      document.removeEventListener('mousedown', listener);
      document.removeEventListener('touchstart', listener);
    };
  }, [ref, handler]);
}
 
// Uso
const ref = useRef<HTMLDivElement>(null);
useClickOutside(ref, () => setOpen(false));

Patterns de Estado

// gerencie estado de forma escalável

Patterns para gerenciar estado complexo de forma organizada e previsível.

Reducer Pattern

Use useReducer para estado complexo com múltiplas ações. Mais previsível que múltiplos useState.

❌ sem pattern

// Múltiplos useState — difícil de manter
const [items, setItems] = useState([]);
const [loading, setLoading] = useState(false);
const [error, setError] = useState(null);
const [page, setPage] = useState(1);
 
// Atualização espalhada pelo componente
setLoading(true);
setError(null);
fetch(url)
  .then(data => { setItems(data); setLoading(false); })
  .catch(err => { setError(err); setLoading(false); });

Context + Provider Pattern

Compartilhe estado global com tipo seguro via Context. Evita prop drilling em árvores profundas.

❌ sem pattern

// Prop drilling — 4 níveis de profundidade
<App user={user} />
  <Layout user={user} />
    <Sidebar user={user} />
      <UserMenu user={user} />
        <Avatar name={user.name} />

Performance Patterns

// otimize renders e carregamento

Técnicas para evitar re-renders desnecessários e otimizar carregamento.

React.memo + useCallback

Evite re-renders de componentes filhos quando props não mudam.

React

// Componente memoizado — só re-renderiza se props mudarem
const ExpensiveList = memo(function ExpensiveList({
  items,
  onItemClick,
}: {
  items: Item[];
  onItemClick: (id: string) => void;
}) {
  return (
    <ul>
      {items.map(item => (
        <li key={item.id} onClick={() => onItemClick(item.id)}>
          {item.name}
        </li>
      ))}
    </ul>
  );
});
 
// Parent estabiliza a referência da função
function Parent() {
  const [items] = useState(fetchItems());
 
  const handleClick = useCallback((id: string) => {
    console.log('clicked', id);
  }, []);
 
  return <ExpensiveList items={items} onItemClick={handleClick} />;
}

useMemo para Cálculos Pesados

Memorize resultados de cálculos caros para evitar recomputação a cada render.

React

function Dashboard({ transactions }: { transactions: Transaction[] }) {
  // Só recalcula quando transactions muda
  const stats = useMemo(() => ({
    total: transactions.reduce((sum, t) => sum + t.amount, 0),
    average: transactions.reduce((sum, t) => sum + t.amount, 0)
      / transactions.length,
    max: Math.max(...transactions.map(t => t.amount)),
    byCategory: groupBy(transactions, 'category'),
  }), [transactions]);
 
  return (
    <div>
      <StatCard label="Total" value={stats.total} />
      <StatCard label="Média" value={stats.average} />
    </div>
  );
}

Lazy Loading + Suspense

Carregue componentes pesados sob demanda para reduzir o bundle inicial.

React

import { lazy, Suspense } from 'react';
 
// Carregado apenas quando necessário
const HeavyChart = lazy(() => import('./HeavyChart'));
const MarkdownEditor = lazy(() => import('./MarkdownEditor'));
 
function App() {
  const [showChart, setShowChart] = useState(false);
 
  return (
    <div>
      <button onClick={() => setShowChart(true)}>
        Mostrar Gráfico
      </button>
 
      {showChart && (
        <Suspense fallback={<Skeleton className="h-64" />}>
          <HeavyChart data={data} />
        </Suspense>
      )}
    </div>
  );
}

Pronto para React avançado?

Explore mais guias e ferramentas práticas para devs.

Voltar às Dicas

Conteúdo relacionado

Dicas de IA para DesenvolvedoresGuia prático de ferramentas IA, uso consciente de tokens e modelos: v0, Copilot, prompt engineering, boas práticas e ferramentas para produtividade dev.

Tailwind CSS + shadcn/ui — Guia PráticoSetup completo, componentes reutilizáveis, padrões de código e boas práticas com Tailwind CSS e shadcn/ui para projetos React e Next.js.

React Query Essencial — Cache e MutationsGuia completo de TanStack Query (React Query): cache inteligente, mutations, invalidação, otimistic updates e boas práticas para apps React.

12 min de leitura

// API declarativa e limpa

<Select.Trigger>Escolha uma opção</Select.Trigger>

<Select.Content>

<Select.Item value="react">React</Select.Item>

<Select.Item value="vue">Vue</Select.Item>

<Select.Item value="angular">Angular</Select.Item>

</Select.Content>

</Select>

// Implementação com Context

const SelectContext = createContext<SelectState | null>(null);

function Select({ children }: { children: ReactNode }) {

const [value, setValue] = useState('');

return (

<SelectContext.Provider value={{ value, setValue }}>

{children}

</SelectContext.Provider>

);

}

Select.Trigger = function Trigger({ children }) { /* ... */ };

Select.Content = function Content({ children }) { /* ... */ };

Select.Item = function Item({ value, children }) { /* ... */ };

// O componente fornece dados, o consumidor decide a UI

function MouseTracker({ children }: {

children: (pos: { x: number; y: number }) => ReactNode

}) {

const [pos, setPos] = useState({ x: 0, y: 0 });

useEffect(() => {

const handler = (e: MouseEvent) =>

setPos({ x: e.clientX, y: e.clientY });

window.addEventListener('mousemove', handler);

return () => window.removeEventListener('mousemove', handler);

}, []);

return <>{children(pos)}</>;

}

// Uso

{({ x, y }) => (

<div>Mouse: {x}, {y}</div>

)}

</MouseTracker>

// Container — lógica e dados

function UserListContainer() {

const { data, isLoading } = useQuery({

queryKey: ['users'],

queryFn: fetchUsers

});

if (isLoading) return <Skeleton />;

return <UserList users={data ?? []} />;

}

// Presentational — só UI, sem lógica

function UserList({ users }: { users: User[] }) {

return (

<ul>

{users.map(user => (

))}

</ul>

);

}

function useLocalStorage<T>(key: string, initial: T) {

const [value, setValue] = useState<T>(() => {

if (typeof window === 'undefined') return initial;

const stored = localStorage.getItem(key);

return stored ? JSON.parse(stored) : initial;

});

useEffect(() => {

localStorage.setItem(key, JSON.stringify(value));

}, [key, value]);

return [value, setValue] as const;

}

// Uso

const [theme, setTheme] = useLocalStorage('theme', 'dark');

function useDebounce<T>(value: T, delay: number): T {

const [debounced, setDebounced] = useState(value);

useEffect(() => {

const timer = setTimeout(() => setDebounced(value), delay);

return () => clearTimeout(timer);

}, [value, delay]);

return debounced;

}

// Uso

const [search, setSearch] = useState('');

const debouncedSearch = useDebounce(search, 300);

useEffect(() => {

fetchResults(debouncedSearch);

}, [debouncedSearch]);

function useMediaQuery(query: string): boolean {

const [matches, setMatches] = useState(false);

useEffect(() => {

const media = window.matchMedia(query);

setMatches(media.matches);

const listener = (e: MediaQueryListEvent) =>

setMatches(e.matches);

media.addEventListener('change', listener);

return () => media.removeEventListener('change', listener);

}, [query]);

return matches;

}

// Uso

const isMobile = useMediaQuery('(max-width: 768px)');

function useClickOutside(

ref: RefObject<HTMLElement | null>,

handler: () => void

) {

useEffect(() => {

const listener = (e: MouseEvent | TouchEvent) => {

if (!ref.current?.contains(e.target as Node)) {

handler();

}

};

document.addEventListener('mousedown', listener);

document.addEventListener('touchstart', listener);

return () => {

document.removeEventListener('mousedown', listener);

document.removeEventListener('touchstart', listener);

};

}, [ref, handler]);

}

// Uso

const ref = useRef<HTMLDivElement>(null);

useClickOutside(ref, () => setOpen(false));

// Múltiplos useState — difícil de manter

const [items, setItems] = useState([]);

const [loading, setLoading] = useState(false);

const [error, setError] = useState(null);

const [page, setPage] = useState(1);

// Atualização espalhada pelo componente

setLoading(true);

setError(null);

fetch(url)

.then(data => { setItems(data); setLoading(false); })

.catch(err => { setError(err); setLoading(false); });

// Componente memoizado — só re-renderiza se props mudarem

const ExpensiveList = memo(function ExpensiveList({

items,

onItemClick,

}: {

items: Item[];

onItemClick: (id: string) => void;

}) {

return (

<ul>

{items.map(item => (

<li key={item.id} onClick={() => onItemClick(item.id)}>

{item.name}

</li>

))}

</ul>

);

});

// Parent estabiliza a referência da função

function Parent() {

const [items] = useState(fetchItems());

const handleClick = useCallback((id: string) => {

console.log('clicked', id);

}, []);

return <ExpensiveList items={items} onItemClick={handleClick} />;

}

function Dashboard({ transactions }: { transactions: Transaction[] }) {

// Só recalcula quando transactions muda

const stats = useMemo(() => ({

total: transactions.reduce((sum, t) => sum + t.amount, 0),

average: transactions.reduce((sum, t) => sum + t.amount, 0)

/ transactions.length,

max: Math.max(...transactions.map(t => t.amount)),

byCategory: groupBy(transactions, 'category'),

}), [transactions]);

return (

<div>

</div>

);

}

import { lazy, Suspense } from 'react';

// Carregado apenas quando necessário

const HeavyChart = lazy(() => import('./HeavyChart'));

const MarkdownEditor = lazy(() => import('./MarkdownEditor'));

function App() {

const [showChart, setShowChart] = useState(false);

return (

<div>

<button onClick={() => setShowChart(true)}>

Mostrar Gráfico

</button>

{showChart && (

</Suspense>

)}

</div>

);

}