useReducer Formularios Multi-Paso

Gestiona el estado complejo de formularios multi-paso con useReducer — acciones explícitas como SET_FIELD, NEXT_STEP y VALIDATE hacen que las transiciones de estado sean predecibles, probables y fáciles de depurar sin necesidad de recurrir a bibliotecas externas.

Receta

Tarjeta de referencia rápida — lista para copiar y pegar.

"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: {} };
  }
}

Cuándo usarlo: Cuando tu formulario tiene 3+ pasos, validación entre pasos, o transiciones de estado lo suficientemente complejas como para que malabarear múltiples llamadas a useState sea propenso a errores.

Ejemplo Funcional

"use client";
 
import { useReducer } from "react";
 
// --- Tipos ---
 
interface FormState {
  step: number;
  totalSteps: number;
  fields: {
    name: string;
    email:

Lo que demuestra esto:

Todo el estado del formulario en un único useReducer — índice de paso, valores de campo, errores y estado de envío
Validación por paso que se ejecuta solo en "Siguiente" — los usuarios no están bloqueados por errores en pasos futuros
SET_FIELD limpia el error para ese campo específico, proporcionando retroalimentación en línea
El reductor es una función pura sin efectos secundarios, lo que la hace trivialmente testeable unitariamente
La acción RESET vuelve a initialState — sin riesgo de estado parcial obsoleto

Análisis Profundo

Cómo Funciona

useReducer acepta una función reductora pura y un estado inicial, devolviendo el estado actual y una función dispatch
Cada cambio de estado es una acción explícita con una cadena type — puedes registrar, reproducir o deshacer acciones
El reductor centraliza todas las transiciones de estado en un lugar, eliminando las llamadas setState dispersas que pueden desincronizarse
React agrupa múltiples envíos en el mismo manejador de eventos en un único re-renderizado

Por Qué useReducer en Lugar de useState para Formularios Multi-Paso

Preocupación	`useState` (múltiple)	`useReducer`
Transiciones de estado	Dispersas en manejadores	Centralizadas en el reductor
Pruebas	Debe montar componente	Prueba el reductor como función pura
Depuración	Comprueba cada setter	Registra acciones enviadas
Actualizaciones coordinadas	Riesgo de actualizaciones parciales	Envío único y atómico
Agregar nuevos campos	Otra llamada a `useState`	Agregar a la interfaz de estado

Patrón de Acción

Define una unión discriminada para acciones type-safe:

type FormAction =
  | { type: "SET_FIELD"; name: string; value: string }
  | { type: "NEXT_STEP" }
  | { type: "PREV_STEP" }
  | {

TypeScript estrecha la acción dentro de cada rama case — action.name solo es accesible dentro del caso SET_FIELD.

Combinación con Server Actions

"use client";
 
import { useReducer, useTransition } from "react";
import { submitSignup } from "./actions";
 
function MultiStepForm() {
  const [state, dispatch] = useReducer(formReducer, initialState);
  const [isPending, startTransition

Variaciones

Asistente de ramificación (pasos condicionales):

function formReducer(state: FormState, action: FormAction): FormState {
  switch (action.type) {
    case "NEXT_STEP": {
      // Omite paso de pago si el plan es "free"
      const nextStep = state.step === 1 && state.fields.plan === "free"

Deshacer/rehacer con historial de acciones:

interface FormStateWithHistory {
  past: FormState[];
  present: FormState;
  future: FormState[];
}
 
type HistoryAction = FormAction | { type: "UNDO" } | { type:

Inicializador lazy para borradores guardados:

function initFromStorage(defaultState: FormState): FormState {
  if (typeof window === "undefined") return defaultState;
  const saved = localStorage.getItem("signup-draft");
  return saved ? JSON

Notas de TypeScript

// Nombres de campo fuertemente tipados — detecta errores tipográficos en tiempo de compilación
interface SignupFields {
  name: string;
  email: string;
  plan: "free" | "pro" | "enterprise";
}
 
type SetFieldAction = {
  [K in

Pruebas Unitarias del Reductor

import { describe, it, expect } from "vitest";
 
describe("formReducer", () => {
  const initial: FormState = { step: 0, fields: { name: "", email: "" }, errors: {} };
 
  it("establece un valor de campo", () => {

Trampa

Estado obsoleto en callbacks asincronos — Si lees state dentro de un setTimeout o await, obtienes el valor en el momento del envío, no el más reciente. Solución: Usa useRef para espejar el estado actual, o envía una acción desde el callback asincrónico en lugar de leer el estado.
Object spread solo crea copias superficiales — Los objetos anidados (como fields dentro de state) también deben extenderse: { ...state, fields: { ...state.fields, [name]: value } }. Solución: Siempre extiende en cada nivel de anidación que modifiques, o usa produce de Immer.
Olvidar limpiar errores al cambiar el campo — Los usuarios corrigen el error pero el mensaje persiste. Solución: Limpia el error específico del campo dentro de SET_FIELD, como se muestra en el ejemplo funcional.
El reductor debe ser puro — Sin llamadas a API, sin lecturas de localStorage, sin Date.now() dentro del reductor. Solución: Realiza efectos secundarios en el componente o manejador de eventos, luego envía el resultado.
La validación se ejecuta contra el estado obsoleto después del envío — dispatch no actualiza state de forma síncrona. Llamar a dispatch({ type: "SET_FIELD" }) y luego leer state.fields da el valor antiguo. Solución: Valida usando el valor que estás a punto de enviar, no el state actual.
Los reductores grandes se vuelven difíciles de leer — Una sentencia switch de 200 líneas es peor que 8 llamadas a useState. Solución: Extrae manejadores de casos en funciones nombradas: case "SET_FIELD": return handleSetField(state, action);.
Caso default faltante en switch — TypeScript no advertirá si te pierdes un caso a menos que agregues comprobación exhaustiva. Solución: Agregar default: { const _exhaustive: never = action; return state; } para detectar acciones no controladas en tiempo de compilación.

Alternativas

Alternativa	Usa Cuando	No Uses Cuando
`useState` múltiple	El formulario tiene 1-3 campos, sin multi-paso	Las transiciones de estado se coordinan entre campos
React Hook Form	Necesitas validación integrada, gestión del enfoque y registro de campos	Quieres control total sobre la forma y transiciones de estado
Zustand / Jotai	El estado del formulario debe persistir entre rutas o compartirse globalmente	El estado es local a un árbol de componentes
XState	El formulario tiene lógica de ramificación compleja (omitir pasos, bucles, estados paralelos)	Un asistente lineal con validación simple
`useActionState`	Formulario de Server Action con estado pendiente/error	Asistente de cliente multi-paso sin round-trip de servidor por paso

FAQs

¿Cuándo debo usar useReducer en lugar de useState para formularios?

Cuando el formulario tiene 4+ campos con estado interdependiente (p. ej., cambiar un campo afecta la validación de otro)
Cuando tienes navegación multi-paso donde paso, campos y errores deben mantenerse sincronizados
Cuando quieres probar unitariamente transiciones de estado sin montar un componente React
Cuando múltiples manejadores de eventos necesitan actualizar el mismo estado de diferentes maneras
Regla de oro: si encuentras que estás llamando a 3+ funciones setState en un manejador, cambia a useReducer

¿Puedo usar useReducer con Server Actions?

Sí — gestiona el estado del asistente del lado del cliente con useReducer, luego llama a la Server Action en el envío final
Envuelve la llamada de Server Action en startTransition para el estado pendiente vía useTransition
Envía una acción VALIDATE con errores devueltos por el servidor para mostrarlos en el paso actual
useActionState maneja mejor formularios de servidor de un solo paso; useReducer es para asistentes multi-paso del cliente

¿Cómo persisto el estado del formulario entre navegaciones de página?

Usa el inicializador lazy (tercer argumento para useReducer) para cargar desde localStorage
Guarda el estado en localStorage en un useEffect que se ejecuta en cada cambio de estado
Alternativamente, levanta el reductor a un proveedor de contexto que envuelve el grupo de ruta
Para el estado persistido en URL, serializa el paso y campos clave en parámetros de búsqueda

¿Cómo valido solo el paso actual?

Escribe una función validateStep(stepIndex, fields) que solo compruebe los campos relevantes para ese paso
Llámala en handleNext antes de enviar NEXT_STEP
Si se encuentran errores, envía VALIDATE con los errores y retorna temprano
Esto evita que los usuarios sean bloqueados por errores en pasos que aún no han alcanzado

¿Debería el reductor manejar operaciones asincronos como llamadas a API?

No — los reductores deben ser funciones puras sin efectos secundarios
Realiza trabajo asincrónico en el manejador de eventos o useEffect, luego envía el resultado
Ejemplo: const result = await saveStep(fields); dispatch({ type: "SAVE_SUCCESS", data: result });
Esto mantiene el reductor testeable y predecible

¿Cómo manejo pasos condicionales/de ramificación?

Agrega lógica de ramificación dentro del caso NEXT_STEP del reductor
Comprueba los valores de los campos para determinar a qué índice de paso saltar
Ejemplo: omite el paso de pago si plan === "free" incrementando el paso en 2
Mantén un array o mapa de steps para que la barra de progreso refleje la ruta actual

¿Cómo hago que TypeScript detecte casos de acción faltantes?

Usa una unión discriminada para tu tipo de acción
Agrega comprobación exhaustiva en el caso default: const _exhaustive: never = action; return state;
TypeScript arrojará un error en tiempo de compilación si agregas un nuevo tipo de acción pero olvidas manejarlo
Esto es más seguro que un default: return state desnudo que silenciosamente traga acciones desconocidas

¿Por qué dispatch no actualiza el estado inmediatamente?

dispatch programa un re-renderizado — state refleja el nuevo valor en el siguiente renderizado, no de forma síncrona
Si necesitas actuar sobre el valor "nuevo", calcúlalo tu mismo: const nextStep = step + 1; dispatch(...) luego usa nextStep
Alternativamente, usa un useEffect que reacciona a cambios de estado
Este es el mismo comportamiento de agrupamiento que useState — no es único para useReducer

¿Cómo evito una sentencia switch masiva en el reductor?

Extrae cada caso en una función manejadora nombrada: case "SET_FIELD": return handleSetField(state, action);
Agrupa acciones relacionadas en sub-reductores si el formulario tiene secciones distintas
Considera un mapa de manejadores: const handlers: Record<string, Handler> = { SET_FIELD: handleSetField, ... }
Si el reductor excede ~50 líneas, es señal de dividirlo

¿Puedo usar Immer con useReducer para actualizaciones más simples?

Sí — envuelve tu reductor con produce de Immer: const reducer = produce((draft, action) => { draft.fields.name = action.value; })
Esto te permite escribir código "mutante" que produce actualizaciones inmutables bajo el capó
Especialmente útil cuando el estado está profundamente anidado (p. ej., state.steps[2].fields.address.city)
Suma ~5KB pero elimina el boilerplate de spread-en-cada-nivel

¿Cómo se compara esto con XState para formularios de asistente?

useReducer es más simple: solo una sentencia switch, sin biblioteca, sin curva de aprendizaje
XState es mejor cuando los pasos pueden ramificarse, hacer bucles o ejecutarse en paralelo (comportamiento verdadero de máquina de estados)
useReducer maneja asistentes lineales y de ramificación simple bien
Si encuentras que estás agregando booleanos canGoToStep3, considera actualizar a XState

¿Cuál es el tipo de TypeScript para la función dispatch?

React.Dispatch<FormAction> — donde FormAction es tu unión discriminada
Pásalo a través del contexto: createContext<Dispatch<FormAction> | null>(null)
Crea un hook tipado: function useFormDispatch() { const d = useContext(Ctx); if (!d) throw ...; return d; }
Esto evita prop-drilling dispatch a través de muchos niveles de componentes

Relacionado

Patrones de Formulario Básico — Inputs controlados, formularios de un solo paso con useState
Patrones de Formulario Complejo — Asistentes multi-paso usando React Hook Form
Formularios de Server Action — Mejora progresiva con useActionState
Mostrar Errores del Formulario — Patrones para mostrar errores de validación
React Hook Form — Gestión de formularios basada en biblioteca como alternativa

Buscar en la documentación

useReducer Formularios Multi-Paso