Validación con Zod

Q: ¿Cómo instalo Zod y el resolver en Expo SDK 57?

expo install fija versiones compatibles con tu lockfile. Importa esquemas de archivos .ts simples - sin configuración de módulo nativo.

Q: ¿Cuál es la diferencia entre parse y safeParse en formularios?

zodResolver usa parse internamente - los fallos de validación se convierten automáticamente en errores de campo RHF. Usa safeParse en clientes de API cuando quieras ramificarte sin lanzar. En onSubmit, los valores ya están validados - confía en el tipo que RHF pasa.

Q: ¿Cómo valido campos opcionales que los usuarios dejan en blanco?

TextInput vacío devuelve "", no undefined. Acepta "" con .or(z.literal("")) o transforma a undefined.

Q: ¿Cómo muestro errores solo después de que el usuario envía una vez?

Combina isTouched e isSubmitted para una primera edición indulgente, estricta después del intento de envío. mode: "onTouched" aún valida campos tempranos antes del primer envío - ajusta mode si es necesario.

Q: ¿Cómo manejo campos TextInput numéricos?

keyboardType="number-pad" no cambia el tipo JS - el valor sigue siendo una cadena hasta la coerción. La cadena vacía se fuerza a NaN - agrega .min(1) en un paso de cadena o mapa de errores personalizado para una copia más clara.

Q: ¿Puedo reutilizar el mismo esquema para formularios y respuestas de API?

Sí - analiza JSON de API con UserSchema.parse(json) y valida formularios con zodResolver(UserSchema). Usa .pick() para formularios de edición que envían un subconjunto de campos. Ver Tipificación de respuestas de API y Zod para patrones de frontera de fetch.

Q: ¿Cómo adjunto un error de refine a un campo específico?

Sin path, el error se encuentra en la raíz del formulario - invisible junto a las entradas. Múltiples refines pueden dirigirse a diferentes valores path.

Q: ¿Cómo asigno errores de validación del servidor a campos?

Recorre fieldErrors de la respuesta de la API. Usa type: "server" para que las reglas del lado del cliente puedan coexistir.

Q: ¿Debo usar z.input o z.infer para generics useForm?

Usa z.infer (tipo de salida) cuando el esquema usa .coerce, .default, o .transform. Usa z.input cuando el formulario contiene formas pre-transform (raro en móvil). Cuando no estés seguro, z.infer coincide con lo que onSubmit recibe después de la validación.

Q: ¿Cómo valido una lista dinámica de campos?

Empareja con useFieldArray de react-hook-form. Zod reporta rutas de índice de array como emails.2 - asígnalas a la fila correcta en la interfaz de usuario.

Zod describe cómo se ve un dato válido en tiempo de ejecución e infiere el mismo tipo de TypeScript que tu IDE autocompletar. En móvil, eso importa el doble: TextInput siempre devuelve cadenas, y los usuarios esperan errores en línea bajo el campo que acabas de dejar, no una ventana modal después de tocar Enviar.

Receta

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

import { zodResolver } from "@hookform/resolvers/zod";
import { Controller, useForm } from "react-hook-form";
import { z } from "zod";
import { Pressable, StyleSheet, Text, TextInput, View } from "react-native";
 
const SignUpSchema = z
  .object({
    email: z.string().min(1, "Email es obligatorio").email("Introduce un email válido"),
    password: z.string().min(8, "Al menos 8 caracteres"),
    confirmPassword: z.string().min(1, "Confirma tu contraseña"),
  })
  .refine((data) => data.password === data.confirmPassword, {
    message: "Las contraseñas deben coincidir",
    path: ["confirmPassword"],
  });
 
type SignUpValues = z.infer<typeof SignUpSchema>;
 
export function SignUpForm() {
  const {
    control,
    handleSubmit,
    formState: { errors, isSubmitting },
  } = useForm<SignUpValues>({
    resolver: zodResolver(SignUpSchema),
    defaultValues: { email: "", password: "", confirmPassword: "" },
    mode: "onTouched",
  });
 
  function onSubmit(values: SignUpValues) {
    console.log(values);
  }
 
  return (
    <View style={styles.form}>
      <Controller
        control={control}
        name="email"
        render={({ field: { onChange, onBlur, value, ref } }) => (
          <TextInput
            ref={ref}
            value={value}
            onChangeText={onChange}
            onBlur={onBlur}
            keyboardType="email-address"
            autoCapitalize="none"
            placeholder="Email"
            style={styles.input}
          />
        )}
      />
      {errors.email && <Text style={styles.error}>{errors.email.message}</Text>}
 
      <Controller
        control={control}
        name="password"
        render={({ field: { onChange, onBlur, value, ref } }) => (
          <TextInput
            ref={ref}
            value={value}
            onChangeText={onChange}
            onBlur={onBlur}
            secureTextEntry
            placeholder="Contraseña"
            style={styles.input}
          />
        )}
      />
      {errors.password && <Text style={styles.error}>{errors.password.message}</Text>}
 
      <Controller
        control={control}
        name="confirmPassword"
        render={({ field: { onChange, onBlur, value, ref } }) => (
          <TextInput
            ref={ref}
            value={value}
            onChangeText={onChange}
            onBlur={onBlur}
            secureTextEntry
            placeholder="Confirmar contraseña"
            style={styles.input}
          />
        )}
      />
      {errors.confirmPassword && (
        <Text style={styles.error}>{errors.confirmPassword.message}</Text>
      )}
 
      <Pressable onPress={handleSubmit(onSubmit)} disabled={isSubmitting} style={styles.button}>
        <Text style={styles.buttonText}>Crear cuenta</Text>
      </Pressable>
    </View>
  );
}
 
const styles = StyleSheet.create({
  form: { gap: 12, padding: 16 },
  input: {
    borderWidth: 1,
    borderColor: "#d1d5db",
    borderRadius: 8,
    paddingHorizontal: 12,
    paddingVertical: 10,
    fontSize: 16,
  },
  error: { color: "#dc2626", fontSize: 13 },
  button: {
    backgroundColor: "#2563eb",
    borderRadius: 8,
    paddingVertical: 12,
    alignItems: "center",
  },
  buttonText: { color: "#fff", fontWeight: "600" },
});

Cuándo usarlo:

Cualquier formulario donde las reglas de validación deben coincidir con tu esquema de solicitud de API.
Reglas entre campos - confirmación de contraseña, rangos de fechas, campos requeridos condicionalmente.
Compartir esquemas entre formularios móviles y análisis en la capa de fetch (ver Tipificación de respuestas de API y Zod).
Mensajes de error localizados derivados de una definición de esquema única.
Evitar que las quirks de cadena de TextInput rompan la validación numérica o booleana.

Ejemplo de trabajo

// lib/schemas/profile.ts - compartido entre formulario y cliente de API
import { z } from "zod";
 
export const ProfileSchema = z.object({
  displayName: z
    .string()
    .trim()
    .min(1, "El nombre de usuario es obligatorio")
    .max(40, "Mantenlo bajo 40 caracteres"),
  bio: z
    .string()
    .max(280, "La biografía debe tener 280 caracteres o menos")
    .optional()
    .or(z.literal("")),
  age: z
    .string()
    .min(1, "La edad es obligatoria")
    .pipe(
      z.coerce
        .number({ invalid_type_error: "Introduce un número" })
        .int("Solo números enteros")
        .min(13, "Debes tener al menos 13 años")
        .max(120, "Introduce una edad realista")
    ),
  newsletter: z.boolean().default(false),
});
 
export type ProfileValues = z.infer<typeof ProfileSchema>;
 
export const ProfileUpdateSchema = ProfileSchema.pick({
  displayName: true,
  bio: true,
  newsletter: true,
});
 
export type ProfileUpdateValues = z.infer<typeof ProfileUpdateSchema>;

// components/form/ValidatedTextField.tsx
import { Controller, type Control, type FieldPath, type FieldValues } from "react-hook-form";
import { StyleSheet, Text, TextInput, type TextInputProps, View } from "react-native";
 
interface ValidatedTextFieldProps<T extends FieldValues>
  extends Omit<TextInputProps, "value" | "onChangeText"> {
  control: Control<T>;
  name: FieldPath<T>;
  label: string;
}
 
export function ValidatedTextField<T extends FieldValues>({
  control,
  name,
  label,
  ...inputProps
}: ValidatedTextFieldProps<T>) {
  return (
    <Controller
      control={control}
      name={name}
      render={({ field: { onChange, onBlur, value, ref }, fieldState: { error, isTouched } }) => (
        <View style={styles.field}>
          <Text style={styles.label}>{label}</Text>
          <TextInput
            ref={ref}
            value={value ?? ""}
            onChangeText={onChange}
            onBlur={onBlur}
            style={[styles.input, isTouched && error && styles.inputError]}
            accessibilityLabel={label}
            accessibilityHint={error?.message}
            {...inputProps}
          />
          {isTouched && error && (
            <Text style={styles.error} accessibilityLiveRegion="polite">
              {error.message}
            </Text>
          )}
        </View>
      )}
    />
  );
}
 
const styles = StyleSheet.create({
  field: { gap: 6 },
  label: { fontSize: 14, fontWeight: "600", color: "#374151" },
  input: {
    borderWidth: 1,
    borderColor: "#d1d5db",
    borderRadius: 8,
    paddingHorizontal: 12,
    paddingVertical: 10,
    fontSize: 16,
    backgroundColor: "#fff",
  },
  inputError: { borderColor: "#dc2626" },
  error: { color: "#dc2626", fontSize: 13 },
});

// app/settings/profile.tsx - enviar con asignación de errores del servidor
import { zodResolver } from "@hookform/resolvers/zod";
import { useForm } from "react-hook-form";
import { Controller } from "react-hook-form";
import { Alert, Pressable, StyleSheet, Switch, Text, View } from "react-native";
import { KeyboardAwareScrollView } from "react-native-keyboard-controller";
import { ProfileSchema, type ProfileValues } from "../../lib/schemas/profile";
import { ValidatedTextField } from "../../components/form/ValidatedTextField";
 
type ApiFieldErrors = Partial<Record<keyof ProfileValues, string>>;
 
async function saveProfile(
  values: ProfileValues
): Promise<{ ok: true } | { ok: false; fieldErrors?: ApiFieldErrors; message?: string }> {
  const res = await fetch("https://api.example.com/v1/profile", {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(values),
  });
  const json: unknown = await res.json();
  if (!res.ok) {
    const body = json as { fieldErrors?: ApiFieldErrors; message?: string };
    return { ok: false, fieldErrors: body.fieldErrors, message: body.message };
  }
  return { ok: true };
}
 
export default function ProfileScreen() {
  const {
    control,
    handleSubmit,
    setError,
    setFocus,
    formState: { isSubmitting, isDirty },
  } = useForm<ProfileValues>({
    resolver: zodResolver(ProfileSchema),
    defaultValues: {
      displayName: "",
      bio: "",
      age: "",
      newsletter: false,
    },
    mode: "onTouched",
    reValidateMode: "onChange",
  });
 
  async function onSubmit(values: ProfileValues) {
    const result = await saveProfile(values);
    if (result.ok) {
      Alert.alert("Guardado", "Tu perfil ha sido actualizado.");
      return;
    }
    if (result.fieldErrors) {
      for (const [field, message] of Object.entries(result.fieldErrors)) {
        setError(field as keyof ProfileValues, { type: "server", message });
      }
      const first = Object.keys(result.fieldErrors)[0] as keyof ProfileValues;
      setFocus(first);
      return;
    }
    Alert.alert("Error al guardar", result.message ?? "Intenta de nuevo.");
  }
 
  return (
    <KeyboardAwareScrollView contentContainerStyle={styles.scroll} keyboardShouldPersistTaps="handled">
      <ValidatedTextField control={control} name="displayName" label="Nombre de usuario" />
 
      <ValidatedTextField
        control={control}
        name="bio"
        label="Biografía"
        multiline
        numberOfLines={3}
        style={styles.multiline}
      />
 
      <ValidatedTextField
        control={control}
        name="age"
        label="Edad"
        keyboardType="number-pad"
      />
 
      <View style={styles.switchRow}>
        <Text style={styles.switchLabel}>Boletín de correo electrónico</Text>
        <Controller
          control={control}
          name="newsletter"
          render={({ field: { value, onChange } }) => (
            <Switch value={value} onValueChange={onChange} />
          )}
        />
      </View>
 
      <Pressable
        onPress={handleSubmit(onSubmit)}
        disabled={isSubmitting || !isDirty}
        style={[styles.button, (!isDirty || isSubmitting) && styles.buttonDisabled]}
      >
        <Text style={styles.buttonText}>{isSubmitting ? "Guardando…" : "Guardar cambios"}</Text>
      </Pressable>
    </KeyboardAwareScrollView>
  );
}
 
const styles = StyleSheet.create({
  scroll: { padding: 16, gap: 16 },
  multiline: { minHeight: 88, textAlignVertical: "top" },
  switchRow: { flexDirection: "row", alignItems: "center", justifyContent: "space-between" },
  switchLabel: { fontSize: 16 },
  button: {
    backgroundColor: "#2563eb",
    borderRadius: 8,
    paddingVertical: 12,
    alignItems: "center",
    marginTop: 8,
  },
  buttonDisabled: { opacity: 0.5 },
  buttonText: { color: "#fff", fontWeight: "600" },
});

Lo que esto demuestra:

Un único ProfileSchema impulsa tanto los tipos en tiempo de compilación como la validación en tiempo de ejecución.
.trim(), .coerce.number(), y .optional().or(z.literal("")) manejan las realidades de cadena de TextInput.
ValidatedTextField muestra errores solo después del toque - mejor UX en móvil que validar en cada carácter.
setError + setFocus asigna fieldErrors del servidor a mensajes en línea bajo la entrada correcta.
ProfileUpdateSchema.pick() reutiliza definiciones de campo para un formulario de edición parcial sin duplicar reglas.

Análisis profundo

Cómo funciona

Defines un esquema de Zod que describe la forma, restricciones y mensajes de error.
zodResolver(Schema) adapta ese esquema al espacio resolver de react-hook-form.
Al enviar (o por mode), RHF pasa valores actuales a Zod; los fallos se convierten en formState.errors con clave de ruta de campo.
z.infer<typeof Schema> exporta el tipo de TypeScript - no hay interfaz paralela que se desvíe.
Zod se ejecuta en archivos .ts simples sin JSX, por lo que Metro puede importar esquemas de clientes de API, tareas de fondo y pruebas.

Reglas de un vistazo

Helper de Zod	Uso en formulario móvil
`z.string().min(1)`	Campos de texto requeridos (después de `.trim()`)
`z.string().email()`	Email `TextInput` con `keyboardType="email-address"`
`z.coerce.number()`	Campos numéricos - `TextInput` siempre devuelve cadenas
`z.boolean()`	Valores de `Switch` via `Controller`
`z.enum(["a", "b"])`	Controles segmentados y selecciones de selector
`.optional()`	El campo puede estar ausente del objeto
`.nullable()`	El campo puede ser `null` explícito de la API
`.default(false)`	Casilla desactivada sin registrar `undefined`
`.refine()`	Reglas entre campos con `path` dirigido a un campo
`.superRefine()`	Múltiples errores o rutas de índice de array

Cadenas vacías y campos opcionales

const OptionalBioSchema = z.object({
  bio: z
    .string()
    .trim()
    .max(280)
    .transform((s) => (s === "" ? undefined : s))
    .optional(),
});

Los usuarios dejan campos opcionales en blanco como "", no undefined.
Transforma cadenas vacías una vez en el esquema en lugar de limpiar en onSubmit.
Para campos requeridos, encadena .trim().min(1, "Requerido") para que la entrada solo de espacios en blanco falle.

Validación entre campos

const ChangePasswordSchema = z
  .object({
    currentPassword: z.string().min(1, "Introduce tu contraseña actual"),
    newPassword: z.string().min(8, "Al menos 8 caracteres"),
    confirmPassword: z.string().min(1, "Confirma tu nueva contraseña"),
  })
  .refine((data) => data.newPassword === data.confirmPassword, {
    message: "Las contraseñas deben coincidir",
    path: ["confirmPassword"],
  })
  .refine((data) => data.currentPassword !== data.newPassword, {
    message: "La nueva contraseña debe ser diferente de la actual",
    path: ["newPassword"],
  });

.refine() se ejecuta después del análisis de campo base - ideal para confirmación de contraseña.
Establece path para que el error se adjunte al TextInput correcto, no a la raíz del formulario.
Usa .superRefine() cuando una validación produce múltiples errores en diferentes rutas.

Notas de TypeScript

import { z } from "zod";
 
const OrderSchema = z.object({
  quantity: z.coerce.number().positive(),
  note: z.string().optional(),
});
 
type OrderInput = z.input<typeof OrderSchema>;   // antes de transforms/coerce
type OrderOutput = z.output<typeof OrderSchema>; // después - igual que z.infer cuando no hay transforms
type OrderValues = z.infer<typeof OrderSchema>;

Instala con npx expo install zod @hookform/resolvers react-hook-form.
Exporta Schema, type Values = z.infer<typeof Schema>, y helpers safeParse de un módulo.
Reutiliza esquemas de respuesta de API con .pick() / .omit() / .extend() para que las formas de lista, detalle y formulario se mantengan alineadas.

Patrones de visualización de errores

Patrón	Comportamiento	Mejor para
Mostrar al tocar	`isTouched && error`	UX móvil por defecto
Mostrar después del primer envío	`isSubmitted && error`	Formularios cortos con un CTA
Siempre mostrar	`error && message`	Formularios de cumplimiento críticos de accesibilidad
Banner resumen	Mensaje `errors.root` de raíz	Fallos de servidor que no son de campo

// Mostrar un error de servidor que no es de campo
setError("root", { type: "server", message: "Red no disponible. Intenta de nuevo." });
{errors.root && <Text style={styles.banner}>{errors.root.message}</Text>}

Errores comunes

Duplicar tipos y esquemas - Mantener una interface Profile separada de ProfileSchema se desvía en el primer cambio de API. Solución: Exporta solo z.infer<typeof ProfileSchema>.
Validar números sin coerción - z.number() falla cuando TextInput entrega "25" como una cadena. Solución: z.coerce.number() o z.string().regex(/^\d+$/).transform(Number).
.optional() vs cadena vacía - Campo bio opcional con "" falla z.string().email() encadenado después. Solución: Recorta y transforma "" - undefined, o usa .or(z.literal("")).
Mostrar errores antes de tocar - Validar onChange en cada pulsación de tecla frustra a los usuarios móviles. Solución: mode: "onTouched" y renderiza isTouched && error.
Coincidencia de contraseña en ruta incorrecta - .refine() sin path pone el error en la raíz _form. Solución: path: ["confirmPassword"] para que el mensaje se encuentre bajo el campo correcto.
Campos de API que aceptan valores nulos en formularios - Backend envía middleName: null pero el formulario usa "". Solución: Normaliza en defaultValues y esquema con .nullable().transform(v => v ?? "").
Esquema monolítico gigante - Un esquema de 40 campos hace que las rutas de error sean difíciles de leer. Solución: Compone esquemas de paso y fusiona con .merge() para asistentes, o valida por paso con .pick().

Alternativas

Alternativa	Úsalo cuando	No lo uses cuando
Zod + `zodResolver`	Por defecto para formularios RN tipificados compartidos con capa de API	Casilla única con un `useState` local trivial
Yup + `yupResolver`	El equipo ya se estandarizó en Yup	Aplicaciones de campo verde donde Zod coincide con tus esquemas de fetch
`rules` en línea en `Controller`	1-2 campos triviales (`required: true`)	Reglas entre campos o esquemas reutilizados en el lado del servidor
Valibot / ArkType	El tamaño del bundle es la restricción máxima	Ya compartes esquemas de Zod con la aplicación web y backend
`safeParse` manual en `onSubmit`	Prototipo sin RHF	Formularios de producción que necesitan estado de toque por campo y `setError`

FAQs

¿Cómo instalo Zod y el resolver en Expo SDK 57?

npx expo install zod @hookform/resolvers react-hook-form

expo install fija versiones compatibles con tu lockfile.
Importa esquemas de archivos .ts simples - sin configuración de módulo nativo.

¿Cuál es la diferencia entre parse y safeParse en formularios?

zodResolver usa parse internamente - los fallos de validación se convierten automáticamente en errores de campo RHF.
Usa safeParse en clientes de API cuando quieras ramificarte sin lanzar.
En onSubmit, los valores ya están validados - confía en el tipo que RHF pasa.

¿Cómo valido campos opcionales que los usuarios dejan en blanco?

bio: z.string().trim().max(280).optional().or(z.literal(""))

TextInput vacío devuelve "", no undefined.
Acepta "" con .or(z.literal("")) o transforma a undefined.

¿Cómo muestro errores solo después de que el usuario envía una vez?

const { isSubmitted } = formState;
{ (isTouched || isSubmitted) && error && <Text>{error.message}</Text> }

Combina isTouched e isSubmitted para una primera edición indulgente, estricta después del intento de envío.
mode: "onTouched" aún valida campos tempranos antes del primer envío - ajusta mode si es necesario.

¿Cómo manejo campos TextInput numéricos?

quantity: z.coerce.number().positive("Introduce un número positivo")

keyboardType="number-pad" no cambia el tipo JS - el valor sigue siendo una cadena hasta la coerción.
La cadena vacía se fuerza a NaN - agrega .min(1) en un paso de cadena o mapa de errores personalizado para una copia más clara.

¿Puedo reutilizar el mismo esquema para formularios y respuestas de API?

Sí - analiza JSON de API con UserSchema.parse(json) y valida formularios con zodResolver(UserSchema).
Usa .pick() para formularios de edición que envían un subconjunto de campos.
Ver Tipificación de respuestas de API y Zod para patrones de frontera de fetch.

¿Cómo adjunto un error de refine a un campo específico?

.refine((data) => data.startDate <= data.endDate, {
  message: "La fecha de finalización debe ser posterior a la fecha de inicio",
  path: ["endDate"],
})

Sin path, el error se encuentra en la raíz del formulario - invisible junto a las entradas.
Múltiples refines pueden dirigirse a diferentes valores path.

¿Cómo asigno errores de validación del servidor a campos?

setError("email", { type: "server", message: "Email ya registrado" });
setFocus("email");

Recorre fieldErrors de la respuesta de la API.
Usa type: "server" para que las reglas del lado del cliente puedan coexistir.

¿Debo usar z.input o z.infer para generics useForm?

Usa z.infer (tipo de salida) cuando el esquema usa .coerce, .default, o .transform.
Usa z.input cuando el formulario contiene formas pre-transform (raro en móvil).
Cuando no estés seguro, z.infer coincide con lo que onSubmit recibe después de la validación.

¿Cómo valido una lista dinámica de campos?

const InviteSchema = z.object({
  emails: z.array(z.string().email("Email inválido")).min(1, "Agrega al menos una invitación"),
});

Empareja con useFieldArray de react-hook-form.
Zod reporta rutas de índice de array como emails.2 - asígnalas a la fila correcta en la interfaz de usuario.

¿Puedo localizar mensajes de error de Zod?

Pasa cadenas personalizadas a cada restricción: .min(8, t("password.min")).
O usa z.setErrorMap() globalmente para plantillas de mensajes compartidas.
Mantén cadenas de mensajes en tu capa i18n - Zod solo almacena la cadena final que RHF muestra.

¿Qué modo de validación se empareja mejor con Zod en móvil?

mode: "onTouched" + reValidateMode: "onChange" es la combinación habitual.
El primer desenfoque ejecuta Zod; las ediciones posteriores revalidan a medida que el usuario corrige errores.
Evita onChange para campos de texto libre largos - lucha contra la autocorrección y la escritura multilínea.

¿En qué se diferencia el Zod del formulario del Zod de la API?

Los esquemas de formulario aceptan cadenas de TextInput y coaccionan antes de comparar.
Los esquemas de API validan formas JSON desde el cable - los números ya pueden ser números.
Comparte una definición de objeto central, luego .extend() o envuelve con coerción específica del formulario en el borde.

Relacionado

react-hook-form en móvil - Controller, cadena de enfoque, y cableado de campo de rendimiento
Conceptos básicos de formularios - tipos de teclado, entradas controladas, y comportamiento de enfoque nativo
Controlador de teclado - desplaza campos enfocados a la vista mientras se edita
Accesibilidad en formularios - anuncia errores a VoiceOver y TalkBack
Tipificación de respuestas de API y Zod - valida JSON de red en los mismos esquemas
Mejores prácticas de formularios - envío sin conexión, recuperación de borrador, y patrones de reducción de pulsaciones

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).

Receta

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

import { zodResolver } from "@hookform/resolvers/zod";
import { Controller, useForm } from "react-hook-form";
import { z } from "zod";
import { Pressable, StyleSheet, Text, TextInput, View } from "react-native";
 
const SignUpSchema = z
  .object({
    email: z.string().min(1, "Email es obligatorio").email("Introduce un email válido"),
    password: z.string().min(8, "Al menos 8 caracteres"),
    confirmPassword: z.string().min(1, "Confirma tu contraseña"),
  })
  .refine((data) => data.password === data.confirmPassword, {
    message: "Las contraseñas deben coincidir",
    path: ["confirmPassword"],
  });
 
type SignUpValues = z.infer<typeof SignUpSchema>;
 
export function SignUpForm() {
  const {
    control,
    handleSubmit,
    formState: { errors, isSubmitting },
  } = useForm<SignUpValues>({
    resolver: zodResolver(SignUpSchema),
    defaultValues: { email: "", password: "", confirmPassword: "" },
    mode: "onTouched",
  });
 
  function onSubmit(values: SignUpValues) {
    console.log(values);
  }
 
  return (
    <View style={styles.form}>
      <Controller
        control={control}
        name="email"
        render={({ field: { onChange, onBlur, value, ref } }) => (
          <TextInput
            ref={ref}
            value={value}
            onChangeText={onChange}
            onBlur={onBlur}
            keyboardType="email-address"
            autoCapitalize="none"
            placeholder="Email"
            style={styles.input}
          />
        )}
      />
      {errors.email && <Text style={styles.error}>{errors.email.message}</Text>}
 
      <Controller
        control={control}
        name="password"
        render={({ field: { onChange, onBlur, value, ref } }) => (
          <TextInput
            ref={ref}
            value={value}
            onChangeText={onChange}
            onBlur={onBlur}
            secureTextEntry
            placeholder="Contraseña"
            style={styles.input}
          />
        )}
      />
      {errors.password && <Text style={styles.error}>{errors.password.message}</Text>}
 
      <Controller
        control={control}
        name="confirmPassword"
        render={({ field: { onChange, onBlur, value, ref } }) => (
          <TextInput
            ref={ref}
            value={value}
            onChangeText={onChange}
            onBlur={onBlur}
            secureTextEntry
            placeholder="Confirmar contraseña"
            style={styles.input}
          />
        )}
      />
      {errors.confirmPassword && (
        <Text style={styles.error}>{errors.confirmPassword.message}</Text>
      )}
 
      <Pressable onPress={handleSubmit(onSubmit)} disabled={isSubmitting} style={styles.button}>
        <Text style={styles.buttonText}>Crear cuenta</Text>
      </Pressable>
    </View>
  );
}
 
const styles = StyleSheet.create({
  form: { gap: 12, padding: 16 },
  input: {
    borderWidth: 1,
    borderColor: "#d1d5db",
    borderRadius: 8,
    paddingHorizontal: 12,
    paddingVertical: 10,
    fontSize: 16,
  },
  error: { color: "#dc2626", fontSize: 13 },
  button: {
    backgroundColor: "#2563eb",
    borderRadius: 8,
    paddingVertical: 12,
    alignItems: "center",
  },
  buttonText: { color: "#fff", fontWeight: "600" },
});

Cuándo usarlo:

Cualquier formulario donde las reglas de validación deben coincidir con tu esquema de solicitud de API.
Reglas entre campos - confirmación de contraseña, rangos de fechas, campos requeridos condicionalmente.
Compartir esquemas entre formularios móviles y análisis en la capa de fetch (ver Tipificación de respuestas de API y Zod).
Mensajes de error localizados derivados de una definición de esquema única.
Evitar que las quirks de cadena de TextInput rompan la validación numérica o booleana.

Ejemplo de trabajo

// lib/schemas/profile.ts - compartido entre formulario y cliente de API
import { z } from "zod";
 
export const ProfileSchema = z.object({
  displayName: z
    .string()
    .trim()
    .min(1, "El nombre de usuario es obligatorio")
    .max(40, "Mantenlo bajo 40 caracteres"),
  bio: z
    .string()
    .max(280, "La biografía debe tener 280 caracteres o menos")
    .optional()
    .or(z.literal("")),
  age: z
    .string()
    .min(1, "La edad es obligatoria")
    .pipe(
      z.coerce
        .number({ invalid_type_error: "Introduce un número" })
        .int("Solo números enteros")
        .min(13, "Debes tener al menos 13 años")
        .max(120, "Introduce una edad realista")
    ),
  newsletter: z.boolean().default(false),
});
 
export type ProfileValues = z.infer<typeof ProfileSchema>;
 
export const ProfileUpdateSchema = ProfileSchema.pick({
  displayName: true,
  bio: true,
  newsletter: true,
});
 
export type ProfileUpdateValues = z.infer<typeof ProfileUpdateSchema>;

// components/form/ValidatedTextField.tsx
import { Controller, type Control, type FieldPath, type FieldValues } from "react-hook-form";
import { StyleSheet, Text, TextInput, type TextInputProps, View } from "react-native";
 
interface ValidatedTextFieldProps<T extends FieldValues>
  extends Omit<TextInputProps, "value" | "onChangeText"> {
  control: Control<T>;
  name: FieldPath<T>;
  label: string;
}
 
export function ValidatedTextField<T extends FieldValues>({
  control,
  name,
  label,
  ...inputProps
}: ValidatedTextFieldProps<T>) {
  return (
    <Controller
      control={control}
      name={name}
      render={({ field: { onChange, onBlur, value, ref }, fieldState: { error, isTouched } }) => (
        <View style={styles.field}>
          <Text style={styles.label}>{label}</Text>
          <TextInput
            ref={ref}
            value={value ?? ""}
            onChangeText={onChange}
            onBlur={onBlur}
            style={[styles.input, isTouched && error && styles.inputError]}
            accessibilityLabel={label}
            accessibilityHint={error?.message}
            {...inputProps}
          />
          {isTouched && error && (
            <Text style={styles.error} accessibilityLiveRegion="polite">
              {error.message}
            </Text>
          )}
        </View>
      )}
    />
  );
}
 
const styles = StyleSheet.create({
  field: { gap: 6 },
  label: { fontSize: 14, fontWeight: "600", color: "#374151" },
  input: {
    borderWidth: 1,
    borderColor: "#d1d5db",
    borderRadius: 8,
    paddingHorizontal: 12,
    paddingVertical: 10,
    fontSize: 16,
    backgroundColor: "#fff",
  },
  inputError: { borderColor: "#dc2626" },
  error: { color: "#dc2626", fontSize: 13 },
});

// app/settings/profile.tsx - enviar con asignación de errores del servidor
import { zodResolver } from "@hookform/resolvers/zod";
import { useForm } from "react-hook-form";
import { Controller } from "react-hook-form";
import { Alert, Pressable, StyleSheet, Switch, Text, View } from "react-native";
import { KeyboardAwareScrollView } from "react-native-keyboard-controller";
import { ProfileSchema, type ProfileValues } from "../../lib/schemas/profile";
import { ValidatedTextField } from "../../components/form/ValidatedTextField";
 
type ApiFieldErrors = Partial<Record<keyof ProfileValues, string>>;
 
async function saveProfile(
  values: ProfileValues
): Promise<{ ok: true } | { ok: false; fieldErrors?: ApiFieldErrors; message?: string }> {
  const res = await fetch("https://api.example.com/v1/profile", {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(values),
  });
  const json: unknown = await res.json();
  if (!res.ok) {
    const body = json as { fieldErrors?: ApiFieldErrors; message?: string };
    return { ok: false, fieldErrors: body.fieldErrors, message: body.message };
  }
  return { ok: true };
}
 
export default function ProfileScreen() {
  const {
    control,
    handleSubmit,
    setError,
    setFocus,
    formState: { isSubmitting, isDirty },
  } = useForm<ProfileValues>({
    resolver: zodResolver(ProfileSchema),
    defaultValues: {
      displayName: "",
      bio: "",
      age: "",
      newsletter: false,
    },
    mode: "onTouched",
    reValidateMode: "onChange",
  });
 
  async function onSubmit(values: ProfileValues) {
    const result = await saveProfile(values);
    if (result.ok) {
      Alert.alert("Guardado", "Tu perfil ha sido actualizado.");
      return;
    }
    if (result.fieldErrors) {
      for (const [field, message] of Object.entries(result.fieldErrors)) {
        setError(field as keyof ProfileValues, { type: "server", message });
      }
      const first = Object.keys(result.fieldErrors)[0] as keyof ProfileValues;
      setFocus(first);
      return;
    }
    Alert.alert("Error al guardar", result.message ?? "Intenta de nuevo.");
  }
 
  return (
    <KeyboardAwareScrollView contentContainerStyle={styles.scroll} keyboardShouldPersistTaps="handled">
      <ValidatedTextField control={control} name="displayName" label="Nombre de usuario" />
 
      <ValidatedTextField
        control={control}
        name="bio"
        label="Biografía"
        multiline
        numberOfLines={3}
        style={styles.multiline}
      />
 
      <ValidatedTextField
        control={control}
        name="age"
        label="Edad"
        keyboardType="number-pad"
      />
 
      <View style={styles.switchRow}>
        <Text style={styles.switchLabel}>Boletín de correo electrónico</Text>
        <Controller
          control={control}
          name="newsletter"
          render={({ field: { value, onChange } }) => (
            <Switch value={value} onValueChange={onChange} />
          )}
        />
      </View>
 
      <Pressable
        onPress={handleSubmit(onSubmit)}
        disabled={isSubmitting || !isDirty}
        style={[styles.button, (!isDirty || isSubmitting) && styles.buttonDisabled]}
      >
        <Text style={styles.buttonText}>{isSubmitting ? "Guardando…" : "Guardar cambios"}</Text>
      </Pressable>
    </KeyboardAwareScrollView>
  );
}
 
const styles = StyleSheet.create({
  scroll: { padding: 16, gap: 16 },
  multiline: { minHeight: 88, textAlignVertical: "top" },
  switchRow: { flexDirection: "row", alignItems: "center", justifyContent: "space-between" },
  switchLabel: { fontSize: 16 },
  button: {
    backgroundColor: "#2563eb",
    borderRadius: 8,
    paddingVertical: 12,
    alignItems: "center",
    marginTop: 8,
  },
  buttonDisabled: { opacity: 0.5 },
  buttonText: { color: "#fff", fontWeight: "600" },
});

Lo que esto demuestra:

Un único ProfileSchema impulsa tanto los tipos en tiempo de compilación como la validación en tiempo de ejecución.
.trim(), .coerce.number(), y .optional().or(z.literal("")) manejan las realidades de cadena de TextInput.
ValidatedTextField muestra errores solo después del toque - mejor UX en móvil que validar en cada carácter.
setError + setFocus asigna fieldErrors del servidor a mensajes en línea bajo la entrada correcta.
ProfileUpdateSchema.pick() reutiliza definiciones de campo para un formulario de edición parcial sin duplicar reglas.

Análisis profundo

Cómo funciona

Defines un esquema de Zod que describe la forma, restricciones y mensajes de error.
zodResolver(Schema) adapta ese esquema al espacio resolver de react-hook-form.
Al enviar (o por mode), RHF pasa valores actuales a Zod; los fallos se convierten en formState.errors con clave de ruta de campo.
z.infer<typeof Schema> exporta el tipo de TypeScript - no hay interfaz paralela que se desvíe.
Zod se ejecuta en archivos .ts simples sin JSX, por lo que Metro puede importar esquemas de clientes de API, tareas de fondo y pruebas.

Reglas de un vistazo

Helper de Zod	Uso en formulario móvil
`z.string().min(1)`	Campos de texto requeridos (después de `.trim()`)
`z.string().email()`	Email `TextInput` con `keyboardType="email-address"`
`z.coerce.number()`	Campos numéricos - `TextInput` siempre devuelve cadenas
`z.boolean()`	Valores de `Switch` via `Controller`
`z.enum(["a", "b"])`	Controles segmentados y selecciones de selector
`.optional()`	El campo puede estar ausente del objeto
`.nullable()`	El campo puede ser `null` explícito de la API
`.default(false)`	Casilla desactivada sin registrar `undefined`
`.refine()`	Reglas entre campos con `path` dirigido a un campo
`.superRefine()`	Múltiples errores o rutas de índice de array

Cadenas vacías y campos opcionales

const OptionalBioSchema = z.object({
  bio: z
    .string()
    .trim()
    .max(280)
    .transform((s) => (s === "" ? undefined : s))
    .optional(),
});

Los usuarios dejan campos opcionales en blanco como "", no undefined.
Transforma cadenas vacías una vez en el esquema en lugar de limpiar en onSubmit.
Para campos requeridos, encadena .trim().min(1, "Requerido") para que la entrada solo de espacios en blanco falle.

Validación entre campos

const ChangePasswordSchema = z
  .object({
    currentPassword: z.string().min(1, "Introduce tu contraseña actual"),
    newPassword: z.string().min(8, "Al menos 8 caracteres"),
    confirmPassword: z.string().min(1, "Confirma tu nueva contraseña"),
  })
  .refine((data) => data.newPassword === data.confirmPassword, {
    message: "Las contraseñas deben coincidir",
    path: ["confirmPassword"],
  })
  .refine((data) => data.currentPassword !== data.newPassword, {
    message: "La nueva contraseña debe ser diferente de la actual",
    path: ["newPassword"],
  });

.refine() se ejecuta después del análisis de campo base - ideal para confirmación de contraseña.
Establece path para que el error se adjunte al TextInput correcto, no a la raíz del formulario.
Usa .superRefine() cuando una validación produce múltiples errores en diferentes rutas.

Notas de TypeScript

import { z } from "zod";
 
const OrderSchema = z.object({
  quantity: z.coerce.number().positive(),
  note: z.string().optional(),
});
 
type OrderInput = z.input<typeof OrderSchema>;   // antes de transforms/coerce
type OrderOutput = z.output<typeof OrderSchema>; // después - igual que z.infer cuando no hay transforms
type OrderValues = z.infer<typeof OrderSchema>;

Instala con npx expo install zod @hookform/resolvers react-hook-form.
Exporta Schema, type Values = z.infer<typeof Schema>, y helpers safeParse de un módulo.
Reutiliza esquemas de respuesta de API con .pick() / .omit() / .extend() para que las formas de lista, detalle y formulario se mantengan alineadas.

Patrones de visualización de errores

Patrón	Comportamiento	Mejor para
Mostrar al tocar	`isTouched && error`	UX móvil por defecto
Mostrar después del primer envío	`isSubmitted && error`	Formularios cortos con un CTA
Siempre mostrar	`error && message`	Formularios de cumplimiento críticos de accesibilidad
Banner resumen	Mensaje `errors.root` de raíz	Fallos de servidor que no son de campo

// Mostrar un error de servidor que no es de campo
setError("root", { type: "server", message: "Red no disponible. Intenta de nuevo." });
{errors.root && <Text style={styles.banner}>{errors.root.message}</Text>}

Errores comunes

Duplicar tipos y esquemas - Mantener una interface Profile separada de ProfileSchema se desvía en el primer cambio de API. Solución: Exporta solo z.infer<typeof ProfileSchema>.
Validar números sin coerción - z.number() falla cuando TextInput entrega "25" como una cadena. Solución: z.coerce.number() o z.string().regex(/^\d+$/).transform(Number).
.optional() vs cadena vacía - Campo bio opcional con "" falla z.string().email() encadenado después. Solución: Recorta y transforma "" - undefined, o usa .or(z.literal("")).
Mostrar errores antes de tocar - Validar onChange en cada pulsación de tecla frustra a los usuarios móviles. Solución: mode: "onTouched" y renderiza isTouched && error.
Coincidencia de contraseña en ruta incorrecta - .refine() sin path pone el error en la raíz _form. Solución: path: ["confirmPassword"] para que el mensaje se encuentre bajo el campo correcto.
Campos de API que aceptan valores nulos en formularios - Backend envía middleName: null pero el formulario usa "". Solución: Normaliza en defaultValues y esquema con .nullable().transform(v => v ?? "").
Esquema monolítico gigante - Un esquema de 40 campos hace que las rutas de error sean difíciles de leer. Solución: Compone esquemas de paso y fusiona con .merge() para asistentes, o valida por paso con .pick().

Alternativas

Alternativa	Úsalo cuando	No lo uses cuando
Zod + `zodResolver`	Por defecto para formularios RN tipificados compartidos con capa de API	Casilla única con un `useState` local trivial
Yup + `yupResolver`	El equipo ya se estandarizó en Yup	Aplicaciones de campo verde donde Zod coincide con tus esquemas de fetch
`rules` en línea en `Controller`	1-2 campos triviales (`required: true`)	Reglas entre campos o esquemas reutilizados en el lado del servidor
Valibot / ArkType	El tamaño del bundle es la restricción máxima	Ya compartes esquemas de Zod con la aplicación web y backend
`safeParse` manual en `onSubmit`	Prototipo sin RHF	Formularios de producción que necesitan estado de toque por campo y `setError`

FAQs

¿Cómo instalo Zod y el resolver en Expo SDK 57?

npx expo install zod @hookform/resolvers react-hook-form

expo install fija versiones compatibles con tu lockfile.
Importa esquemas de archivos .ts simples - sin configuración de módulo nativo.

¿Cuál es la diferencia entre parse y safeParse en formularios?

zodResolver usa parse internamente - los fallos de validación se convierten automáticamente en errores de campo RHF.
Usa safeParse en clientes de API cuando quieras ramificarte sin lanzar.
En onSubmit, los valores ya están validados - confía en el tipo que RHF pasa.

¿Cómo valido campos opcionales que los usuarios dejan en blanco?

bio: z.string().trim().max(280).optional().or(z.literal(""))

TextInput vacío devuelve "", no undefined.
Acepta "" con .or(z.literal("")) o transforma a undefined.

¿Cómo muestro errores solo después de que el usuario envía una vez?

const { isSubmitted } = formState;
{ (isTouched || isSubmitted) && error && <Text>{error.message}</Text> }

Combina isTouched e isSubmitted para una primera edición indulgente, estricta después del intento de envío.
mode: "onTouched" aún valida campos tempranos antes del primer envío - ajusta mode si es necesario.

¿Cómo manejo campos TextInput numéricos?

quantity: z.coerce.number().positive("Introduce un número positivo")

keyboardType="number-pad" no cambia el tipo JS - el valor sigue siendo una cadena hasta la coerción.
La cadena vacía se fuerza a NaN - agrega .min(1) en un paso de cadena o mapa de errores personalizado para una copia más clara.

¿Puedo reutilizar el mismo esquema para formularios y respuestas de API?

Sí - analiza JSON de API con UserSchema.parse(json) y valida formularios con zodResolver(UserSchema).
Usa .pick() para formularios de edición que envían un subconjunto de campos.
Ver Tipificación de respuestas de API y Zod para patrones de frontera de fetch.

¿Cómo adjunto un error de refine a un campo específico?

.refine((data) => data.startDate <= data.endDate, {
  message: "La fecha de finalización debe ser posterior a la fecha de inicio",
  path: ["endDate"],
})

Sin path, el error se encuentra en la raíz del formulario - invisible junto a las entradas.
Múltiples refines pueden dirigirse a diferentes valores path.

¿Cómo asigno errores de validación del servidor a campos?

setError("email", { type: "server", message: "Email ya registrado" });
setFocus("email");

Recorre fieldErrors de la respuesta de la API.
Usa type: "server" para que las reglas del lado del cliente puedan coexistir.

¿Debo usar z.input o z.infer para generics useForm?

Usa z.infer (tipo de salida) cuando el esquema usa .coerce, .default, o .transform.
Usa z.input cuando el formulario contiene formas pre-transform (raro en móvil).
Cuando no estés seguro, z.infer coincide con lo que onSubmit recibe después de la validación.

¿Cómo valido una lista dinámica de campos?

const InviteSchema = z.object({
  emails: z.array(z.string().email("Email inválido")).min(1, "Agrega al menos una invitación"),
});

Empareja con useFieldArray de react-hook-form.
Zod reporta rutas de índice de array como emails.2 - asígnalas a la fila correcta en la interfaz de usuario.

¿Puedo localizar mensajes de error de Zod?

Pasa cadenas personalizadas a cada restricción: .min(8, t("password.min")).
O usa z.setErrorMap() globalmente para plantillas de mensajes compartidas.
Mantén cadenas de mensajes en tu capa i18n - Zod solo almacena la cadena final que RHF muestra.

¿Qué modo de validación se empareja mejor con Zod en móvil?

mode: "onTouched" + reValidateMode: "onChange" es la combinación habitual.
El primer desenfoque ejecuta Zod; las ediciones posteriores revalidan a medida que el usuario corrige errores.
Evita onChange para campos de texto libre largos - lucha contra la autocorrección y la escritura multilínea.

¿En qué se diferencia el Zod del formulario del Zod de la API?

Los esquemas de formulario aceptan cadenas de TextInput y coaccionan antes de comparar.
Los esquemas de API validan formas JSON desde el cable - los números ya pueden ser números.
Comparte una definición de objeto central, luego .extend() o envuelve con coerción específica del formulario en el borde.

Relacionado

react-hook-form en móvil - Controller, cadena de enfoque, y cableado de campo de rendimiento
Conceptos básicos de formularios - tipos de teclado, entradas controladas, y comportamiento de enfoque nativo
Controlador de teclado - desplaza campos enfocados a la vista mientras se edita
Accesibilidad en formularios - anuncia errores a VoiceOver y TalkBack
Tipificación de respuestas de API y Zod - valida JSON de red en los mismos esquemas
Mejores prácticas de formularios - envío sin conexión, recuperación de borrador, y patrones de reducción de pulsaciones

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).

Validación con Zod

Buscar en la documentación

Validación con Zod