react-hook-form no Mobile

Q: Por que não posso usar register() como na web?

React Native não tem DOM - register depende de ref + eventos de mudança nativos que TextInput não expõe da mesma forma. TextInput usa onChangeText, não onChange. Controller é a ponte suportada e lhe dá controle total sobre as props do teclado.

Q: Qual modo de validação devo usar no mobile?

Comece com mode: "onTouched" - erros aparecem após o usuário sair de um campo, não no meio da palavra. Adicione reValidateMode: "onChange" para que campos corrigidos limpem erros sem outro submit. Reserve mode: "onChange" para campos curtos como códigos promocionais onde feedback instantâneo ajuda.

Q: Como mudo o foco para o próximo campo quando o usuário toca em Return?

setFocus é embutido no useForm - nenhum mapeamento manual de ref necessário quando os nomes dos campos são registrados. Defina returnKeyType="done" no último campo e chame handleSubmit(onSubmit) em onSubmitEditing.

Q: Como foco o primeiro campo inválido após o submit?

O segundo argumento de handleSubmit é executado quando a validação falha. Combine com scrollTo de um ref em KeyboardAwareScrollView para formulários longos.

Q: react-hook-form funciona com TypeScript no Expo?

Sim - passe um genérico para useForm() e para Control em componentes de campo. Combine com zodResolver e z.infer para formulários totalmente tipados. Instale via npx expo install react-hook-form @hookform/resolvers zod.

Q: Como mostro um estado de carregamento no botão de submit?

Desestruture isSubmitting de formState. handleSubmit o define como true enquanto sua promise onSubmit assíncrona está pendente. Desabilite o Pressable e mude o texto do rótulo enquanto isSubmitting for true.

Q: Como resetar o formulário após uma chamada de API bem-sucedida?

reset() limpa erros, estado sujo e valores. Passe reset(partialValues) para manter alguns campos após o sucesso (ex: email para um passo de confirmação).

Q: Devo usar FormProvider?

Use-o quando múltiplos componentes filhos precisam de useFormContext() - passos de assistente, grupos de campos em modais, ou seções de formulário de design-system. Para um formulário de tela única, passar control para TextField é suficiente.

Q: Como react-hook-form se compara ao useState controlado no RN?

useState re-renderiza o componente proprietário a cada onChangeText. RHF armazena valores em refs e re-renderiza apenas fatias de formState inscritas. Para 1–2 campos a diferença é insignificante; após ~4 campos RHF vence em hardware de gama média.

Componentes TextInput do React Native são sempre controlados pelo lado nativo, mas você ainda quer um estado de formulário não controlado no thread JS. react-hook-form se inscreve em mudanças de campo em vez de re-renderizar a tela inteira a cada pressionamento de tecla - o padrão que mantém fluxos de cadastro e checkout com múltiplos campos fluidos em dispositivos Android de gama média.

Receita

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

import { Controller, useForm } from "react-hook-form";
import { Pressable, StyleSheet, Text, TextInput, View } from "react-native";
 
interface SignInValues {
  email: string;
  password: string;
}
 
export function SignInForm() {
  const {
    control,
    handleSubmit,
    formState: { errors, isSubmitting },
  } = useForm<SignInValues>({
    defaultValues: { email: "", password: "" },
    mode: "onTouched",
  });
 
  async function onSubmit(values: SignInValues) {
    await fetch("https://api.example.com/auth/login", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(values),
    });
  }
 
  return (
    <View style={styles.form}>
      <Controller
        control={control}
        name="email"
        rules={{ required: "O Email é obrigatório" }}
        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"
        rules={{ minLength: { value: 8, message: "Pelo menos 8 caracteres" } }}
        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>}
 
      <Pressable
        onPress={handleSubmit(onSubmit)}
        disabled={isSubmitting}
        style={styles.button}
      >
        <Text style={styles.buttonText}>{isSubmitting ? "Entrando…" : "Entrar"}</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:

Telas com mais de três campos TextInput onde useState por campo causa lentidão visível.
Listas de campos dinâmicas (endereços, itens de linha) via useFieldArray.
Formulários que compartilham validação com seu aplicativo web através de esquemas Zod.
Assistentes de múltiplos passos que precisam de uma única instância de formulário entre as etapas.
Qualquer fluxo onde você precise de guardas isDirty antes de navegar de volta.

Exemplo de Trabalho

// components/form/TextField.tsx - campo RN reutilizável conectado ao RHF
import { Controller, type Control, type FieldPath, type FieldValues } from "react-hook-form";
import { StyleSheet, Text, TextInput, type TextInputProps, View } from "react-native";
 
interface TextFieldProps<T extends FieldValues> extends Omit<TextInputProps, "value" | "onChangeText"> {
  control: Control<T>;
  name: FieldPath<T>;
  label: string;
}
 
export function TextField<T extends FieldValues>({
  control,
  name,
  label,
  ...inputProps
}: TextFieldProps<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}
            {...inputProps}
          />
          {error && <Text style={styles.error}>{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/(auth)/register.tsx - formulário de perfil com cadeia de foco e guarda de envio
import { useForm } from "react-hook-form";
import { Alert, Pressable, StyleSheet, Text, View } from "react-native";
import { KeyboardAwareScrollView } from "react-native-keyboard-controller";
import { useRouter } from "expo-router";
import { TextField } from "../../components/form/TextField";
 
interface RegisterValues {
  fullName: string;
  email: string;
  phone: string;
}
 
export default function RegisterScreen() {
  const router = useRouter();
 
  const {
    control,
    handleSubmit,
    setFocus,
    formState: { isSubmitting, isDirty },
  } = useForm<RegisterValues>({
    defaultValues: { fullName: "", email: "", phone: "" },
    mode: "onTouched",
  });
 
  async function onSubmit(values: RegisterValues) {
    const res = await fetch("https://api.example.com/v1/register", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(values),
    });
    if (!res.ok) {
      Alert.alert("Falha no cadastro", "Verifique seus detalhes e tente novamente.");
      return;
    }
    Alert.alert("Conta criada", "Você pode entrar agora.");
  }
 
  function handleBack() {
    if (isDirty) {
      Alert.alert("Descartar alterações?", "Você tem edições não salvas.", [
        { text: "Permanecer", style: "cancel" },
        { text: "Descartar", style: "destructive", onPress: () => router.back() },
      ]);
      return;
    }
    router.back();
  }
 
  return (
    <KeyboardAwareScrollView
      bottomOffset={24}
      contentContainerStyle={styles.scroll}
      keyboardShouldPersistTaps="handled"
    >
      <Text style={styles.title}>Criar conta</Text>
 
      <TextField
        control={control}
        name="fullName"
        label="Nome completo"
        autoComplete="name"
        returnKeyType="next"
        onSubmitEditing={() => setFocus("email")}
      />
 
      <TextField
        control={control}
        name="email"
        label="Email"
        keyboardType="email-address"
        autoCapitalize="none"
        autoComplete="email"
        returnKeyType="next"
        onSubmitEditing={() => setFocus("phone")}
      />
 
      <TextField
        control={control}
        name="phone"
        label="Telefone"
        keyboardType="phone-pad"
        autoComplete="tel"
        returnKeyType="done"
        onSubmitEditing={handleSubmit(onSubmit)}
      />
 
      <View style={styles.actions}>
        <Pressable onPress={handleBack} style={styles.secondary}>
          <Text style={styles.secondaryText}>Voltar</Text>
        </Pressable>
        <Pressable
          onPress={handleSubmit(onSubmit)}
          disabled={isSubmitting}
          style={styles.primary}
        >
          <Text style={styles.primaryText}>{isSubmitting ? "Salvando…" : "Continuar"}</Text>
        </Pressable>
      </View>
    </KeyboardAwareScrollView>
  );
}
 
const styles = StyleSheet.create({
  scroll: { padding: 16, gap: 16 },
  title: { fontSize: 22, fontWeight: "700", marginBottom: 4 },
  actions: { flexDirection: "row", gap: 12, marginTop: 8 },
  secondary: {
    flex: 1,
    borderWidth: 1,
    borderColor: "#d1d5db",
    borderRadius: 8,
    paddingVertical: 12,
    alignItems: "center",
  },
  secondaryText: { fontWeight: "600", color: "#374151" },
  primary: {
    flex: 1,
    backgroundColor: "#2563eb",
    borderRadius: 8,
    paddingVertical: 12,
    alignItems: "center",
  },
  primaryText: { color: "#fff", fontWeight: "600" },
});

O que isso demonstra:

Controller conecta o react-hook-form a cada TextInput - o padrão necessário no React Native.
Um TextField reutilizável mantém a consistência de estilo de erro e rótulos de acessibilidade entre as telas.
setFocus e returnKeyType="next" encadeiam o teclado de software sem estado extra.
mode: "onTouched" valida após o blur, não a cada caractere - melhor para digitação mobile.
isDirty habilita uma guarda de descarte de alterações antes que o usuário saia da tela.
KeyboardAwareScrollView mantém o campo ativo visível acima do teclado.

Mergulho Profundo

Como Funciona

useForm mantém os valores dos campos em um armazenamento baseado em ref - atualizar um campo não re-renderiza o pai, a menos que você se inscreva nessa fatia do formState.
Controller registra o campo, conecta onChange a onChangeText, e anexa o ref para que setFocus possa chamar TextInput.focus().
A validação é feita através de rules no Controller, um resolver customizado, ou zodResolver (veja Validação com Zod).
handleSubmit executa a validação primeiro; seu onSubmit só é acionado quando o formulário é válido.
formState usa um Proxy - ler errors.email inscreve o componente nos erros de email; ler todo o objeto formState se inscreve em tudo.

Controller vs register no Mobile

Abordagem	React Native	Notas
`register` + spread props	Não funciona	Sem ref de `<input>`; `TextInput` precisa de `onChangeText`
`Controller`	Padrão	Controle total sobre props e estilos do `TextInput`
`useController`	Componentes de campo customizados	Igual ao `Controller`, melhor para wrappers de design-system

Na web você pode usar {...register("email")} em um input nativo. No RN, sempre use Controller ou useController.

Modos de Validação para Mobile

`mode`	Quando a validação ocorre	Adequação para Mobile
`onSubmit`	Ao pressionar o botão	Formulários simples de um campo
`onTouched`	Após o primeiro blur, depois a cada mudança	Padrão recomendado para telas com múltiplos campos
`onBlur`	A cada blur	Bom para áreas de texto longas
`onChange`	A cada pressionamento de tecla	Use com moderação - pode conflitar com o teclado e causar lentidão

Combine com reValidateMode: "onChange" para que campos corrigidos limpem os erros imediatamente após a primeira tentativa de envio.

FormProvider e Fluxos de Múltiplos Passos

import { FormProvider, useForm } from "react-hook-form";
 
const methods = useForm<WizardValues>({ defaultValues: { /* todos os passos */ } });
 
return (
  <FormProvider {...methods}>
    {step === 1 ? <AccountStep /> : <AddressStep />}
  </FormProvider>
);

Declare todos os campos dos passos em defaultValues, mesmo que o passo atual renderize apenas um subconjunto - isDirty e reset permanecem precisos.
Passos filhos chamam useFormContext() em vez de receber control via props.
Persista methods.getValues() no AsyncStorage entre os passos para recuperação do assistente (veja Fluxos de Múltiplos Passos e Assistentes).

Notas TypeScript

import { useForm, type SubmitHandler } from "react-hook-form";
import { z } from "zod";
import { zodResolver } from "@hookform/resolvers/zod";
 
const ProfileSchema = z.object({
  fullName: z.string().min(1),
  email: z.string().email(),
});
 
type ProfileValues = z.infer<typeof ProfileSchema>;
 
const onSubmit: SubmitHandler<ProfileValues> = async (values) => {
  // values é totalmente tipado
};
 
const form = useForm<ProfileValues>({
  resolver: zodResolver(ProfileSchema),
  defaultValues: { fullName: "", email: "" },
});

Instale com npx expo install react-hook-form @hookform/resolvers zod.
Use FieldPath<ProfileValues> nas props name de campos reutilizáveis para que erros de digitação falhem em tempo de compilação.
Valores de TextInput são sempre strings - converta números em Zod com z.coerce.number() em vez de tipar campos como number em defaultValues.

Parâmetros e Valores de Retorno

API	Propósito no RN
`useForm({ defaultValues })`	Obrigatório - cada chave de campo deve aparecer
`control`	Passe para `Controller` / `useFieldArray`
`handleSubmit(onValid, onInvalid?)`	Envolve `Pressable.onPress`; `onInvalid` pode chamar `setFocus` no primeiro erro
`setFocus(name)`	Move o foco do teclado para um campo pelo nome
`reset(values?)`	Limpa após o sucesso ou restaura o rascunho
`watch(name)`	Inscreve-se em um campo - evite observar o formulário inteiro no render
`useFieldArray({ control, name })`	Linhas dinâmicas - liste itens chave com `field.id`, não o índice do array

Armadilhas

Espalhar register em TextInput - register retorna props centradas na web (onChange, name) que não mapeiam para onChangeText. Correção: Use Controller e mapeie onChange → onChangeText.
Chaves defaultValues ausentes - Novos campos mostram undefined, isDirty permanece falso após edições, e reset() os ignora. Correção: Liste todos os campos em defaultValues, incluindo strings vazias e arrays vazios.
Desestruturar todo o formState - const { formState } = useForm() e depois ler formState.isSubmitting no render ainda funciona, mas const { isSubmitting, errors, isDirty, isValid } = formState se inscreve em quatro sinais de uma vez. Correção: Desestruture apenas o que o componente exibe.
watch() no render pai - watch() sem argumentos re-renderiza a cada pressionamento de tecla em todos os campos - o problema que RHF resolve. Correção: watch("email") para um campo, ou mova a UI observada para um filho isolado.
Valor undefined do TextInput - Passar value={undefined} aciona avisos e limpa a posição do cursor. Correção: value={value ?? ""} no render do Controller.
onSubmit sem handleSubmit - Pressionar o botão pula a validação e envia dados parciais. Correção: onPress={handleSubmit(onSubmit)} no Pressable, nunca onPress={onSubmit}.
Erros do servidor não mapeados para campos - A API retorna { fieldErrors: { email: "Já em uso" } } mas a UI mostra um alerta genérico. Correção: Use setError("email", { type: "server", message }) e setFocus("email").

Alternativas

Alternativa	Use Quando	Não Use Quando
react-hook-form + `Controller`	Padrão para 4+ campos, listas dinâmicas, esquemas Zod compartilhados	Uma única caixa de busca com um pedaço de estado local
`useState` simples por campo	1–3 campos, sem validação, telas de protótipo	Checkout, onboarding, ou qualquer formulário com regras entre campos
Formik	Aplicativo brownfield já usando Formik	Aplicativos Expo greenfield - perfil de re-renderização mais pesado
React 19 `useActionState`	Server actions estilo web em rotas de API do Expo Router	Validação complexa apenas no cliente e inputs mascarados no dispositivo
TanStack Form	Você quer primitivas de formulário headless com subscrições de grão fino	Equipe já padronizada em RHF em web e mobile

FAQs

Por que não posso usar register() como na web?

React Native não tem <input> DOM - register depende de ref + eventos de mudança nativos que TextInput não expõe da mesma forma.
TextInput usa onChangeText, não onChange.
Controller é a ponte suportada e lhe dá controle total sobre as props do teclado.

Qual modo de validação devo usar no mobile?

Comece com mode: "onTouched" - erros aparecem após o usuário sair de um campo, não no meio da palavra.
Adicione reValidateMode: "onChange" para que campos corrigidos limpem erros sem outro submit.
Reserve mode: "onChange" para campos curtos como códigos promocionais onde feedback instantâneo ajuda.

Como mudo o foco para o próximo campo quando o usuário toca em Return?

<TextField
  name="email"
  returnKeyType="next"
  onSubmitEditing={() => setFocus("password")}
/>

setFocus é embutido no useForm - nenhum mapeamento manual de ref necessário quando os nomes dos campos são registrados.
Defina returnKeyType="done" no último campo e chame handleSubmit(onSubmit) em onSubmitEditing.

Como foco o primeiro campo inválido após o submit?

handleSubmit(onSubmit, (invalid) => {
  const first = Object.keys(invalid)[0] as keyof RegisterValues;
  setFocus(first);
})();

O segundo argumento de handleSubmit é executado quando a validação falha.
Combine com scrollTo de um ref em KeyboardAwareScrollView para formulários longos.

react-hook-form funciona com TypeScript no Expo?

Sim - passe um genérico para useForm<FormValues>() e para Control<FormValues> em componentes de campo.
Combine com zodResolver e z.infer<typeof Schema> para formulários totalmente tipados.
Instale via npx expo install react-hook-form @hookform/resolvers zod.

Como mostro um estado de carregamento no botão de submit?

Desestruture isSubmitting de formState.
handleSubmit o define como true enquanto sua promise onSubmit assíncrona está pendente.
Desabilite o Pressable e mude o texto do rótulo enquanto isSubmitting for true.

Posso usar react-hook-form dentro de um FlatList?

Sim para o wrapper do formulário - coloque campos dentro de ListHeaderComponent ou ListFooterComponent.
Não coloque TextInput não controlado dentro de renderItem sem Controller - a reciclagem resetará os valores.
Para linhas dinâmicas, prefira useFieldArray a estado de índice manual.

Como resetar o formulário após uma chamada de API bem-sucedida?

async function onSubmit(values: RegisterValues) {
  await createAccount(values);
  reset(); // volta para defaultValues
}

reset() limpa erros, estado sujo e valores.
Passe reset(partialValues) para manter alguns campos após o sucesso (ex: email para um passo de confirmação).

Devo usar FormProvider?

Use-o quando múltiplos componentes filhos precisam de useFormContext() - passos de assistente, grupos de campos em modais, ou seções de formulário de design-system.
Para um formulário de tela única, passar control para TextField é suficiente.

Como react-hook-form se compara ao useState controlado no RN?

useState re-renderiza o componente proprietário a cada onChangeText.
RHF armazena valores em refs e re-renderiza apenas fatias de formState inscritas.
Para 1–2 campos a diferença é insignificante; após ~4 campos RHF vence em hardware de gama média.

Como lidar com toggles de visibilidade de texto seguro e senha?

Mantenha secureTextEntry no TextInput dentro do Controller - não crie um segundo input não controlado.
Alterne a visibilidade com useState local no componente de campo; o valor RHF permanece a mesma string.

Posso combinar react-hook-form com KeyboardAwareScrollView?

Sim - envolva o formulário em KeyboardAwareScrollView de react-native-keyboard-controller.
Defina keyboardShouldPersistTaps="handled" para que os botões de submit funcionem enquanto o teclado está aberto.
Veja Keyboard Controller para bottomOffset e configuração de barra de ferramentas.

Como instalar react-hook-form em um projeto Expo SDK 57?

npx expo install react-hook-form

Adicione @hookform/resolvers e zod quando configurar a validação de esquema.
Nenhum plugin de configuração nativo necessário - JavaScript puro.

Relacionados

Fundamentos de Formulários - TextInput controlado, tipos de teclado e fundamentos de foco
Validação com Zod - zodResolver, erros inline e UX mobile com esquema primeiro
Keyboard Controller - mantenha os inputs focados visíveis acima do teclado de software
Acessibilidade em Formulários - rótulos, anúncios de erro e ordem de foco
Fluxos de Múltiplos Passos e Assistentes - uma instância useForm entre passos
Melhores Práticas de Formulários - redução de toques, persistência de rascunho e submit offline

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 { Controller, useForm } from "react-hook-form";
import { Pressable, StyleSheet, Text, TextInput, View } from "react-native";
 
interface SignInValues {
  email: string;
  password: string;
}
 
export function SignInForm() {
  const {
    control,
    handleSubmit,
    formState: { errors, isSubmitting },
  } = useForm<SignInValues>({
    defaultValues: { email: "", password: "" },
    mode: "onTouched",
  });
 
  async function onSubmit(values: SignInValues) {
    await fetch("https://api.example.com/auth/login", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(values),
    });
  }
 
  return (
    <View style={styles.form}>
      <Controller
        control={control}
        name="email"
        rules={{ required: "O Email é obrigatório" }}
        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"
        rules={{ minLength: { value: 8, message: "Pelo menos 8 caracteres" } }}
        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>}
 
      <Pressable
        onPress={handleSubmit(onSubmit)}
        disabled={isSubmitting}
        style={styles.button}
      >
        <Text style={styles.buttonText}>{isSubmitting ? "Entrando…" : "Entrar"}</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:

Telas com mais de três campos TextInput onde useState por campo causa lentidão visível.
Listas de campos dinâmicas (endereços, itens de linha) via useFieldArray.
Formulários que compartilham validação com seu aplicativo web através de esquemas Zod.
Assistentes de múltiplos passos que precisam de uma única instância de formulário entre as etapas.
Qualquer fluxo onde você precise de guardas isDirty antes de navegar de volta.

Exemplo de Trabalho

// components/form/TextField.tsx - campo RN reutilizável conectado ao RHF
import { Controller, type Control, type FieldPath, type FieldValues } from "react-hook-form";
import { StyleSheet, Text, TextInput, type TextInputProps, View } from "react-native";
 
interface TextFieldProps<T extends FieldValues> extends Omit<TextInputProps, "value" | "onChangeText"> {
  control: Control<T>;
  name: FieldPath<T>;
  label: string;
}
 
export function TextField<T extends FieldValues>({
  control,
  name,
  label,
  ...inputProps
}: TextFieldProps<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}
            {...inputProps}
          />
          {error && <Text style={styles.error}>{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/(auth)/register.tsx - formulário de perfil com cadeia de foco e guarda de envio
import { useForm } from "react-hook-form";
import { Alert, Pressable, StyleSheet, Text, View } from "react-native";
import { KeyboardAwareScrollView } from "react-native-keyboard-controller";
import { useRouter } from "expo-router";
import { TextField } from "../../components/form/TextField";
 
interface RegisterValues {
  fullName: string;
  email: string;
  phone: string;
}
 
export default function RegisterScreen() {
  const router = useRouter();
 
  const {
    control,
    handleSubmit,
    setFocus,
    formState: { isSubmitting, isDirty },
  } = useForm<RegisterValues>({
    defaultValues: { fullName: "", email: "", phone: "" },
    mode: "onTouched",
  });
 
  async function onSubmit(values: RegisterValues) {
    const res = await fetch("https://api.example.com/v1/register", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(values),
    });
    if (!res.ok) {
      Alert.alert("Falha no cadastro", "Verifique seus detalhes e tente novamente.");
      return;
    }
    Alert.alert("Conta criada", "Você pode entrar agora.");
  }
 
  function handleBack() {
    if (isDirty) {
      Alert.alert("Descartar alterações?", "Você tem edições não salvas.", [
        { text: "Permanecer", style: "cancel" },
        { text: "Descartar", style: "destructive", onPress: () => router.back() },
      ]);
      return;
    }
    router.back();
  }
 
  return (
    <KeyboardAwareScrollView
      bottomOffset={24}
      contentContainerStyle={styles.scroll}
      keyboardShouldPersistTaps="handled"
    >
      <Text style={styles.title}>Criar conta</Text>
 
      <TextField
        control={control}
        name="fullName"
        label="Nome completo"
        autoComplete="name"
        returnKeyType="next"
        onSubmitEditing={() => setFocus("email")}
      />
 
      <TextField
        control={control}
        name="email"
        label="Email"
        keyboardType="email-address"
        autoCapitalize="none"
        autoComplete="email"
        returnKeyType="next"
        onSubmitEditing={() => setFocus("phone")}
      />
 
      <TextField
        control={control}
        name="phone"
        label="Telefone"
        keyboardType="phone-pad"
        autoComplete="tel"
        returnKeyType="done"
        onSubmitEditing={handleSubmit(onSubmit)}
      />
 
      <View style={styles.actions}>
        <Pressable onPress={handleBack} style={styles.secondary}>
          <Text style={styles.secondaryText}>Voltar</Text>
        </Pressable>
        <Pressable
          onPress={handleSubmit(onSubmit)}
          disabled={isSubmitting}
          style={styles.primary}
        >
          <Text style={styles.primaryText}>{isSubmitting ? "Salvando…" : "Continuar"}</Text>
        </Pressable>
      </View>
    </KeyboardAwareScrollView>
  );
}
 
const styles = StyleSheet.create({
  scroll: { padding: 16, gap: 16 },
  title: { fontSize: 22, fontWeight: "700", marginBottom: 4 },
  actions: { flexDirection: "row", gap: 12, marginTop: 8 },
  secondary: {
    flex: 1,
    borderWidth: 1,
    borderColor: "#d1d5db",
    borderRadius: 8,
    paddingVertical: 12,
    alignItems: "center",
  },
  secondaryText: { fontWeight: "600", color: "#374151" },
  primary: {
    flex: 1,
    backgroundColor: "#2563eb",
    borderRadius: 8,
    paddingVertical: 12,
    alignItems: "center",
  },
  primaryText: { color: "#fff", fontWeight: "600" },
});

O que isso demonstra:

Controller conecta o react-hook-form a cada TextInput - o padrão necessário no React Native.
Um TextField reutilizável mantém a consistência de estilo de erro e rótulos de acessibilidade entre as telas.
setFocus e returnKeyType="next" encadeiam o teclado de software sem estado extra.
mode: "onTouched" valida após o blur, não a cada caractere - melhor para digitação mobile.
isDirty habilita uma guarda de descarte de alterações antes que o usuário saia da tela.
KeyboardAwareScrollView mantém o campo ativo visível acima do teclado.

Mergulho Profundo

Como Funciona

useForm mantém os valores dos campos em um armazenamento baseado em ref - atualizar um campo não re-renderiza o pai, a menos que você se inscreva nessa fatia do formState.
Controller registra o campo, conecta onChange a onChangeText, e anexa o ref para que setFocus possa chamar TextInput.focus().
A validação é feita através de rules no Controller, um resolver customizado, ou zodResolver (veja Validação com Zod).
handleSubmit executa a validação primeiro; seu onSubmit só é acionado quando o formulário é válido.
formState usa um Proxy - ler errors.email inscreve o componente nos erros de email; ler todo o objeto formState se inscreve em tudo.

Controller vs register no Mobile

Abordagem	React Native	Notas
`register` + spread props	Não funciona	Sem ref de `<input>`; `TextInput` precisa de `onChangeText`
`Controller`	Padrão	Controle total sobre props e estilos do `TextInput`
`useController`	Componentes de campo customizados	Igual ao `Controller`, melhor para wrappers de design-system

Na web você pode usar {...register("email")} em um input nativo. No RN, sempre use Controller ou useController.

Modos de Validação para Mobile

`mode`	Quando a validação ocorre	Adequação para Mobile
`onSubmit`	Ao pressionar o botão	Formulários simples de um campo
`onTouched`	Após o primeiro blur, depois a cada mudança	Padrão recomendado para telas com múltiplos campos
`onBlur`	A cada blur	Bom para áreas de texto longas
`onChange`	A cada pressionamento de tecla	Use com moderação - pode conflitar com o teclado e causar lentidão

Combine com reValidateMode: "onChange" para que campos corrigidos limpem os erros imediatamente após a primeira tentativa de envio.

FormProvider e Fluxos de Múltiplos Passos

import { FormProvider, useForm } from "react-hook-form";
 
const methods = useForm<WizardValues>({ defaultValues: { /* todos os passos */ } });
 
return (
  <FormProvider {...methods}>
    {step === 1 ? <AccountStep /> : <AddressStep />}
  </FormProvider>
);

Declare todos os campos dos passos em defaultValues, mesmo que o passo atual renderize apenas um subconjunto - isDirty e reset permanecem precisos.
Passos filhos chamam useFormContext() em vez de receber control via props.
Persista methods.getValues() no AsyncStorage entre os passos para recuperação do assistente (veja Fluxos de Múltiplos Passos e Assistentes).

Notas TypeScript

import { useForm, type SubmitHandler } from "react-hook-form";
import { z } from "zod";
import { zodResolver } from "@hookform/resolvers/zod";
 
const ProfileSchema = z.object({
  fullName: z.string().min(1),
  email: z.string().email(),
});
 
type ProfileValues = z.infer<typeof ProfileSchema>;
 
const onSubmit: SubmitHandler<ProfileValues> = async (values) => {
  // values é totalmente tipado
};
 
const form = useForm<ProfileValues>({
  resolver: zodResolver(ProfileSchema),
  defaultValues: { fullName: "", email: "" },
});

Instale com npx expo install react-hook-form @hookform/resolvers zod.
Use FieldPath<ProfileValues> nas props name de campos reutilizáveis para que erros de digitação falhem em tempo de compilação.
Valores de TextInput são sempre strings - converta números em Zod com z.coerce.number() em vez de tipar campos como number em defaultValues.

Parâmetros e Valores de Retorno

API	Propósito no RN
`useForm({ defaultValues })`	Obrigatório - cada chave de campo deve aparecer
`control`	Passe para `Controller` / `useFieldArray`
`handleSubmit(onValid, onInvalid?)`	Envolve `Pressable.onPress`; `onInvalid` pode chamar `setFocus` no primeiro erro
`setFocus(name)`	Move o foco do teclado para um campo pelo nome
`reset(values?)`	Limpa após o sucesso ou restaura o rascunho
`watch(name)`	Inscreve-se em um campo - evite observar o formulário inteiro no render
`useFieldArray({ control, name })`	Linhas dinâmicas - liste itens chave com `field.id`, não o índice do array

Armadilhas

Espalhar register em TextInput - register retorna props centradas na web (onChange, name) que não mapeiam para onChangeText. Correção: Use Controller e mapeie onChange → onChangeText.
Chaves defaultValues ausentes - Novos campos mostram undefined, isDirty permanece falso após edições, e reset() os ignora. Correção: Liste todos os campos em defaultValues, incluindo strings vazias e arrays vazios.
Desestruturar todo o formState - const { formState } = useForm() e depois ler formState.isSubmitting no render ainda funciona, mas const { isSubmitting, errors, isDirty, isValid } = formState se inscreve em quatro sinais de uma vez. Correção: Desestruture apenas o que o componente exibe.
watch() no render pai - watch() sem argumentos re-renderiza a cada pressionamento de tecla em todos os campos - o problema que RHF resolve. Correção: watch("email") para um campo, ou mova a UI observada para um filho isolado.
Valor undefined do TextInput - Passar value={undefined} aciona avisos e limpa a posição do cursor. Correção: value={value ?? ""} no render do Controller.
onSubmit sem handleSubmit - Pressionar o botão pula a validação e envia dados parciais. Correção: onPress={handleSubmit(onSubmit)} no Pressable, nunca onPress={onSubmit}.
Erros do servidor não mapeados para campos - A API retorna { fieldErrors: { email: "Já em uso" } } mas a UI mostra um alerta genérico. Correção: Use setError("email", { type: "server", message }) e setFocus("email").

Alternativas

Alternativa	Use Quando	Não Use Quando
react-hook-form + `Controller`	Padrão para 4+ campos, listas dinâmicas, esquemas Zod compartilhados	Uma única caixa de busca com um pedaço de estado local
`useState` simples por campo	1–3 campos, sem validação, telas de protótipo	Checkout, onboarding, ou qualquer formulário com regras entre campos
Formik	Aplicativo brownfield já usando Formik	Aplicativos Expo greenfield - perfil de re-renderização mais pesado
React 19 `useActionState`	Server actions estilo web em rotas de API do Expo Router	Validação complexa apenas no cliente e inputs mascarados no dispositivo
TanStack Form	Você quer primitivas de formulário headless com subscrições de grão fino	Equipe já padronizada em RHF em web e mobile

FAQs

Por que não posso usar register() como na web?

React Native não tem <input> DOM - register depende de ref + eventos de mudança nativos que TextInput não expõe da mesma forma.
TextInput usa onChangeText, não onChange.
Controller é a ponte suportada e lhe dá controle total sobre as props do teclado.

Qual modo de validação devo usar no mobile?

Comece com mode: "onTouched" - erros aparecem após o usuário sair de um campo, não no meio da palavra.
Adicione reValidateMode: "onChange" para que campos corrigidos limpem erros sem outro submit.
Reserve mode: "onChange" para campos curtos como códigos promocionais onde feedback instantâneo ajuda.

Como mudo o foco para o próximo campo quando o usuário toca em Return?

<TextField
  name="email"
  returnKeyType="next"
  onSubmitEditing={() => setFocus("password")}
/>

setFocus é embutido no useForm - nenhum mapeamento manual de ref necessário quando os nomes dos campos são registrados.
Defina returnKeyType="done" no último campo e chame handleSubmit(onSubmit) em onSubmitEditing.

Como foco o primeiro campo inválido após o submit?

handleSubmit(onSubmit, (invalid) => {
  const first = Object.keys(invalid)[0] as keyof RegisterValues;
  setFocus(first);
})();

O segundo argumento de handleSubmit é executado quando a validação falha.
Combine com scrollTo de um ref em KeyboardAwareScrollView para formulários longos.

react-hook-form funciona com TypeScript no Expo?

Sim - passe um genérico para useForm<FormValues>() e para Control<FormValues> em componentes de campo.
Combine com zodResolver e z.infer<typeof Schema> para formulários totalmente tipados.
Instale via npx expo install react-hook-form @hookform/resolvers zod.

Como mostro um estado de carregamento no botão de submit?

Desestruture isSubmitting de formState.
handleSubmit o define como true enquanto sua promise onSubmit assíncrona está pendente.
Desabilite o Pressable e mude o texto do rótulo enquanto isSubmitting for true.

Posso usar react-hook-form dentro de um FlatList?

Sim para o wrapper do formulário - coloque campos dentro de ListHeaderComponent ou ListFooterComponent.
Não coloque TextInput não controlado dentro de renderItem sem Controller - a reciclagem resetará os valores.
Para linhas dinâmicas, prefira useFieldArray a estado de índice manual.

Como resetar o formulário após uma chamada de API bem-sucedida?

async function onSubmit(values: RegisterValues) {
  await createAccount(values);
  reset(); // volta para defaultValues
}

reset() limpa erros, estado sujo e valores.
Passe reset(partialValues) para manter alguns campos após o sucesso (ex: email para um passo de confirmação).

Devo usar FormProvider?

Use-o quando múltiplos componentes filhos precisam de useFormContext() - passos de assistente, grupos de campos em modais, ou seções de formulário de design-system.
Para um formulário de tela única, passar control para TextField é suficiente.

Como react-hook-form se compara ao useState controlado no RN?

useState re-renderiza o componente proprietário a cada onChangeText.
RHF armazena valores em refs e re-renderiza apenas fatias de formState inscritas.
Para 1–2 campos a diferença é insignificante; após ~4 campos RHF vence em hardware de gama média.

Como lidar com toggles de visibilidade de texto seguro e senha?

Mantenha secureTextEntry no TextInput dentro do Controller - não crie um segundo input não controlado.
Alterne a visibilidade com useState local no componente de campo; o valor RHF permanece a mesma string.

Posso combinar react-hook-form com KeyboardAwareScrollView?

Sim - envolva o formulário em KeyboardAwareScrollView de react-native-keyboard-controller.
Defina keyboardShouldPersistTaps="handled" para que os botões de submit funcionem enquanto o teclado está aberto.
Veja Keyboard Controller para bottomOffset e configuração de barra de ferramentas.

Como instalar react-hook-form em um projeto Expo SDK 57?

npx expo install react-hook-form

Adicione @hookform/resolvers e zod quando configurar a validação de esquema.
Nenhum plugin de configuração nativo necessário - JavaScript puro.

Relacionados

Fundamentos de Formulários - TextInput controlado, tipos de teclado e fundamentos de foco
Validação com Zod - zodResolver, erros inline e UX mobile com esquema primeiro
Keyboard Controller - mantenha os inputs focados visíveis acima do teclado de software
Acessibilidade em Formulários - rótulos, anúncios de erro e ordem de foco
Fluxos de Múltiplos Passos e Assistentes - uma instância useForm entre passos
Melhores Práticas de Formulários - redução de toques, persistência de rascunho e submit offline

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

react-hook-form no Mobile

Buscar na documentação

react-hook-form no Mobile