Busca en todas las páginas de la documentación
Cuando el estado del componente es suficiente en pantallas móviles. Usa useReducer cuando varios campos se actualizan juntos - pasos de pago, asistentes de incorporación y formularios con mucha validación. Mantén las respuestas de API en TanStack Query; los reducers poseen solo transiciones de UI de cliente.
Tarjeta de referencia rápida - lista para copiar y pegar.
// useState - UI efímera en una pantalla
const [expanded, setExpanded] = useState(false);// useReducer - campos relacionados + transiciones explícitas
type State = { step: 0 | 1 | 2; email: string; error?: string };
type Action =
| { type: "set_email"; email: string }
| { type: "next" }
| { type: "back" }
| { type: "set_error"; error: string };
function reducer(state: State, action: Action): State {
switch (action.type) {
case "set_email":
return { ...state, email: action.email, error: undefined };
case "next":
return state.step < 2 ? { ...state, step: (state.step + 1) as State["step"] } : state;
case "back":
return state.step > 0 ? { ...state, step: (state.step - 1) as State["step"] } : state;
case "set_error":
return { ...state, error: action.error };
default:
return state;
}
}
const [state, dispatch] = useReducer(reducer, { step: 0, email: "" });Cuándo usarlo:
useState se actualizan al mismo ritmo - un reducer reemplaza cinco llamadas setX.// OnboardingWizard.tsx - useReducer para pasos; useState para un simple botón de alternancia
import { useReducer, useState } from "react";
import { Pressable, StyleSheet, Text, TextInput, View } from "react-native";
type WizardState = {
step: 1 | 2 | 3;
name: string;
notifications: boolean;
error?: string;
};
type WizardAction =
| { type: "set_name"; name: string }
| { type: "toggle_notifications" }
| { type: "next" }
| { type: "back" }
| { type: "submit_error"; error: string }
| { type: "reset" };
const initial: WizardState = { step: 1, name: "", notifications: true };
function wizardReducer(state: WizardState, action: WizardAction): WizardState {
switch (action.type) {
case "set_name":
return { ...state, name: action.name, error: undefined };
case "toggle_notifications":
return { ...state, notifications: !state.notifications };
case "next": {
if (state.step === 1 && state.name.trim().length < 2) {
return { ...state, error: "El nombre debe tener al menos 2 caracteres" };
}
return state.step < 3 ? { ...state, step: (state.step + 1) as WizardState["step"], error: undefined } : state;
}
case "back":
return state.step > 1 ? { ...state, step: (state.step - 1) as WizardState["step"], error: undefined } : state;
case "submit_error":
return { ...state, error: action.error };
case "reset":
return initial;
default:
return state;
}
}
export function OnboardingWizard({ onComplete }: { onComplete: (payload: WizardState) => void }) {
const [state, dispatch] = useReducer(wizardReducer, initial);
const [submitting, setSubmitting] = useState(false);
async function handleFinish() {
setSubmitting(true);
try {
// await saveProfile(state) - mutación vía Query en aplicaciones de producción
onComplete(state);
dispatch({ type: "reset" });
} catch {
dispatch({ type: "submit_error", error: "No se pudo guardar - intenta de nuevo" });
} finally {
setSubmitting(false);
}
}
return (
<View style={styles.container}>
<Text style={styles.title}>Paso {state.step} de 3</Text>
{state.error && <Text style={styles.error}>{state.error}</Text>}
{state.step === 1 && (
<TextInput
placeholder="Tu nombre"
value={state.name}
onChangeText={(name) => dispatch({ type: "set_name", name })}
style={styles.input}
/>
)}
{state.step === 2 && (
<Pressable onPress={() => dispatch({ type: "toggle_notifications" })}>
<Text>Notificaciones: {state.notifications ? "Activadas" : "Desactivadas"}</Text>
</Pressable>
)}
{state.step === 3 && <Text>Revisar: {state.name}</Text>}
<View style={styles.row}>
{state.step > 1 && (
<Pressable style={styles.btnSecondary} onPress={() => dispatch({ type: "back" })}>
<Text>Atrás</Text>
</Pressable>
)}
{state.step < 3 ? (
<Pressable style={styles.btn} onPress={() => dispatch({ type: "next" })}>
<Text style={styles.btnLabel}>Siguiente</Text>
</Pressable>
) : (
<Pressable style={styles.btn} onPress={handleFinish} disabled={submitting}>
<Text style={styles.btnLabel}>{submitting ? "Guardando…" : "Terminar"}</Text>
</Pressable>
)}
</View>
</View>
);
}
const styles = StyleSheet.create({
container: { padding: 20, gap: 12 },
title: { fontSize: 22, fontWeight: "700" },
error: { color: "#dc2626" },
input: { borderWidth: 1, borderColor: "#cbd5e1", padding: 12, borderRadius: 8 },
row: { flexDirection: "row", gap: 8, marginTop: 8 },
btn: { backgroundColor: "#2563eb", padding: 14, borderRadius: 8, flex: 1 },
btnSecondary: { padding: 14, borderRadius: 8, borderWidth: 1, borderColor: "#94a3b8" },
btnLabel: { color: "#fff", fontWeight: "600", textAlign: "center" },
});Lo que esto demuestra:
useReducer posee step, name, notifications y error de validación - una función de transición.useState(submitting) se mantiene separado - el estado pendiente asincrónico es ortogonal a los datos del asistente.next - los estados imposibles (step 4) nunca existen.reset devuelve un objeto inicial conocido - comprobable e idempotente.| Patrón | Ejemplo | Por qué useState |
|---|---|---|
| Booleano UI | Modal abierto, acordeón | Un valor, un setter |
| Selección única | Fila de lista resaltada | El padre mantiene selectedId |
| Contador | Selector de cantidad | setQty((q) => q + 1) es claro |
| Filtro de texto (local) | Cuadro de búsqueda antes de Query con debounce | Efímero hasta enviar |
| Patrón | Ejemplo | Por qué reducer |
|---|---|---|
| Asistente / pasos | Incorporación, KYC | next/back codifican reglas |
| Formulario con reglas entre campos | Contraseña + confirmar | Una acción actualiza múltiples campos |
| Máquina de estado | Carga: idle - cargando - hecho | Transiciones finitas |
| Deshacer lote | Editor de borrador | Acción RESET única |
dispatch de useReducer es estable durante la vida útil del componente - omítelo de los arrays de dependencias de useEffect. Lo mismo aplica para setState de useState. Las reglas de lint react-hooks documentan esto.
const [state, dispatch] = useReducer(reducer, props.initialStep, (step) => ({
step,
email: "",
notifications: true,
}));Pasa un tercer argumento cuando el estado inicial es costoso de calcular - se ejecuta una sola vez en el montaje.
Mantén wizardReducer en el mismo archivo que OnboardingWizard hasta que una segunda pantalla necesite transiciones idénticas. Promuévelo a features/onboarding/wizardReducer.ts solo en reutilización - no de manera preventiva.
// ❌ No hidratar reducer desde fetch en useEffect
useEffect(() => {
fetchProfile().then((p) => dispatch({ type: "load_profile", profile: p }));
}, []);
// ✅ Query posee el perfil; reducer posee el borrador de edición
const { data: profile } = useQuery({ queryKey: ["profile"], queryFn: fetchProfile });
const [draft, dispatch] = useReducer(editReducer, profile ?? emptyDraft);Sincroniza el borrador desde Query con un remontaje con clave o reset explícito cuando profile.id cambia - no en cada renderizado.
Muchas llamadas useState no relacionadas - Cinco booleanos para un formulario significa actualizaciones perdidas. Solución: Un useReducer o React Hook Form.
Mutando estado dentro del reducer - state.items.push(x) rompe React. Solución: Devuelve nuevos objetos: { ...state, items: [...state.items, x] }.
Efectos secundarios del reducer - Obtener dentro de switch dificulta las pruebas. Solución: Efectos secundarios en manejadores de eventos; reducer se mantiene puro.
Almacenar listas de API en reducer - Duplica el caché de TanStack Query. Solución: Query para datos del servidor; reducer para borrador solo de UI.
Elevar reducer demasiado alto - El estado del asistente en Context raíz re-renderiza la aplicación. Solución: Mantén el reducer en la pantalla del asistente hasta que otra ruta realmente lo necesite.
Falta el caso default - La exhaustividad de TypeScript ayuda; las acciones desconocidas en tiempo de ejecución deben devolver state.
Actualizaciones funcionales con reducer - Los reducers ya reciben el estado anterior - no anides patrones setState dentro.
| Alternativa | Úsalo cuando | No lo uses cuando |
|---|---|---|
useState | 1-2 valores independientes | Muchos campos acoplados |
useReducer | Asistentes, formularios pequeños, máquinas de estado | Carrito global en pestañas |
| React Hook Form | Formularios grandes, esquemas de validación | Campo de email único |
| Zustand | Estado de cliente global con selectores | Modal efímero en una pantalla |
| XState | Flujos de trabajo complejos auditados | Asistente de tres pasos simple |
Dos campos (correo electrónico, contraseña) - useState está bien. Si agregas remember-me, paso MFA y validación en línea, cambia a useReducer o Hook Form.
Sí - useReducer en un proveedor es el patrón global integrado. Divide contextos o Zustand cuando los consumidores se re-renderizan demasiado a menudo - ver Context Without Storms.
Solo para estado de UI local o pequeño compartido. Redux Toolkit aún gana para dominios multi-característica auditados y DevTools a escala - ver Redux Toolkit.
Exporta wizardReducer y prueba unitariamente acciones sin renderizar:
expect(wizardReducer(initial, { type: "next" })).toEqual({ ...initial, error: "El nombre debe tener al menos 2 caracteres" });Mantén submitting como useState o deriva de isPending de useMutation. El estado asincrónico es un efecto secundario, no una transición pura.
useActionState se dirige a Server Actions en web. Las aplicaciones móviles de Expo usan useReducer + useMutation de TanStack Query para envíos en red.
Regla de oro: más de cuatro valores relacionados en una pantalla - considera un reducer o un hook personalizado envolviéndote el estado.
Sí vía useImmerReducer de use-immer. Zustand + middleware immer es más común para almacenes globales - ver Zustand.
Mantén el índice de paso en el estado del reducer para transiciones animadas. Para el progreso compartible, refleja el paso en router.setParams({ step: "2" }) - la URL es UX opcional, el reducer es la fuente de verdad durante la sesión.
setState({ ...s, email }) funciona hasta que dos actualizaciones se cotejan incorrectamente u olvidas un campo. Los reducers fuerzan nombres de acción explícitos - más fácil de registrar y probar.
El contenedor mantiene useReducer / useState; el presentador recibe solo props y callbacks - ver container-presenter en móvil.
El estado del reducer en un padre de una FlatList de 500 filas re-renderiza todas las filas. Mueve los datos de la lista a Query; mantén la selección en reducer con extraData o memoización a nivel de fila.
Versiones de stack: Esta página fue escrita para React 19.2.3, React Native 0.86.0, y Expo SDK 57 (
expo~57.0.4).
Revisado por Chris St. John·Última actualización: 16 jul 2026