Hook useState

Gerencie o estado local do componente com o hook mais fundamental do React.

Receita

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

const [value, setValue] = useState<T>(initialValue)
 
// Com inicializador preguiçoso (cálculo caro)
const [value, setValue] = useState(() => computeExpensive())
 
// Função de atualizador (quando o novo estado depende do anterior)
setValue(prev => prev + 1)

Quando usar: Você precisa de estado local e síncrono em um único componente.

Exemplo de Trabalho

"use client";
 
import { useState } from "react";
 
export function Counter() {
  const [count, setCount] = useState(0);
 
  return (
    <div className="flex items-center gap-4">
      <button
        onClick={() => setCount(prev => prev - 1)}
        className="px-3 py-1 border rounded"
      >
        -
      </button>
      <span className="text-xl font-mono w-12 text-center">{count}</span>
      <button
        onClick={() => setCount(prev => prev + 1)}
        className="px-3 py-1 border rounded"
      >
        +
      </button>
    </div>
  );
}

O que isso demonstra:

• useState básico com um número
• Usando a função de atualizador prev => prev + 1 em vez de setCount(count + 1) para evitar problemas de closure obsoleto
• O componente é re-renderizado apenas quando count muda

Análise Detalhada

Como Funciona

• useState retorna uma tupla: o valor de estado atual e uma função de configuração
• Na renderização inicial, o estado é definido como initialValue
• Em renderizações subsequentes, o React retorna o estado mais recente
• Quando você chama a função de configuração, o React agenda uma re-renderização com o novo valor
• O React agrupa várias chamadas setState dentro do mesmo manipulador de eventos em uma única re-renderização para otimização de desempenho

Parâmetros e Valores de Retorno

Variações

Estado de objeto:

const [form, setForm] = useState({ name: "", email: "" });
// Deve usar spread para criar nova referência
setForm(prev => ({ ...prev, name: "Alice" }));

Estado de array:

const [items, setItems] = useState<string[]>([]);
setItems(prev => [...prev, "new item"]);

Inicializador preguiçoso (executa apenas na montagem):

const [data, setData] = useState(() => {
  return JSON.parse(localStorage.getItem("key") ?? "null");
});

Notas de TypeScript

// O tipo é inferido do valor inicial
const [count, setCount] = useState(0); // number
 
// Genérico explícito para tipos de união ou nulo
const [user, setUser] = useState<User | null>(null);
 
// Genérico explícito para tipos complexos
const [items, setItems] = useState<Item[]>([]);

Armadilhas

Coisas que vão te morder. Cada armadilha inclui o que dá errado, por que acontece e a correção.

• Armadilha de closure obsoleto - Ler count dentro de um setTimeout ou useEffect sem ele no array de dependências fornece o valor antigo. Correção: Use a função atualizadora setCount(prev => prev + 1).

• Identidade do objeto - setState({ ...obj }) cria uma nova referência a cada vez, mesmo que os valores não tenham mudado, causando re-renderizações desnecessárias. Correção: Espalhe apenas quando os valores realmente mudarem, ou use useMemo para valores derivados.

• Armadilha do inicializador preguiçoso - Passar computeExpensive() em vez de () => computeExpensive() executa a função em cada renderização, não apenas na primeira. Correção: Sempre envolva cálculos caros em uma função de seta.

• Armadilha de agrupamento - Chamar setCount(count + 1) três vezes seguidas resulta em apenas +1, não +3, porque cada chamada lê o mesmo count obsoleto. Correção: Use a função atualizadora setCount(prev => prev + 1).

Alternativas

Outras maneiras de resolver o mesmo problema - e quando cada uma é a melhor escolha.

Por que não usar sempre Zustand? Zustand adiciona uma dependência e indireção. useState tem custo zero para estado local - sem provider, sem loja, sem seletores. Use a ferramenta mais simples que funcionar.

Exemplo do Mundo Real

De uma aplicação SaaS de produção Next.js 15 / React 19 (SystemsArchitect.io).

// Exemplo de produção: formulário de edição de FAQ com múltiplos useState
// Arquivo: src/components/admin/faq-edit-form.tsx
'use client';
import { useState } from 'react';
 
interface FaqEditFormProps {
  faq: Faq & { category?: { id: string; slug: string; title: string } };
  onSave: (updatedFaq: Partial<Faq>) => Promise<void>;
  onCancel: () => void;
}
 
export default function FaqEditForm({ faq, onSave, onCancel }: FaqEditFormProps) {
  const [question, setQuestion] = useState(faq.question);
  const [answer, setAnswer] = useState(faq.answer);
  const [isActive, setIsActive] = useState(faq.isActive);
  const [sortOrder, setSortOrder] = useState(faq.sortOrder);
  const [isSaving, setIsSaving] = useState(false);
 
  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setIsSaving(true);
    try {
      await onSave({ question, answer, isActive, sortOrder });
    } catch (error) {
      console.error('Erro ao salvar FAQ:', error);
    } finally {
      setIsSaving(false);
    }
  };
  // ... JSX do formulário
}

O que isso demonstra em produção:

• O TypeScript infere o tipo de cada variável de estado a partir do valor inicial passado para useState. Nenhum genérico explícito é necessário para useState(faq.question), pois faq.question já é do tipo string.
• O bloco finally garante que isSaving seja redefinido para false em caso de sucesso e falha. Sem ele, uma falha ao salvar deixaria o formulário preso em um estado de carregamento.
• Partial<Faq> significa que apenas os campos alterados são enviados para o manipulador de salvamento, não o objeto FAQ inteiro. Isso mantém a chamada da API enxuta.
• Cinco chamadas useState separadas funcionam bem para um formulário deste tamanho. Para formulários com mais de 6-8 campos, considere useReducer ou uma biblioteca de formulários como react-hook-form para reduzir o boilerplate e habilitar a validação em nível de campo.
• A flag isSaving é usada para desabilitar o botão de envio durante a operação assíncrona, evitando o duplo envio.

FAQs

const [form, setForm] = useState({ name: "", email: "" });
 
// Correto: usa spread para criar uma nova referência
setForm(prev => ({ ...prev, name: "Alice" }));
 
// Errado: mutando o objeto existente
form.name = "Alice"; // Nenhuma re-renderização

// Use um genérico explícito para tipos de união
const [user, setUser] = useState<User | null>(null);
 
// Mais tarde, o TypeScript sabe que user pode ser nulo
if (user) {
  console.log(user.name); // estreitado para User
}

// Sem o genérico, o TypeScript infere never[]
const [items, setItems] = useState<string[]>([]);
 
// Agora você pode adicionar strings
setItems(prev => [...prev, "new item"]);

Relacionados

• useReducer - para lógica de estado complexa com ações
• useRef - para valores mutáveis que não acionam re-renderizações
• Configuração do Zustand - quando o estado precisa ser compartilhado globalmente