Validação com Zod

Q: Como instalo Zod e o resolver no Expo SDK 57?

expo install fixa versões compatíveis com seu lockfile. Importe schemas de arquivos .ts puros - nenhuma configuração de módulo nativo.

Q: Qual a diferença entre parse e safeParse em formulários?

zodResolver usa parse internamente - falhas de validação se tornam erros de campo RHF automaticamente. Use safeParse em clientes de API quando quiser ramificar sem lançar exceções. Em onSubmit, os valores já estão validados - confie no tipo que RHF passa.

Q: Como valido campos opcionais que os usuários deixam em branco?

TextInput vazio retorna "", não undefined. Aceite "" com .or(z.literal("")) ou transforme para undefined.

Q: Como mostro erros apenas depois que o usuário envia uma vez?

Combine isTouched e isSubmitted para uma primeira edição tolerante, rigorosa após a tentativa de envio. mode: "onTouched" ainda valida campos iniciais antes do primeiro envio - ajuste mode se necessário.

Q: Como lidar com campos TextInput numéricos?

keyboardType="number-pad" não muda o tipo JS - o valor ainda é uma string até a coerção. String vazia se coerge para NaN - adicione .min(1) em uma etapa de string ou um mapa de erros personalizado para uma cópia mais clara.

Q: Posso reutilizar o mesmo schema para formulários e respostas de API?

Sim - analise o JSON da API com UserSchema.parse(json) e valide formulários com zodResolver(UserSchema). Use .pick() para formulários de edição que enviam um subconjunto de campos. Veja Tipando Respostas de API e Zod para padrões de limite de fetch.

Q: Como anexo um erro de refine a um campo específico?

Sem path, o erro vai para a raiz do formulário - invisível ao lado dos inputs. Múltiplos refines podem direcionar para diferentes valores de path.

Q: Como mapeio erros de validação do servidor para campos?

Itere sobre fieldErrors da resposta da API. Use type: "server" para que as regras do lado do cliente possam coexistir.

Q: Devo usar z.input ou z.infer para genéricos do useForm?

Use z.infer (tipo de saída) quando o schema usar .coerce, .default ou .transform. Use z.input quando o formulário contiver formas pré-transformação (raro no mobile). Em caso de dúvida, z.infer corresponde ao que onSubmit recebe após a validação.

Q: Como valido uma lista dinâmica de campos?

Emparelhe com useFieldArray do react-hook-form. Zod relata caminhos de índice de array como emails.2 - mapeie-os para a linha correta na UI.

Zod descreve como os dados válidos se parecem em tempo de execução e infere o mesmo tipo TypeScript que seu IDE autocompleta. No mobile, isso importa em dobro: TextInput sempre entrega strings, e os usuários esperam erros inline sob o campo que acabaram de deixar - não um modal após tocar em Enviar.

Receita

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

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 é obrigatório").email("Insira um email válido"),
    password: z.string().min(8, "Mínimo de 8 caracteres"),
    confirmPassword: z.string().min(1, "Confirme sua senha"),
  })
  .refine((data) => data.password === data.confirmPassword, {
    message: "As senhas devem 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="Senha"
            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="Confirme a senha"
            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}>Criar conta</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" },
});

Quando usar isso:

Qualquer formulário onde as regras de validação devam corresponder ao schema da sua requisição de API.
Regras entre campos - confirmação de senha, intervalos de datas, campos obrigatórios condicionais.
Compartilhamento de schemas entre formulários mobile e parsing na camada de fetch (veja Tipando Respostas de API e Zod).
Mensagens de erro localizadas derivadas de uma única definição de schema.
Prevenção de peculiaridades de string do TextInput quebrando validações numéricas ou booleanas.

Exemplo de Trabalho

// lib/schemas/profile.ts - compartilhado entre formulário e cliente de API
import { z } from "zod";
 
export const ProfileSchema = z.object({
  displayName: z
    .string()
    .trim()
    .min(1, "Nome de exibição é obrigatório")
    .max(40, "Mantenha em menos de 40 caracteres"),
  bio: z
    .string()
    .max(280, "Bio deve ter no máximo 280 caracteres")
    .optional()
    .or(z.literal("")),
  age: z
    .string()
    .min(1, "Idade é obrigatória")
    .pipe(
      z.coerce
        .number({ invalid_type_error: "Insira um número" })
        .int("Apenas números inteiros")
        .min(13, "Você deve ter pelo menos 13 anos")
        .max(120, "Insira uma idade 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 - envio com mapeamento de erro do 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("Salvo", "Seu perfil foi atualizado.");
      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("Falha ao salvar", result.message ?? "Tente novamente.");
  }
 
  return (
    <KeyboardAwareScrollView contentContainerStyle={styles.scroll} keyboardShouldPersistTaps="handled">
      <ValidatedTextField control={control} name="displayName" label="Nome de exibição" />
 
      <ValidatedTextField
        control={control}
        name="bio"
        label="Bio"
        multiline
        numberOfLines={3}
        style={styles.multiline}
      />
 
      <ValidatedTextField
        control={control}
        name="age"
        label="Idade"
        keyboardType="number-pad"
      />
 
      <View style={styles.switchRow}>
        <Text style={styles.switchLabel}>Newsletter por email</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 ? "Salvando…" : "Salvar alterações"}</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" },
});

O que isso demonstra:

Um único ProfileSchema controla tanto os tipos em tempo de compilação quanto a validação em tempo de execução.
.trim(), .coerce.number() e .optional().or(z.literal("")) lidam com as realidades das strings do TextInput.
ValidatedTextField mostra erros apenas após o toque - melhor UX mobile do que validar a cada caractere.
setError + setFocus mapeia fieldErrors do servidor para mensagens inline sob o input correto.
ProfileUpdateSchema.pick() reutiliza definições de campo para um formulário de edição parcial sem duplicar regras.

Mergulho Profundo

Como Funciona

Você define um schema Zod descrevendo a forma, restrições e mensagens de erro.
zodResolver(Schema) adapta esse schema para o slot resolver do react-hook-form.
Ao enviar (ou por mode), RHF passa os valores atuais para Zod; falhas se tornam formState.errors com chave pelo caminho do campo.
z.infer<typeof Schema> exporta o tipo TypeScript - sem interface paralelo para divergir.
Zod roda em arquivos .ts puros sem JSX, então Metro pode importar schemas de clientes de API, tarefas em segundo plano e testes.

Regras em Resumo

Helper Zod	Uso em formulário mobile
`z.string().min(1)`	Campos de texto obrigatórios (após `.trim()`)
`z.string().email()`	`TextInput` de email com `keyboardType="email-address"`
`z.coerce.number()`	Campos numéricos - `TextInput` sempre retorna strings
`z.boolean()`	Valores de `Switch` via `Controller`
`z.enum(["a", "b"])`	Controles segmentados e seleções de picker
`.optional()`	Campo pode estar ausente do objeto
`.nullable()`	Campo pode ser `null` explícito da API
`.default(false)`	Checkbox desmarcado sem registrar `undefined`
`.refine()`	Regras entre campos com `path` direcionando para um campo
`.superRefine()`	Múltiplos erros ou caminhos de índice de array

Strings Vazias e Campos Opcionais

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

Usuários deixam campos opcionais em branco como "", não undefined.
Transforme strings vazias uma vez no schema em vez de limpar em onSubmit.
Para campos obrigatórios, encadeie .trim().min(1, "Obrigatório") para que a entrada apenas com espaços falhe.

Validação Entre Campos

const ChangePasswordSchema = z
  .object({
    currentPassword: z.string().min(1, "Insira sua senha atual"),
    newPassword: z.string().min(8, "Mínimo de 8 caracteres"),
    confirmPassword: z.string().min(1, "Confirme sua nova senha"),
  })
  .refine((data) => data.newPassword === data.confirmPassword, {
    message: "As senhas devem coincidir",
    path: ["confirmPassword"],
  })
  .refine((data) => data.currentPassword !== data.newPassword, {
    message: "A nova senha deve ser diferente da atual",
    path: ["newPassword"],
  });

.refine() roda após o parsing do campo base - ideal para confirmação de senha.
Defina path para que o erro se anexe ao TextInput correto, não à raiz do formulário.
Use .superRefine() quando uma validação produz múltiplos erros em caminhos diferentes.

Notas 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>; // depois - igual a z.infer quando não há transforms
type OrderValues = z.infer<typeof OrderSchema>;

Instale com npx expo install zod @hookform/resolvers react-hook-form.
Exporte Schema, type Values = z.infer<typeof Schema>, e helpers safeParse de um único módulo.
Reutilize schemas de resposta de API com .pick() / .omit() / .extend() para que as formas de lista, detalhe e formulário permaneçam alinhadas.

Padrões de Exibição de Erro

Padrão	Comportamento	Melhor para
Mostrar ao tocar	`isTouched && error`	UX mobile padrão
Mostrar após o primeiro envio	`isSubmitted && error`	Formulários curtos com um único CTA
Mostrar sempre	`error && message`	Formulários críticos de conformidade de acessibilidade
Banner de resumo	Mensagem `errors.root` raiz	Falhas de servidor não relacionadas a campos

// Exibir um erro de servidor não relacionado a campo
setError("root", { type: "server", message: "Rede indisponível. Tente novamente." });
{errors.root && <Text style={styles.banner}>{errors.root.message}</Text>}

Armadilhas

Duplicar tipos e schemas - Manter uma interface Profile separada de ProfileSchema diverge na primeira alteração de API. Correção: Exporte apenas z.infer<typeof ProfileSchema>.
Validar números sem coerção - z.number() falha quando TextInput entrega "25" como string. Correção: z.coerce.number() ou z.string().regex(/^\d+$/).transform(Number).
.optional() vs string vazia - Campo de bio opcional com "" falha z.string().email() encadeado depois. Correção: Remova espaços e transforme "" → undefined, ou use .or(z.literal("")).
Mostrar erros antes do toque - Validar onChange a cada pressionamento de tecla frustra usuários mobile. Correção: mode: "onTouched" e renderize isTouched && error.
Correspondência de senha no caminho errado - .refine() sem path coloca o erro na raiz do formulário. Correção: path: ["confirmPassword"] para que a mensagem fique sob o campo correto.
Campos de API anuláveis em formulários - Backend envia middleName: null mas o formulário usa "". Correção: Normalize em defaultValues e schema com .nullable().transform(v => v ?? "").
Schema monolítico gigante - Um schema de 40 campos torna os caminhos de erro difíceis de ler. Correção: Componha schemas de etapas e mescle com .merge() para assistentes, ou valide por etapa com .pick().

Alternativas

Alternativa	Use Quando	Não Use Quando
Zod + `zodResolver`	Padrão para formulários RN tipados compartilhados com a camada de API	Checkbox único com um `useState` local
Yup + `yupResolver`	Equipe já padronizada em Yup	Novos aplicativos onde Zod corresponde aos seus schemas de fetch
`rules` inline no `Controller`	1–2 campos triviais (`required: true`)	Regras entre campos ou schemas reutilizados do lado do servidor
Valibot / ArkType	Tamanho do bundle é a principal restrição	Você já compartilha schemas Zod com o backend e o aplicativo web
`safeParse` manual em `onSubmit`	Protótipo sem RHF	Formulários de produção que precisam de estado de toque por campo e `setError`

FAQs

Como instalo Zod e o resolver no Expo SDK 57?

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

expo install fixa versões compatíveis com seu lockfile.
Importe schemas de arquivos .ts puros - nenhuma configuração de módulo nativo.

Qual a diferença entre parse e safeParse em formulários?

zodResolver usa parse internamente - falhas de validação se tornam erros de campo RHF automaticamente.
Use safeParse em clientes de API quando quiser ramificar sem lançar exceções.
Em onSubmit, os valores já estão validados - confie no tipo que RHF passa.

Como valido campos opcionais que os usuários deixam em branco?

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

TextInput vazio retorna "", não undefined.
Aceite "" com .or(z.literal("")) ou transforme para undefined.

Como mostro erros apenas depois que o usuário envia uma vez?

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

Combine isTouched e isSubmitted para uma primeira edição tolerante, rigorosa após a tentativa de envio.
mode: "onTouched" ainda valida campos iniciais antes do primeiro envio - ajuste mode se necessário.

Como lidar com campos TextInput numéricos?

quantity: z.coerce.number().positive("Insira um número positivo")

keyboardType="number-pad" não muda o tipo JS - o valor ainda é uma string até a coerção.
String vazia se coerge para NaN - adicione .min(1) em uma etapa de string ou um mapa de erros personalizado para uma cópia mais clara.

Posso reutilizar o mesmo schema para formulários e respostas de API?

Sim - analise o JSON da API com UserSchema.parse(json) e valide formulários com zodResolver(UserSchema).
Use .pick() para formulários de edição que enviam um subconjunto de campos.
Veja Tipando Respostas de API e Zod para padrões de limite de fetch.

Como anexo um erro de refine a um campo específico?

.refine((data) => data.startDate <= data.endDate, {
  message: "A data de término deve ser posterior à data de início",
  path: ["endDate"],
})

Sem path, o erro vai para a raiz do formulário - invisível ao lado dos inputs.
Múltiplos refines podem direcionar para diferentes valores de path.

Como mapeio erros de validação do servidor para campos?

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

Itere sobre fieldErrors da resposta da API.
Use type: "server" para que as regras do lado do cliente possam coexistir.

Devo usar z.input ou z.infer para genéricos do useForm?

Use z.infer (tipo de saída) quando o schema usar .coerce, .default ou .transform.
Use z.input quando o formulário contiver formas pré-transformação (raro no mobile).
Em caso de dúvida, z.infer corresponde ao que onSubmit recebe após a validação.

Como valido uma lista dinâmica de campos?

const InviteSchema = z.object({
  emails: z.array(z.string().email("Email inválido")).min(1, "Adicione pelo menos um convite"),
});

Emparelhe com useFieldArray do react-hook-form.
Zod relata caminhos de índice de array como emails.2 - mapeie-os para a linha correta na UI.

Posso localizar mensagens de erro Zod?

Passe strings personalizadas para cada restrição: .min(8, t("password.min")).
Ou use z.setErrorMap() globalmente para modelos de mensagens compartilhados.
Mantenha as strings de mensagem em sua camada de i18n - Zod apenas armazena a string final que RHF exibe.

Qual modo de validação combina melhor com Zod no mobile?

mode: "onTouched" + reValidateMode: "onChange" é a combinação usual.
O primeiro blur executa Zod; edições subsequentes revalidam enquanto o usuário corrige erros.
Evite onChange para campos de texto longo - ele luta contra o autocorreção e a digitação multilinha.

Qual a diferença entre Zod de formulário e Zod de API?

Schemas de formulário aceitam strings TextInput e fazem coerção antes de comparar.
Schemas de API validam formas JSON da rede - números podem já ser números.
Compartilhe uma definição de objeto principal, então .extend() ou envolva com coerção específica do formulário na borda.

Relacionados

react-hook-form no Mobile - Controller, cadeia de foco e conexão de campos de forma performática
Fundamentos de Formulários - tipos de teclado, inputs controlados e comportamento de foco nativo
Keyboard Controller - rola os campos focados para a visualização durante a edição
Acessibilidade em Formulários - anuncia erros para VoiceOver e TalkBack
Tipando Respostas de API e Zod - valida JSON de rede com os mesmos schemas
Melhores Práticas de Formulários - envio offline, recuperação de rascunho e padrões de redução de toques

Versões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).

Receita

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

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 é obrigatório").email("Insira um email válido"),
    password: z.string().min(8, "Mínimo de 8 caracteres"),
    confirmPassword: z.string().min(1, "Confirme sua senha"),
  })
  .refine((data) => data.password === data.confirmPassword, {
    message: "As senhas devem 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="Senha"
            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="Confirme a senha"
            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}>Criar conta</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" },
});

Quando usar isso:

Qualquer formulário onde as regras de validação devam corresponder ao schema da sua requisição de API.
Regras entre campos - confirmação de senha, intervalos de datas, campos obrigatórios condicionais.
Compartilhamento de schemas entre formulários mobile e parsing na camada de fetch (veja Tipando Respostas de API e Zod).
Mensagens de erro localizadas derivadas de uma única definição de schema.
Prevenção de peculiaridades de string do TextInput quebrando validações numéricas ou booleanas.

Exemplo de Trabalho

// lib/schemas/profile.ts - compartilhado entre formulário e cliente de API
import { z } from "zod";
 
export const ProfileSchema = z.object({
  displayName: z
    .string()
    .trim()
    .min(1, "Nome de exibição é obrigatório")
    .max(40, "Mantenha em menos de 40 caracteres"),
  bio: z
    .string()
    .max(280, "Bio deve ter no máximo 280 caracteres")
    .optional()
    .or(z.literal("")),
  age: z
    .string()
    .min(1, "Idade é obrigatória")
    .pipe(
      z.coerce
        .number({ invalid_type_error: "Insira um número" })
        .int("Apenas números inteiros")
        .min(13, "Você deve ter pelo menos 13 anos")
        .max(120, "Insira uma idade 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 - envio com mapeamento de erro do 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("Salvo", "Seu perfil foi atualizado.");
      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("Falha ao salvar", result.message ?? "Tente novamente.");
  }
 
  return (
    <KeyboardAwareScrollView contentContainerStyle={styles.scroll} keyboardShouldPersistTaps="handled">
      <ValidatedTextField control={control} name="displayName" label="Nome de exibição" />
 
      <ValidatedTextField
        control={control}
        name="bio"
        label="Bio"
        multiline
        numberOfLines={3}
        style={styles.multiline}
      />
 
      <ValidatedTextField
        control={control}
        name="age"
        label="Idade"
        keyboardType="number-pad"
      />
 
      <View style={styles.switchRow}>
        <Text style={styles.switchLabel}>Newsletter por email</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 ? "Salvando…" : "Salvar alterações"}</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" },
});

O que isso demonstra:

Um único ProfileSchema controla tanto os tipos em tempo de compilação quanto a validação em tempo de execução.
.trim(), .coerce.number() e .optional().or(z.literal("")) lidam com as realidades das strings do TextInput.
ValidatedTextField mostra erros apenas após o toque - melhor UX mobile do que validar a cada caractere.
setError + setFocus mapeia fieldErrors do servidor para mensagens inline sob o input correto.
ProfileUpdateSchema.pick() reutiliza definições de campo para um formulário de edição parcial sem duplicar regras.

Mergulho Profundo

Como Funciona

Você define um schema Zod descrevendo a forma, restrições e mensagens de erro.
zodResolver(Schema) adapta esse schema para o slot resolver do react-hook-form.
Ao enviar (ou por mode), RHF passa os valores atuais para Zod; falhas se tornam formState.errors com chave pelo caminho do campo.
z.infer<typeof Schema> exporta o tipo TypeScript - sem interface paralelo para divergir.
Zod roda em arquivos .ts puros sem JSX, então Metro pode importar schemas de clientes de API, tarefas em segundo plano e testes.

Regras em Resumo

Helper Zod	Uso em formulário mobile
`z.string().min(1)`	Campos de texto obrigatórios (após `.trim()`)
`z.string().email()`	`TextInput` de email com `keyboardType="email-address"`
`z.coerce.number()`	Campos numéricos - `TextInput` sempre retorna strings
`z.boolean()`	Valores de `Switch` via `Controller`
`z.enum(["a", "b"])`	Controles segmentados e seleções de picker
`.optional()`	Campo pode estar ausente do objeto
`.nullable()`	Campo pode ser `null` explícito da API
`.default(false)`	Checkbox desmarcado sem registrar `undefined`
`.refine()`	Regras entre campos com `path` direcionando para um campo
`.superRefine()`	Múltiplos erros ou caminhos de índice de array

Strings Vazias e Campos Opcionais

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

Usuários deixam campos opcionais em branco como "", não undefined.
Transforme strings vazias uma vez no schema em vez de limpar em onSubmit.
Para campos obrigatórios, encadeie .trim().min(1, "Obrigatório") para que a entrada apenas com espaços falhe.

Validação Entre Campos

const ChangePasswordSchema = z
  .object({
    currentPassword: z.string().min(1, "Insira sua senha atual"),
    newPassword: z.string().min(8, "Mínimo de 8 caracteres"),
    confirmPassword: z.string().min(1, "Confirme sua nova senha"),
  })
  .refine((data) => data.newPassword === data.confirmPassword, {
    message: "As senhas devem coincidir",
    path: ["confirmPassword"],
  })
  .refine((data) => data.currentPassword !== data.newPassword, {
    message: "A nova senha deve ser diferente da atual",
    path: ["newPassword"],
  });

.refine() roda após o parsing do campo base - ideal para confirmação de senha.
Defina path para que o erro se anexe ao TextInput correto, não à raiz do formulário.
Use .superRefine() quando uma validação produz múltiplos erros em caminhos diferentes.

Notas 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>; // depois - igual a z.infer quando não há transforms
type OrderValues = z.infer<typeof OrderSchema>;

Instale com npx expo install zod @hookform/resolvers react-hook-form.
Exporte Schema, type Values = z.infer<typeof Schema>, e helpers safeParse de um único módulo.
Reutilize schemas de resposta de API com .pick() / .omit() / .extend() para que as formas de lista, detalhe e formulário permaneçam alinhadas.

Padrões de Exibição de Erro

Padrão	Comportamento	Melhor para
Mostrar ao tocar	`isTouched && error`	UX mobile padrão
Mostrar após o primeiro envio	`isSubmitted && error`	Formulários curtos com um único CTA
Mostrar sempre	`error && message`	Formulários críticos de conformidade de acessibilidade
Banner de resumo	Mensagem `errors.root` raiz	Falhas de servidor não relacionadas a campos

// Exibir um erro de servidor não relacionado a campo
setError("root", { type: "server", message: "Rede indisponível. Tente novamente." });
{errors.root && <Text style={styles.banner}>{errors.root.message}</Text>}

Armadilhas

Duplicar tipos e schemas - Manter uma interface Profile separada de ProfileSchema diverge na primeira alteração de API. Correção: Exporte apenas z.infer<typeof ProfileSchema>.
Validar números sem coerção - z.number() falha quando TextInput entrega "25" como string. Correção: z.coerce.number() ou z.string().regex(/^\d+$/).transform(Number).
.optional() vs string vazia - Campo de bio opcional com "" falha z.string().email() encadeado depois. Correção: Remova espaços e transforme "" → undefined, ou use .or(z.literal("")).
Mostrar erros antes do toque - Validar onChange a cada pressionamento de tecla frustra usuários mobile. Correção: mode: "onTouched" e renderize isTouched && error.
Correspondência de senha no caminho errado - .refine() sem path coloca o erro na raiz do formulário. Correção: path: ["confirmPassword"] para que a mensagem fique sob o campo correto.
Campos de API anuláveis em formulários - Backend envia middleName: null mas o formulário usa "". Correção: Normalize em defaultValues e schema com .nullable().transform(v => v ?? "").
Schema monolítico gigante - Um schema de 40 campos torna os caminhos de erro difíceis de ler. Correção: Componha schemas de etapas e mescle com .merge() para assistentes, ou valide por etapa com .pick().

Alternativas

Alternativa	Use Quando	Não Use Quando
Zod + `zodResolver`	Padrão para formulários RN tipados compartilhados com a camada de API	Checkbox único com um `useState` local
Yup + `yupResolver`	Equipe já padronizada em Yup	Novos aplicativos onde Zod corresponde aos seus schemas de fetch
`rules` inline no `Controller`	1–2 campos triviais (`required: true`)	Regras entre campos ou schemas reutilizados do lado do servidor
Valibot / ArkType	Tamanho do bundle é a principal restrição	Você já compartilha schemas Zod com o backend e o aplicativo web
`safeParse` manual em `onSubmit`	Protótipo sem RHF	Formulários de produção que precisam de estado de toque por campo e `setError`

FAQs

Como instalo Zod e o resolver no Expo SDK 57?

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

expo install fixa versões compatíveis com seu lockfile.
Importe schemas de arquivos .ts puros - nenhuma configuração de módulo nativo.

Qual a diferença entre parse e safeParse em formulários?

zodResolver usa parse internamente - falhas de validação se tornam erros de campo RHF automaticamente.
Use safeParse em clientes de API quando quiser ramificar sem lançar exceções.
Em onSubmit, os valores já estão validados - confie no tipo que RHF passa.

Como valido campos opcionais que os usuários deixam em branco?

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

TextInput vazio retorna "", não undefined.
Aceite "" com .or(z.literal("")) ou transforme para undefined.

Como mostro erros apenas depois que o usuário envia uma vez?

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

Combine isTouched e isSubmitted para uma primeira edição tolerante, rigorosa após a tentativa de envio.
mode: "onTouched" ainda valida campos iniciais antes do primeiro envio - ajuste mode se necessário.

Como lidar com campos TextInput numéricos?

quantity: z.coerce.number().positive("Insira um número positivo")

keyboardType="number-pad" não muda o tipo JS - o valor ainda é uma string até a coerção.
String vazia se coerge para NaN - adicione .min(1) em uma etapa de string ou um mapa de erros personalizado para uma cópia mais clara.

Posso reutilizar o mesmo schema para formulários e respostas de API?

Sim - analise o JSON da API com UserSchema.parse(json) e valide formulários com zodResolver(UserSchema).
Use .pick() para formulários de edição que enviam um subconjunto de campos.
Veja Tipando Respostas de API e Zod para padrões de limite de fetch.

Como anexo um erro de refine a um campo específico?

.refine((data) => data.startDate <= data.endDate, {
  message: "A data de término deve ser posterior à data de início",
  path: ["endDate"],
})

Sem path, o erro vai para a raiz do formulário - invisível ao lado dos inputs.
Múltiplos refines podem direcionar para diferentes valores de path.

Como mapeio erros de validação do servidor para campos?

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

Itere sobre fieldErrors da resposta da API.
Use type: "server" para que as regras do lado do cliente possam coexistir.

Devo usar z.input ou z.infer para genéricos do useForm?

Use z.infer (tipo de saída) quando o schema usar .coerce, .default ou .transform.
Use z.input quando o formulário contiver formas pré-transformação (raro no mobile).
Em caso de dúvida, z.infer corresponde ao que onSubmit recebe após a validação.

Como valido uma lista dinâmica de campos?

const InviteSchema = z.object({
  emails: z.array(z.string().email("Email inválido")).min(1, "Adicione pelo menos um convite"),
});

Emparelhe com useFieldArray do react-hook-form.
Zod relata caminhos de índice de array como emails.2 - mapeie-os para a linha correta na UI.

Posso localizar mensagens de erro Zod?

Passe strings personalizadas para cada restrição: .min(8, t("password.min")).
Ou use z.setErrorMap() globalmente para modelos de mensagens compartilhados.
Mantenha as strings de mensagem em sua camada de i18n - Zod apenas armazena a string final que RHF exibe.

Qual modo de validação combina melhor com Zod no mobile?

mode: "onTouched" + reValidateMode: "onChange" é a combinação usual.
O primeiro blur executa Zod; edições subsequentes revalidam enquanto o usuário corrige erros.
Evite onChange para campos de texto longo - ele luta contra o autocorreção e a digitação multilinha.

Qual a diferença entre Zod de formulário e Zod de API?

Schemas de formulário aceitam strings TextInput e fazem coerção antes de comparar.
Schemas de API validam formas JSON da rede - números podem já ser números.
Compartilhe uma definição de objeto principal, então .extend() ou envolva com coerção específica do formulário na borda.

Relacionados

react-hook-form no Mobile - Controller, cadeia de foco e conexão de campos de forma performática
Fundamentos de Formulários - tipos de teclado, inputs controlados e comportamento de foco nativo
Keyboard Controller - rola os campos focados para a visualização durante a edição
Acessibilidade em Formulários - anuncia erros para VoiceOver e TalkBack
Tipando Respostas de API e Zod - valida JSON de rede com os mesmos schemas
Melhores Práticas de Formulários - envio offline, recuperação de rascunho e padrões de redução de toques

Versões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).

Validação com Zod

Buscar na documentação

Validação com Zod