useReducer Multi-Step Forms

Q: Como persisto o estado do formulário entre as navegações de página?

Use o inicializador preguiçoso (terceiro argumento para useReducer) para carregar do localStorage Salve o estado no localStorage em um useEffect que é executado a cada mudança de estado Alternativamente, eleve o reducer para um provedor de contexto que envolva o grupo de rotas Para estado persistido na URL, serialize a etapa e os campos-chave nos parâmetros de busca

Q: Como valido apenas a etapa atual?

Escreva uma função validateStep(stepIndex, fields) que verifica apenas os campos relevantes para essa etapa Chame-a em handleNext antes de despachar NEXT_STEP Se erros forem encontrados, despache VALIDATE com os erros e retorne cedo Isso evita que os usuários sejam bloqueados por erros em etapas que ainda não alcançaram

Q: Como lido com etapas condicionais/de ramificação?

Adicione lógica de ramificação dentro do caso NEXT_STEP do reducer Verifique os valores dos campos para determinar para qual índice de etapa pular Exemplo: pule a etapa de pagamento se plan === "free" incrementando a etapa em 2 Mantenha um array ou mapa de steps para que a barra de progresso reflita o caminho real

Q: Por que dispatch não atualiza o estado imediatamente?

dispatch agenda uma re-renderização - state reflete o novo valor na próxima renderização, não de forma síncrona Se você precisar agir sobre o "novo" valor, calcule-o você mesmo: const nextStep = step + 1; dispatch(...) e depois use nextStep Alternativamente, use um useEffect que reaja às mudanças de estado Este é o mesmo comportamento de agrupamento do useState - não é exclusivo do useReducer

Q: Como evito uma instrução switch massiva no reducer?

Extraia cada caso em uma função manipuladora nomeada: case "SET_FIELD": return handleSetField(state, action); Agrupe ações relacionadas em sub-reducers se o formulário tiver seções distintas Considere um mapa de manipuladores: const handlers: Record = { SET_FIELD: handleSetField, ... } Se o reducer exceder ~50 linhas, é um sinal para dividi-lo

Q: Posso usar Immer com useReducer para atualizações mais simples?

Sim - envolva seu reducer com produce do Immer: const reducer = produce((draft, action) => { draft.fields.name = action.value; }) Isso permite que você escreva código "mutável" que produz atualizações imutáveis nos bastidores Especialmente útil quando o estado é profundamente aninhado (por exemplo, state.steps[2].fields.address.city) Adiciona ~5KB, mas elimina a repetição de espalhamento em todos os níveis

Gerencie o estado complexo de formulários multi-etapas com useReducer - ações explícitas como SET_FIELD, NEXT_STEP e VALIDATE tornam as transições de estado previsíveis, testáveis e fáceis de depurar sem a necessidade de bibliotecas externas.

Receita

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

"use client";
 
import { useReducer } from "react";
 
interface FormState {
  step: number;
  fields: Record<string, string>;
  errors: Record<string, string>;
}
 
type FormAction =
  | { type: "SET_FIELD"; name: string; value: string }
  | { type: "NEXT_STEP" }
  | { type: "PREV_STEP" }
  | { type: "VALIDATE"; errors: Record<string, string> }
  | { type: "RESET" };
 
function formReducer(state: FormState, action: FormAction): FormState {
  switch (action.type) {
    case "SET_FIELD":
      return { ...state, fields: { ...state.fields, [action.name]: action.value }, errors: {} };
    case "NEXT_STEP":
      return { ...state, step: state.step + 1, errors: {} };
    case "PREV_STEP":
      return { ...state, step: Math.max(0, state.step - 1) };
    case "VALIDATE":
      return { ...state, errors: action.errors };
    case "RESET":
      return { step: 0, fields: {}, errors: {} };
  }
}

Quando usar isso: Quando seu formulário tem 3+ etapas, validação entre etapas ou transições de estado complexas o suficiente para que o gerenciamento de várias chamadas useState se torne propenso a erros.

Exemplo Funcional

"use client";
 
import { useReducer } from "react";
 
// --- Tipos ---
 
interface FormState {
  step: number;
  totalSteps: number;
  fields: {
    name: string;
    email: string;
    company: string;
    role: string;
    plan: string;
    cardNumber: string;
    agree: boolean;
  };
  errors: Record<string, string>;
  submitted: boolean;
}
 
type FormAction =
  | { type: "SET_FIELD"; name: keyof FormState["fields"]; value: string | boolean }
  | { type: "NEXT_STEP" }
  | { type: "PREV_STEP" }
  | { type: "VALIDATE"; errors: Record<string, string> }
  | { type: "SUBMIT" }
  | { type: "RESET" };
 
// --- Estado inicial ---
 
const initialState: FormState = {
  step: 0,
  totalSteps: 3,
  fields: {
    name: "",
    email: "",
    company: "",
    role: "",
    plan: "free",
    cardNumber: "",
    agree: false,
  },
  errors: {},
  submitted: false,
};
 
// --- Reducer (função pura - fácil de testar unitariamente) ---
 
function formReducer(state: FormState, action: FormAction): FormState {
  switch (action.type) {
    case "SET_FIELD":
      return {
        ...state,
        fields: { ...state.fields, [action.name]: action.value },
        errors: { ...state.errors, [action.name]: "" },
      };
    case "NEXT_STEP":
      return { ...state, step: state.step + 1, errors: {} };
    case "PREV_STEP":
      return { ...state, step: Math.max(0, state.step - 1), errors: {} };
    case "VALIDATE":
      return { ...state, errors: action.errors };
    case "SUBMIT":
      return { ...state, submitted: true };
    case "RESET":
      return initialState;
  }
}
 
// --- Validação por etapa ---
 
function validateStep(step: number, fields: FormState["fields"]): Record<string, string> {
  const errors: Record<string, string> = {};
 
  if (step === 0) {
    if (!fields.name.trim()) errors.name = "O nome é obrigatório";
    if (!fields.email.includes("@")) errors.email = "Um e-mail válido é obrigatório";
  }
 
  if (step === 1) {
    if (!fields.company.trim()) errors.company = "A empresa é obrigatória";
    if (!fields.role.trim()) errors.role = "A função é obrigatória";
  }
 
  if (step === 2) {
    if (fields.plan !== "free" && fields.cardNumber.length < 16)
      errors.cardNumber = "Um número de cartão válido é necessário para planos pagos";
    if (!fields.agree) errors.agree = "Você deve concordar com os termos";
  }
 
  return errors;
}
 
// --- Componente ---
 
export default function MultiStepSignup() {
  const [state, dispatch] = useReducer(formReducer, initialState);
  const { step, totalSteps, fields, errors, submitted } = state;
 
  function handleNext() {
    const stepErrors = validateStep(step, fields);
    if (Object.keys(stepErrors).length > 0) {
      dispatch({ type: "VALIDATE", errors: stepErrors });
      return;
    }
    if (step < totalSteps - 1) {
      dispatch({ type: "NEXT_STEP" });
    } else {
      dispatch({ type: "SUBMIT" });
    }
  }
 
  if (submitted) {
    return (
      <div className="rounded-lg bg-green-50 p-8 text-center">
        <h2 className="text-xl font-semibold text-green-800">Bem-vindo(a), {fields.name}!</h2>
        <p className="mt-2 text-green-600">Seu plano {fields.plan} está ativo.</p>
        <button
          onClick={() => dispatch({ type: "RESET" })}
          className="mt-4 rounded bg-green-600 px-4 py-2 text-white"
        >
          Começar de novo
        </button>
      </div>
    );
  }
 
  return (
    <div className="mx-auto max-w-md">
      {/* Barra de progresso */}
      <div className="mb-6 flex gap-2">
        {Array.from({ length: totalSteps }, (_, i) => (
          <div
            key={i}
            className={`h-2 flex-1 rounded ${i <= step ? "bg-blue-600" : "bg-gray-200"}`}
          />
        ))}
      </div>
 
      {/* Etapa 0: Informações Pessoais */}
      {step === 0 && (
        <div className="space-y-4">
          <h2 className="text-lg font-semibold">Informações Pessoais</h2>
          <div>
            <input
              type="text"
              placeholder="Nome completo"
              value={fields.name}
              onChange={(e) => dispatch({ type: "SET_FIELD", name: "name", value: e.target.value })}
              className="w-full rounded border p-2"
            />
            {errors.name && <p className="mt-1 text-sm text-red-600">{errors.name}</p>}
          </div>
          <div>
            <input
              type="email"
              placeholder="E-mail"
              value={fields.email}
              onChange={(e) => dispatch({ type: "SET_FIELD", name: "email", value: e.target.value })}
              className="w-full rounded border p-2"
            />
            {errors.email && <p className="mt-1 text-sm text-red-600">{errors.email}</p>}
          </div>
        </div>
      )}
 
      {/* Etapa 1: Informações da Empresa */}
      {step === 1 && (
        <div className="space-y-4">
          <h2 className="text-lg font-semibold">Detalhes da Empresa</h2>
          <div>
            <input
              type="text"
              placeholder="Empresa"
              value={fields.company}
              onChange={(e) =>
                dispatch({ type: "SET_FIELD", name: "company", value: e.target.value })
              }
              className="w-full rounded border p-2"
            />
            {errors.company && <p className="mt-1 text-sm text-red-600">{errors.company}</p>}
          </div>
          <div>
            <input
              type="text"
              placeholder="Função"
              value={fields.role}
              onChange={(e) => dispatch({ type: "SET_FIELD", name: "role", value: e.target.value })}
              className="w-full rounded border p-2"
            />
            {errors.role && <p className="mt-1 text-sm text-red-600">{errors.role}</p>}
          </div>
        </div>
      )}
 
      {/* Etapa 2: Plano e Pagamento */}
      {step === 2 && (
        <div className="space-y-4">
          <h2 className="text-lg font-semibold">Escolha o Plano</h2>
          <select
            value={fields.plan}
            onChange={(e) => dispatch({ type: "SET_FIELD", name: "plan", value: e.target.value })}
            className="w-full rounded border p-2"
          >
            <option value="free">Grátis</option>
            <option value="pro">Pro - R$19/mês</option>
            <option value="enterprise">Enterprise - R$99/mês</option>
          </select>
          {fields.plan !== "free" && (
            <div>
              <input
                type="text"
                placeholder="Número do cartão"
                value={fields.cardNumber}
                onChange={(e) =>
                  dispatch({ type: "SET_FIELD", name: "cardNumber", value: e.target.value })
                }
                className="w-full rounded border p-2"
              />
              {errors.cardNumber && (
                <p className="mt-1 text-sm text-red-600">{errors.cardNumber}</p>
              )}
            </div>
          )}
          <label className="flex items-center gap-2">
            <input
              type="checkbox"
              checked={fields.agree as boolean}
              onChange={(e) =>
                dispatch({ type: "SET_FIELD", name: "agree", value: e.target.checked })
              }
            />
            <span className="text-sm">Concordo com os termos de serviço</span>
          </label>
          {errors.agree && <p className="mt-1 text-sm text-red-600">{errors.agree}</p>}
        </div>
      )}
 
      {/* Navegação */}
      <div className="mt-6 flex justify-between">
        <button
          onClick={() => dispatch({ type: "PREV_STEP" })}
          disabled={step === 0}
          className="rounded bg-gray-200 px-4 py-2 disabled:opacity-50"
        >
          Voltar
        </button>
        <button onClick={handleNext} className="rounded bg-blue-600 px-4 py-2 text-white">
          {step === totalSteps - 1 ? "Enviar" : "Próximo"}
        </button>
      </div>
    </div>
  );
}

O que isso demonstra:

Todo o estado do formulário em um único useReducer - índice da etapa, valores dos campos, erros e status de envio
Validação por etapa que é executada apenas ao clicar em "Próximo" - os usuários não são bloqueados por erros em etapas futuras
SET_FIELD limpa o erro para aquele campo específico, fornecendo feedback inline
O reducer é uma função pura sem efeitos colaterais, tornando-o trivialmente testável unitariamente
A ação RESET retorna ao initialState - sem risco de estado parcial desatualizado

Análise Detalhada

Como Funciona

useReducer aceita uma função reducer pura e um estado inicial, retornando o estado atual e uma função dispatch
Cada mudança de estado é uma ação explícita com uma string type - você pode registrar, reproduzir ou desfazer ações
O reducer centraliza todas as transições de estado em um único local, eliminando chamadas setState dispersas que podem ficar dessincronizadas
O React agrupa múltiplos dispatches no mesmo manipulador de eventos em uma única re-renderização

Por que usar useReducer em vez de useState para Formulários Multi-Etapas

Preocupação	`useState` (múltiplos)	`useReducer`
Transições de estado	Espalhadas pelos manipuladores	Centralizadas no reducer
Teste	Precisa montar o componente	Testar o reducer como função pura
Depuração	Verificar cada setter	Registrar ações despachadas
Atualizações coordenadas	Risco de atualizações parciais	Dispatch atômico único
Adicionar novos campos	Outra chamada `useState`	Adicionar à interface de estado

O Padrão de Ação

Defina uma união discriminada para ações type-safe:

type FormAction =
  | { type: "SET_FIELD"; name: string; value: string }
  | { type: "NEXT_STEP" }
  | { type: "PREV_STEP" }
  | { type: "SET_ERRORS"; errors: Record<string, string> }
  | { type: "SUBMIT" }
  | { type: "RESET" };

O TypeScript restringe a ação dentro de cada branch case - action.name só está acessível dentro do caso SET_FIELD.

Combinando com Server Actions

"use client";
 
import { useReducer, useTransition } from "react";
import { submitSignup } from "./actions";
 
function MultiStepForm() {
  const [state, dispatch] = useReducer(formReducer, initialState);
  const [isPending, startTransition] = useTransition();
 
  async function handleSubmit() {
    const errors = validateStep(state.step, state.fields);
    if (Object.keys(errors).length > 0) {
      dispatch({ type: "VALIDATE", errors });
      return;
    }
 
    startTransition(async () => {
      const result = await submitSignup(state.fields);
      if (result.errors) {
        dispatch({ type: "VALIDATE", errors: result.errors });
      } else {
        dispatch({ type: "SUBMIT" });
      }
    });
  }
 
  return (
    <button onClick={handleSubmit} disabled={isPending}>
      {isPending ? "Enviando..." : "Enviar"}
    </button>
  );
}

Variações

Assistente de ramificação (etapas condicionais):

function formReducer(state: FormState, action: FormAction): FormState {
  switch (action.type) {
    case "NEXT_STEP": {
      // Pula a etapa de pagamento se o plano for "free"
      const nextStep = state.step === 1 && state.fields.plan === "free"
        ? state.step + 2
        : state.step + 1;
      return { ...state, step: nextStep, errors: {} };
    }
    // ... outros casos
  }
}

Desfazer/Refazer com histórico de ações:

interface FormStateWithHistory {
  past: FormState[];
  present: FormState;
  future: FormState[];
}
 
type HistoryAction = FormAction | { type: "UNDO" } | { type: "REDO" };
 
function undoableReducer(state: FormStateWithHistory, action: HistoryAction): FormStateWithHistory {
  if (action.type === "UNDO") {
    const previous = state.past[state.past.length - 1];
    if (!previous) return state;
    return {
      past: state.past.slice(0, -1),
      present: previous,
      future: [state.present, ...state.future],
    };
  }
  if (action.type === "REDO") {
    const next = state.future[0];
    if (!next) return state;
    return {
      past: [...state.past, state.present],
      present: next,
      future: state.future.slice(1),
    };
  }
  return {
    past: [...state.past, state.present],
    present: formReducer(state.present, action),
    future: [],
  };
}

Inicialização preguiçosa para rascunhos salvos:

function initFromStorage(defaultState: FormState): FormState {
  if (typeof window === "undefined") return defaultState;
  const saved = localStorage.getItem("signup-draft");
  return saved ? JSON.parse(saved) : defaultState;
}
 
const [state, dispatch] = useReducer(formReducer, initialState, initFromStorage);

Notas TypeScript

// Nomes de campo fortemente tipados - captura erros de digitação em tempo de compilação
interface SignupFields {
  name: string;
  email: string;
  plan: "free" | "pro" | "enterprise";
}
 
type SetFieldAction = {
  [K in keyof SignupFields]: { type: "SET_FIELD"; name: K; value: SignupFields[K] };
}[keyof SignupFields];
 
// Agora dispatch({ type: "SET_FIELD", name: "plan", value: "invalid" }) é um erro de tipo
 
// Contexto de dispatch tipado para evitar prop drilling
import { createContext, useContext, type Dispatch } from "react";
 
const FormDispatchContext = createContext<Dispatch<FormAction> | null>(null);
 
function useFormDispatch(): Dispatch<FormAction> {
  const dispatch = useContext(FormDispatchContext);
  if (!dispatch) throw new Error("useFormDispatch must be used within FormProvider");
  return dispatch;
}

Teste Unitário do Reducer

import { describe, it, expect } from "vitest";
 
describe("formReducer", () => {
  const initial: FormState = { step: 0, fields: { name: "", email: "" }, errors: {} };
 
  it("define o valor de um campo", () => {
    const next = formReducer(initial, { type: "SET_FIELD", name: "name", value: "Alice" });
    expect(next.fields.name).toBe("Alice");
  });
 
  it("avança para a próxima etapa", () => {
    const next = formReducer(initial, { type: "NEXT_STEP" });
    expect(next.step).toBe(1);
    expect(next.errors).toEqual({});
  });
 
  it("limpa o erro do campo em SET_FIELD", () => {
    const withError = { ...initial, errors: { name: "Obrigatório" } };
    const next = formReducer(withError, { type: "SET_FIELD", name: "name", value: "Alice" });
    expect(next.errors.name).toBe("");
  });
 
  it("não vai abaixo da etapa 0", () => {
    const next = formReducer(initial, { type: "PREV_STEP" });
    expect(next.step).toBe(0);
  });
 
  it("reseta para o estado inicial", () => {
    const modified = { step: 2, fields: { name: "Alice", email: "a@b.com" }, errors: {} };
    const next = formReducer(modified, { type: "RESET" });
    expect(next).toEqual(initial);
  });
});

Armadilhas

Estado desatualizado em callbacks assíncronos - Se você ler state dentro de um setTimeout ou await, obterá o valor no momento do dispatch, não o mais recente. Correção: Use useRef para espelhar o estado atual ou despache uma ação do callback assíncrono em vez de ler o estado.
O spread de objeto cria apenas cópias rasas - Objetos aninhados (como fields dentro de state) também devem ser espalhados: { ...state, fields: { ...state.fields, [name]: value } }. Correção: Sempre espalhe em todos os níveis de aninhamento que você está modificando, ou use produce do Immer.
Esquecer de limpar erros ao alterar um campo - O usuário corrige o erro, mas a mensagem permanece. Correção: Limpe o erro do campo específico dentro de SET_FIELD, como mostrado no exemplo funcional.
O reducer deve ser puro - Sem chamadas de API, sem leituras de localStorage, sem Date.now() dentro do reducer. Correção: Execute efeitos colaterais no componente ou manipulador de eventos, em seguida, despache o resultado.
A validação é executada contra o estado desatualizado após o dispatch - dispatch não atualiza state de forma síncrona. Chamar dispatch({ type: "SET_FIELD" }) e depois ler state.fields retorna o valor antigo. Correção: Valide usando o valor que você está prestes a despachar, não o state atual.
Reducers grandes se tornam difíceis de ler - Uma instrução switch de 200 linhas é pior do que 8 chamadas useState. Correção: Extraia os manipuladores de casos em funções nomeadas: case "SET_FIELD": return handleSetField(state, action);.
Caso default ausente no switch - O TypeScript não avisará se você esquecer um caso, a menos que adicione verificação exaustiva. Correção: Adicione default: { const _exhaustive: never = action; return state; } para capturar ações não tratadas em tempo de compilação.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Múltiplos `useState`	O formulário tem 1-3 campos, sem multi-etapas	As transições de estado são coordenadas entre os campos
React Hook Form	Você precisa de validação integrada, gerenciamento de foco e registro de campos	Você quer controle total sobre a forma e as transições do estado
Zustand / Jotai	O estado do formulário deve persistir entre rotas ou ser compartilhado globalmente	O estado é local para uma árvore de componentes
XState	O formulário tem lógica de ramificação complexa (pular etapas, loops, estados paralelos)	Um assistente linear com validação simples
`useActionState`	Formulário com Server Actions com estado pendente/erro	Assistente multi-etapas no lado do cliente sem viagem de ida e volta do servidor por etapa

FAQs

Quando devo usar useReducer em vez de useState para formulários?

Quando o formulário tem 4+ campos com estado interdependente (por exemplo, alterar um campo afeta a validação de outro)
Quando você tem navegação multi-etapas onde etapa, campos e erros devem permanecer sincronizados
Quando você deseja testar unitariamente as transições de estado sem montar um componente React
Quando vários manipuladores de eventos precisam atualizar o mesmo estado de maneiras diferentes
Regra geral: se você se encontrar chamando 3+ funções setState em um manipulador, mude para useReducer

Posso usar useReducer com Server Actions?

Sim - gerencie o estado do assistente no lado do cliente com useReducer, em seguida, chame a Server Action na submissão final
Envolva a chamada da Server Action em startTransition para obter o estado pendente via useTransition
Despache uma ação VALIDATE com os erros retornados pelo servidor para exibi-los na etapa atual
useActionState lida melhor com formulários de servidor de etapa única; useReducer é para assistentes multi-etapas no cliente

Como persisto o estado do formulário entre as navegações de página?

Use o inicializador preguiçoso (terceiro argumento para useReducer) para carregar do localStorage
Salve o estado no localStorage em um useEffect que é executado a cada mudança de estado
Alternativamente, eleve o reducer para um provedor de contexto que envolva o grupo de rotas
Para estado persistido na URL, serialize a etapa e os campos-chave nos parâmetros de busca

Como valido apenas a etapa atual?

Escreva uma função validateStep(stepIndex, fields) que verifica apenas os campos relevantes para essa etapa
Chame-a em handleNext antes de despachar NEXT_STEP
Se erros forem encontrados, despache VALIDATE com os erros e retorne cedo
Isso evita que os usuários sejam bloqueados por erros em etapas que ainda não alcançaram

O reducer deve lidar com operações assíncronas como chamadas de API?

Não - reducers devem ser funções puras sem efeitos colaterais
Execute o trabalho assíncrono no manipulador de eventos ou useEffect, em seguida, despache o resultado
Exemplo: const result = await saveStep(fields); dispatch({ type: "SAVE_SUCCESS", data: result });
Isso mantém o reducer testável e previsível

Como lido com etapas condicionais/de ramificação?

Adicione lógica de ramificação dentro do caso NEXT_STEP do reducer
Verifique os valores dos campos para determinar para qual índice de etapa pular
Exemplo: pule a etapa de pagamento se plan === "free" incrementando a etapa em 2
Mantenha um array ou mapa de steps para que a barra de progresso reflita o caminho real

Como faço o TypeScript capturar casos de ação ausentes?

Use uma união discriminada para o seu tipo de ação
Adicione verificação exaustiva no caso default: const _exhaustive: never = action; return state;
O TypeScript gerará um erro em tempo de compilação se você adicionar um novo tipo de ação, mas esquecer de tratá-lo
Isso é mais seguro do que um default: return state simples que ignora silenciosamente ações desconhecidas

Por que dispatch não atualiza o estado imediatamente?

dispatch agenda uma re-renderização - state reflete o novo valor na próxima renderização, não de forma síncrona
Se você precisar agir sobre o "novo" valor, calcule-o você mesmo: const nextStep = step + 1; dispatch(...) e depois use nextStep
Alternativamente, use um useEffect que reaja às mudanças de estado
Este é o mesmo comportamento de agrupamento do useState - não é exclusivo do useReducer

Como evito uma instrução switch massiva no reducer?

Extraia cada caso em uma função manipuladora nomeada: case "SET_FIELD": return handleSetField(state, action);
Agrupe ações relacionadas em sub-reducers se o formulário tiver seções distintas
Considere um mapa de manipuladores: const handlers: Record<string, Handler> = { SET_FIELD: handleSetField, ... }
Se o reducer exceder ~50 linhas, é um sinal para dividi-lo

Posso usar Immer com useReducer para atualizações mais simples?

Sim - envolva seu reducer com produce do Immer: const reducer = produce((draft, action) => { draft.fields.name = action.value; })
Isso permite que você escreva código "mutável" que produz atualizações imutáveis nos bastidores
Especialmente útil quando o estado é profundamente aninhado (por exemplo, state.steps[2].fields.address.city)
Adiciona ~5KB, mas elimina a repetição de espalhamento em todos os níveis

Como isso se compara ao XState para formulários de assistente?

useReducer é mais simples: apenas uma instrução switch, sem biblioteca, sem curva de aprendizado
XState é melhor quando as etapas podem ramificar, loop ou rodar em paralelo (comportamento real de máquina de estados)
useReducer lida bem com assistentes lineares e de ramificação simples
Se você se encontrar adicionando booleanos canGoToStep3, considere atualizar para XState

Qual é o tipo TypeScript para a função dispatch?

React.Dispatch<FormAction> - onde FormAction é sua união discriminada
Passe-o através do contexto: createContext<Dispatch<FormAction> | null>(null)
Crie um hook tipado: function useFormDispatch() { const d = useContext(Ctx); if (!d) throw ...; return d; }
Isso evita o prop-drilling de dispatch através de muitos níveis de componentes

Relacionados

Padrões de Formulário Básico - Inputs controlados, formulários de etapa única com useState
Padrões de Formulário Complexos - Assistentes multi-etapas usando React Hook Form
Formulários com Server Actions - Melhoria progressiva com useActionState
Exibição de Erros de Formulário - Padrões para exibir erros de validação
React Hook Form - Gerenciamento de formulários baseado em biblioteca como alternativa

Receita

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

"use client";
 
import { useReducer } from "react";
 
interface FormState {
  step: number;
  fields: Record<string, string>;
  errors: Record<string, string>;
}
 
type FormAction =
  | { type: "SET_FIELD"; name: string; value: string }
  | { type: "NEXT_STEP" }
  | { type: "PREV_STEP" }
  | { type: "VALIDATE"; errors: Record<string, string> }
  | { type: "RESET" };
 
function formReducer(state: FormState, action: FormAction): FormState {
  switch (action.type) {
    case "SET_FIELD":
      return { ...state, fields: { ...state.fields, [action.name]: action.value }, errors: {} };
    case "NEXT_STEP":
      return { ...state, step: state.step + 1, errors: {} };
    case "PREV_STEP":
      return { ...state, step: Math.max(0, state.step - 1) };
    case "VALIDATE":
      return { ...state, errors: action.errors };
    case "RESET":
      return { step: 0, fields: {}, errors: {} };
  }
}

Exemplo Funcional

"use client";
 
import { useReducer } from "react";
 
// --- Tipos ---
 
interface FormState {
  step: number;
  totalSteps: number;
  fields: {
    name: string;
    email: string;
    company: string;
    role: string;
    plan: string;
    cardNumber: string;
    agree: boolean;
  };
  errors: Record<string, string>;
  submitted: boolean;
}
 
type FormAction =
  | { type: "SET_FIELD"; name: keyof FormState["fields"]; value: string | boolean }
  | { type: "NEXT_STEP" }
  | { type: "PREV_STEP" }
  | { type: "VALIDATE"; errors: Record<string, string> }
  | { type: "SUBMIT" }
  | { type: "RESET" };
 
// --- Estado inicial ---
 
const initialState: FormState = {
  step: 0,
  totalSteps: 3,
  fields: {
    name: "",
    email: "",
    company: "",
    role: "",
    plan: "free",
    cardNumber: "",
    agree: false,
  },
  errors: {},
  submitted: false,
};
 
// --- Reducer (função pura - fácil de testar unitariamente) ---
 
function formReducer(state: FormState, action: FormAction): FormState {
  switch (action.type) {
    case "SET_FIELD":
      return {
        ...state,
        fields: { ...state.fields, [action.name]: action.value },
        errors: { ...state.errors, [action.name]: "" },
      };
    case "NEXT_STEP":
      return { ...state, step: state.step + 1, errors: {} };
    case "PREV_STEP":
      return { ...state, step: Math.max(0, state.step - 1), errors: {} };
    case "VALIDATE":
      return { ...state, errors: action.errors };
    case "SUBMIT":
      return { ...state, submitted: true };
    case "RESET":
      return initialState;
  }
}
 
// --- Validação por etapa ---
 
function validateStep(step: number, fields: FormState["fields"]): Record<string, string> {
  const errors: Record<string, string> = {};
 
  if (step === 0) {
    if (!fields.name.trim()) errors.name = "O nome é obrigatório";
    if (!fields.email.includes("@")) errors.email = "Um e-mail válido é obrigatório";
  }
 
  if (step === 1) {
    if (!fields.company.trim()) errors.company = "A empresa é obrigatória";
    if (!fields.role.trim()) errors.role = "A função é obrigatória";
  }
 
  if (step === 2) {
    if (fields.plan !== "free" && fields.cardNumber.length < 16)
      errors.cardNumber = "Um número de cartão válido é necessário para planos pagos";
    if (!fields.agree) errors.agree = "Você deve concordar com os termos";
  }
 
  return errors;
}
 
// --- Componente ---
 
export default function MultiStepSignup() {
  const [state, dispatch] = useReducer(formReducer, initialState);
  const { step, totalSteps, fields, errors, submitted } = state;
 
  function handleNext() {
    const stepErrors = validateStep(step, fields);
    if (Object.keys(stepErrors).length > 0) {
      dispatch({ type: "VALIDATE", errors: stepErrors });
      return;
    }
    if (step < totalSteps - 1) {
      dispatch({ type: "NEXT_STEP" });
    } else {
      dispatch({ type: "SUBMIT" });
    }
  }
 
  if (submitted) {
    return (
      <div className="rounded-lg bg-green-50 p-8 text-center">
        <h2 className="text-xl font-semibold text-green-800">Bem-vindo(a), {fields.name}!</h2>
        <p className="mt-2 text-green-600">Seu plano {fields.plan} está ativo.</p>
        <button
          onClick={() => dispatch({ type: "RESET" })}
          className="mt-4 rounded bg-green-600 px-4 py-2 text-white"
        >
          Começar de novo
        </button>
      </div>
    );
  }
 
  return (
    <div className="mx-auto max-w-md">
      {/* Barra de progresso */}
      <div className="mb-6 flex gap-2">
        {Array.from({ length: totalSteps }, (_, i) => (
          <div
            key={i}
            className={`h-2 flex-1 rounded ${i <= step ? "bg-blue-600" : "bg-gray-200"}`}
          />
        ))}
      </div>
 
      {/* Etapa 0: Informações Pessoais */}
      {step === 0 && (
        <div className="space-y-4">
          <h2 className="text-lg font-semibold">Informações Pessoais</h2>
          <div>
            <input
              type="text"
              placeholder="Nome completo"
              value={fields.name}
              onChange={(e) => dispatch({ type: "SET_FIELD", name: "name", value: e.target.value })}
              className="w-full rounded border p-2"
            />
            {errors.name && <p className="mt-1 text-sm text-red-600">{errors.name}</p>}
          </div>
          <div>
            <input
              type="email"
              placeholder="E-mail"
              value={fields.email}
              onChange={(e) => dispatch({ type: "SET_FIELD", name: "email", value: e.target.value })}
              className="w-full rounded border p-2"
            />
            {errors.email && <p className="mt-1 text-sm text-red-600">{errors.email}</p>}
          </div>
        </div>
      )}
 
      {/* Etapa 1: Informações da Empresa */}
      {step === 1 && (
        <div className="space-y-4">
          <h2 className="text-lg font-semibold">Detalhes da Empresa</h2>
          <div>
            <input
              type="text"
              placeholder="Empresa"
              value={fields.company}
              onChange={(e) =>
                dispatch({ type: "SET_FIELD", name: "company", value: e.target.value })
              }
              className="w-full rounded border p-2"
            />
            {errors.company && <p className="mt-1 text-sm text-red-600">{errors.company}</p>}
          </div>
          <div>
            <input
              type="text"
              placeholder="Função"
              value={fields.role}
              onChange={(e) => dispatch({ type: "SET_FIELD", name: "role", value: e.target.value })}
              className="w-full rounded border p-2"
            />
            {errors.role && <p className="mt-1 text-sm text-red-600">{errors.role}</p>}
          </div>
        </div>
      )}
 
      {/* Etapa 2: Plano e Pagamento */}
      {step === 2 && (
        <div className="space-y-4">
          <h2 className="text-lg font-semibold">Escolha o Plano</h2>
          <select
            value={fields.plan}
            onChange={(e) => dispatch({ type: "SET_FIELD", name: "plan", value: e.target.value })}
            className="w-full rounded border p-2"
          >
            <option value="free">Grátis</option>
            <option value="pro">Pro - R$19/mês</option>
            <option value="enterprise">Enterprise - R$99/mês</option>
          </select>
          {fields.plan !== "free" && (
            <div>
              <input
                type="text"
                placeholder="Número do cartão"
                value={fields.cardNumber}
                onChange={(e) =>
                  dispatch({ type: "SET_FIELD", name: "cardNumber", value: e.target.value })
                }
                className="w-full rounded border p-2"
              />
              {errors.cardNumber && (
                <p className="mt-1 text-sm text-red-600">{errors.cardNumber}</p>
              )}
            </div>
          )}
          <label className="flex items-center gap-2">
            <input
              type="checkbox"
              checked={fields.agree as boolean}
              onChange={(e) =>
                dispatch({ type: "SET_FIELD", name: "agree", value: e.target.checked })
              }
            />
            <span className="text-sm">Concordo com os termos de serviço</span>
          </label>
          {errors.agree && <p className="mt-1 text-sm text-red-600">{errors.agree}</p>}
        </div>
      )}
 
      {/* Navegação */}
      <div className="mt-6 flex justify-between">
        <button
          onClick={() => dispatch({ type: "PREV_STEP" })}
          disabled={step === 0}
          className="rounded bg-gray-200 px-4 py-2 disabled:opacity-50"
        >
          Voltar
        </button>
        <button onClick={handleNext} className="rounded bg-blue-600 px-4 py-2 text-white">
          {step === totalSteps - 1 ? "Enviar" : "Próximo"}
        </button>
      </div>
    </div>
  );
}

O que isso demonstra:

Todo o estado do formulário em um único useReducer - índice da etapa, valores dos campos, erros e status de envio
Validação por etapa que é executada apenas ao clicar em "Próximo" - os usuários não são bloqueados por erros em etapas futuras
SET_FIELD limpa o erro para aquele campo específico, fornecendo feedback inline
O reducer é uma função pura sem efeitos colaterais, tornando-o trivialmente testável unitariamente
A ação RESET retorna ao initialState - sem risco de estado parcial desatualizado

Análise Detalhada

Como Funciona

useReducer aceita uma função reducer pura e um estado inicial, retornando o estado atual e uma função dispatch
Cada mudança de estado é uma ação explícita com uma string type - você pode registrar, reproduzir ou desfazer ações
O reducer centraliza todas as transições de estado em um único local, eliminando chamadas setState dispersas que podem ficar dessincronizadas
O React agrupa múltiplos dispatches no mesmo manipulador de eventos em uma única re-renderização

Por que usar useReducer em vez de useState para Formulários Multi-Etapas

Preocupação	`useState` (múltiplos)	`useReducer`
Transições de estado	Espalhadas pelos manipuladores	Centralizadas no reducer
Teste	Precisa montar o componente	Testar o reducer como função pura
Depuração	Verificar cada setter	Registrar ações despachadas
Atualizações coordenadas	Risco de atualizações parciais	Dispatch atômico único
Adicionar novos campos	Outra chamada `useState`	Adicionar à interface de estado

O Padrão de Ação

Defina uma união discriminada para ações type-safe:

type FormAction =
  | { type: "SET_FIELD"; name: string; value: string }
  | { type: "NEXT_STEP" }
  | { type: "PREV_STEP" }
  | { type: "SET_ERRORS"; errors: Record<string, string> }
  | { type: "SUBMIT" }
  | { type: "RESET" };

O TypeScript restringe a ação dentro de cada branch case - action.name só está acessível dentro do caso SET_FIELD.

Combinando com Server Actions

"use client";
 
import { useReducer, useTransition } from "react";
import { submitSignup } from "./actions";
 
function MultiStepForm() {
  const [state, dispatch] = useReducer(formReducer, initialState);
  const [isPending, startTransition] = useTransition();
 
  async function handleSubmit() {
    const errors = validateStep(state.step, state.fields);
    if (Object.keys(errors).length > 0) {
      dispatch({ type: "VALIDATE", errors });
      return;
    }
 
    startTransition(async () => {
      const result = await submitSignup(state.fields);
      if (result.errors) {
        dispatch({ type: "VALIDATE", errors: result.errors });
      } else {
        dispatch({ type: "SUBMIT" });
      }
    });
  }
 
  return (
    <button onClick={handleSubmit} disabled={isPending}>
      {isPending ? "Enviando..." : "Enviar"}
    </button>
  );
}

Variações

Assistente de ramificação (etapas condicionais):

function formReducer(state: FormState, action: FormAction): FormState {
  switch (action.type) {
    case "NEXT_STEP": {
      // Pula a etapa de pagamento se o plano for "free"
      const nextStep = state.step === 1 && state.fields.plan === "free"
        ? state.step + 2
        : state.step + 1;
      return { ...state, step: nextStep, errors: {} };
    }
    // ... outros casos
  }
}

Desfazer/Refazer com histórico de ações:

interface FormStateWithHistory {
  past: FormState[];
  present: FormState;
  future: FormState[];
}
 
type HistoryAction = FormAction | { type: "UNDO" } | { type: "REDO" };
 
function undoableReducer(state: FormStateWithHistory, action: HistoryAction): FormStateWithHistory {
  if (action.type === "UNDO") {
    const previous = state.past[state.past.length - 1];
    if (!previous) return state;
    return {
      past: state.past.slice(0, -1),
      present: previous,
      future: [state.present, ...state.future],
    };
  }
  if (action.type === "REDO") {
    const next = state.future[0];
    if (!next) return state;
    return {
      past: [...state.past, state.present],
      present: next,
      future: state.future.slice(1),
    };
  }
  return {
    past: [...state.past, state.present],
    present: formReducer(state.present, action),
    future: [],
  };
}

Inicialização preguiçosa para rascunhos salvos:

function initFromStorage(defaultState: FormState): FormState {
  if (typeof window === "undefined") return defaultState;
  const saved = localStorage.getItem("signup-draft");
  return saved ? JSON.parse(saved) : defaultState;
}
 
const [state, dispatch] = useReducer(formReducer, initialState, initFromStorage);

Notas TypeScript

// Nomes de campo fortemente tipados - captura erros de digitação em tempo de compilação
interface SignupFields {
  name: string;
  email: string;
  plan: "free" | "pro" | "enterprise";
}
 
type SetFieldAction = {
  [K in keyof SignupFields]: { type: "SET_FIELD"; name: K; value: SignupFields[K] };
}[keyof SignupFields];
 
// Agora dispatch({ type: "SET_FIELD", name: "plan", value: "invalid" }) é um erro de tipo
 
// Contexto de dispatch tipado para evitar prop drilling
import { createContext, useContext, type Dispatch } from "react";
 
const FormDispatchContext = createContext<Dispatch<FormAction> | null>(null);
 
function useFormDispatch(): Dispatch<FormAction> {
  const dispatch = useContext(FormDispatchContext);
  if (!dispatch) throw new Error("useFormDispatch must be used within FormProvider");
  return dispatch;
}

Teste Unitário do Reducer

import { describe, it, expect } from "vitest";
 
describe("formReducer", () => {
  const initial: FormState = { step: 0, fields: { name: "", email: "" }, errors: {} };
 
  it("define o valor de um campo", () => {
    const next = formReducer(initial, { type: "SET_FIELD", name: "name", value: "Alice" });
    expect(next.fields.name).toBe("Alice");
  });
 
  it("avança para a próxima etapa", () => {
    const next = formReducer(initial, { type: "NEXT_STEP" });
    expect(next.step).toBe(1);
    expect(next.errors).toEqual({});
  });
 
  it("limpa o erro do campo em SET_FIELD", () => {
    const withError = { ...initial, errors: { name: "Obrigatório" } };
    const next = formReducer(withError, { type: "SET_FIELD", name: "name", value: "Alice" });
    expect(next.errors.name).toBe("");
  });
 
  it("não vai abaixo da etapa 0", () => {
    const next = formReducer(initial, { type: "PREV_STEP" });
    expect(next.step).toBe(0);
  });
 
  it("reseta para o estado inicial", () => {
    const modified = { step: 2, fields: { name: "Alice", email: "a@b.com" }, errors: {} };
    const next = formReducer(modified, { type: "RESET" });
    expect(next).toEqual(initial);
  });
});

Armadilhas

Estado desatualizado em callbacks assíncronos - Se você ler state dentro de um setTimeout ou await, obterá o valor no momento do dispatch, não o mais recente. Correção: Use useRef para espelhar o estado atual ou despache uma ação do callback assíncrono em vez de ler o estado.
O spread de objeto cria apenas cópias rasas - Objetos aninhados (como fields dentro de state) também devem ser espalhados: { ...state, fields: { ...state.fields, [name]: value } }. Correção: Sempre espalhe em todos os níveis de aninhamento que você está modificando, ou use produce do Immer.
Esquecer de limpar erros ao alterar um campo - O usuário corrige o erro, mas a mensagem permanece. Correção: Limpe o erro do campo específico dentro de SET_FIELD, como mostrado no exemplo funcional.
O reducer deve ser puro - Sem chamadas de API, sem leituras de localStorage, sem Date.now() dentro do reducer. Correção: Execute efeitos colaterais no componente ou manipulador de eventos, em seguida, despache o resultado.
A validação é executada contra o estado desatualizado após o dispatch - dispatch não atualiza state de forma síncrona. Chamar dispatch({ type: "SET_FIELD" }) e depois ler state.fields retorna o valor antigo. Correção: Valide usando o valor que você está prestes a despachar, não o state atual.
Reducers grandes se tornam difíceis de ler - Uma instrução switch de 200 linhas é pior do que 8 chamadas useState. Correção: Extraia os manipuladores de casos em funções nomeadas: case "SET_FIELD": return handleSetField(state, action);.
Caso default ausente no switch - O TypeScript não avisará se você esquecer um caso, a menos que adicione verificação exaustiva. Correção: Adicione default: { const _exhaustive: never = action; return state; } para capturar ações não tratadas em tempo de compilação.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Múltiplos `useState`	O formulário tem 1-3 campos, sem multi-etapas	As transições de estado são coordenadas entre os campos
React Hook Form	Você precisa de validação integrada, gerenciamento de foco e registro de campos	Você quer controle total sobre a forma e as transições do estado
Zustand / Jotai	O estado do formulário deve persistir entre rotas ou ser compartilhado globalmente	O estado é local para uma árvore de componentes
XState	O formulário tem lógica de ramificação complexa (pular etapas, loops, estados paralelos)	Um assistente linear com validação simples
`useActionState`	Formulário com Server Actions com estado pendente/erro	Assistente multi-etapas no lado do cliente sem viagem de ida e volta do servidor por etapa

FAQs

Quando devo usar useReducer em vez de useState para formulários?

Quando o formulário tem 4+ campos com estado interdependente (por exemplo, alterar um campo afeta a validação de outro)
Quando você tem navegação multi-etapas onde etapa, campos e erros devem permanecer sincronizados
Quando você deseja testar unitariamente as transições de estado sem montar um componente React
Quando vários manipuladores de eventos precisam atualizar o mesmo estado de maneiras diferentes
Regra geral: se você se encontrar chamando 3+ funções setState em um manipulador, mude para useReducer

Posso usar useReducer com Server Actions?

Sim - gerencie o estado do assistente no lado do cliente com useReducer, em seguida, chame a Server Action na submissão final
Envolva a chamada da Server Action em startTransition para obter o estado pendente via useTransition
Despache uma ação VALIDATE com os erros retornados pelo servidor para exibi-los na etapa atual
useActionState lida melhor com formulários de servidor de etapa única; useReducer é para assistentes multi-etapas no cliente

Como persisto o estado do formulário entre as navegações de página?

Use o inicializador preguiçoso (terceiro argumento para useReducer) para carregar do localStorage
Salve o estado no localStorage em um useEffect que é executado a cada mudança de estado
Alternativamente, eleve o reducer para um provedor de contexto que envolva o grupo de rotas
Para estado persistido na URL, serialize a etapa e os campos-chave nos parâmetros de busca

Como valido apenas a etapa atual?

Escreva uma função validateStep(stepIndex, fields) que verifica apenas os campos relevantes para essa etapa
Chame-a em handleNext antes de despachar NEXT_STEP
Se erros forem encontrados, despache VALIDATE com os erros e retorne cedo
Isso evita que os usuários sejam bloqueados por erros em etapas que ainda não alcançaram

O reducer deve lidar com operações assíncronas como chamadas de API?

Não - reducers devem ser funções puras sem efeitos colaterais
Execute o trabalho assíncrono no manipulador de eventos ou useEffect, em seguida, despache o resultado
Exemplo: const result = await saveStep(fields); dispatch({ type: "SAVE_SUCCESS", data: result });
Isso mantém o reducer testável e previsível

Como lido com etapas condicionais/de ramificação?

Adicione lógica de ramificação dentro do caso NEXT_STEP do reducer
Verifique os valores dos campos para determinar para qual índice de etapa pular
Exemplo: pule a etapa de pagamento se plan === "free" incrementando a etapa em 2
Mantenha um array ou mapa de steps para que a barra de progresso reflita o caminho real

Como faço o TypeScript capturar casos de ação ausentes?

Use uma união discriminada para o seu tipo de ação
Adicione verificação exaustiva no caso default: const _exhaustive: never = action; return state;
O TypeScript gerará um erro em tempo de compilação se você adicionar um novo tipo de ação, mas esquecer de tratá-lo
Isso é mais seguro do que um default: return state simples que ignora silenciosamente ações desconhecidas

Por que dispatch não atualiza o estado imediatamente?

dispatch agenda uma re-renderização - state reflete o novo valor na próxima renderização, não de forma síncrona
Se você precisar agir sobre o "novo" valor, calcule-o você mesmo: const nextStep = step + 1; dispatch(...) e depois use nextStep
Alternativamente, use um useEffect que reaja às mudanças de estado
Este é o mesmo comportamento de agrupamento do useState - não é exclusivo do useReducer

Como evito uma instrução switch massiva no reducer?

Extraia cada caso em uma função manipuladora nomeada: case "SET_FIELD": return handleSetField(state, action);
Agrupe ações relacionadas em sub-reducers se o formulário tiver seções distintas
Considere um mapa de manipuladores: const handlers: Record<string, Handler> = { SET_FIELD: handleSetField, ... }
Se o reducer exceder ~50 linhas, é um sinal para dividi-lo

Posso usar Immer com useReducer para atualizações mais simples?

Sim - envolva seu reducer com produce do Immer: const reducer = produce((draft, action) => { draft.fields.name = action.value; })
Isso permite que você escreva código "mutável" que produz atualizações imutáveis nos bastidores
Especialmente útil quando o estado é profundamente aninhado (por exemplo, state.steps[2].fields.address.city)
Adiciona ~5KB, mas elimina a repetição de espalhamento em todos os níveis

Como isso se compara ao XState para formulários de assistente?

useReducer é mais simples: apenas uma instrução switch, sem biblioteca, sem curva de aprendizado
XState é melhor quando as etapas podem ramificar, loop ou rodar em paralelo (comportamento real de máquina de estados)
useReducer lida bem com assistentes lineares e de ramificação simples
Se você se encontrar adicionando booleanos canGoToStep3, considere atualizar para XState

Qual é o tipo TypeScript para a função dispatch?

React.Dispatch<FormAction> - onde FormAction é sua união discriminada
Passe-o através do contexto: createContext<Dispatch<FormAction> | null>(null)
Crie um hook tipado: function useFormDispatch() { const d = useContext(Ctx); if (!d) throw ...; return d; }
Isso evita o prop-drilling de dispatch através de muitos níveis de componentes

Relacionados

Padrões de Formulário Básico - Inputs controlados, formulários de etapa única com useState
Padrões de Formulário Complexos - Assistentes multi-etapas usando React Hook Form
Formulários com Server Actions - Melhoria progressiva com useActionState
Exibição de Erros de Formulário - Padrões para exibir erros de validação
React Hook Form - Gerenciamento de formulários baseado em biblioteca como alternativa

useReducer Multi-Step Forms

Buscar na documentação

useReducer Multi-Step Forms