React

Boas Práticas com Formulários em React usando React Hook Form + Zod

Boas Práticas com Formulários em React usando React Hook Form + Zod

Por que usar React Hook Form com Zod?

Ao trabalhar com formulários em React, buscamos soluções que ofereçam performance, validação confiável e boa experiência de desenvolvimento. O react-hook-form se destaca por ser leve e rápido, enquanto o zod traz uma abordagem moderna e tipada para validação de dados.

Juntos, eles formam uma dupla poderosa para criar formulários robustos e seguros em aplicações React.

Configuração Inicial

Antes de tudo, instale os pacotes necessários:

npm install react-hook-form zod @hookform/resolvers

Agora, vamos montar um exemplo básico:

import { useForm } from 'react-hook-form'
import { z } from 'zod'
import { zodResolver } from '@hookform/resolvers/zod'
 
const schema = z.object({
  name: z.string().min(1, 'Nome é obrigatório'),
  email: z.string().email('E-mail inválido'),
  age: z.number().min(18, 'Você deve ter pelo menos 18 anos'),
})
 
type FormData = z.infer<typeof schema>
 
export default function MyForm() {
  const { register, handleSubmit, formState: { errors } } = useForm<FormData>({
    resolver: zodResolver(schema),
  })
 
  const onSubmit = (data: FormData) => {
    console.log(data)
  }
 
  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register('name')} placeholder="Nome" />
      {errors.name && <span>{errors.name.message}</span>}
 
      <input {...register('email')} placeholder="E-mail" />
      {errors.email && <span>{errors.email.message}</span>}
 
      <input type="number" {...register('age', { valueAsNumber: true })} placeholder="Idade" />
      {errors.age && <span>{errors.age.message}</span>}
 
      <button type="submit">Enviar</button>
    </form>
  )
}

Boas Práticas

1. Centralize os Schemas

Mantenha seus schemas Zod organizados em arquivos separados, como schemas/user.ts, facilitando reuso e testes.

2. Tipagem com z.infer<>

Evite criar tipos manualmente — use z.infer<typeof schema> para garantir sincronização entre validação e tipos do formulário.

3. Validação no lado do cliente + servidor

Mesmo usando Zod no front, mantenha validações no backend. Nunca confie apenas no cliente.

4. Feedback de erro claro

Exiba mensagens específicas para cada campo. Isso melhora a usabilidade e reduz frustração do usuário.

5. Normalize valores de input

Use opções como valueAsNumber ou setValueAs ao registrar campos para transformar strings em números, datas etc.

Armadilhas Comuns

❌ Campos com tipo errado

Evite confiar que input type="number" retorna um número. Use valueAsNumber para garantir.

<input {...register('age', { valueAsNumber: true })} />

❌ Esquecer o resolver

Sem o zodResolver, seu schema não é aplicado. Sempre adicione ao useForm.

❌ Usar defaultValue fora do contexto

Prefira defaultValues no useForm, principalmente quando precisar reidratar dados em edição.

Conclusão

O combo React Hook Form + Zod oferece tipo seguro, validação declarativa e ótima performance. Ao seguir boas práticas, você cria formulários limpos, reutilizáveis e fáceis de manter.

🚀 Próximos Passos

  • Teste este exemplo no seu projeto.

  • Experimente extrair validações para um schema global.

  • Compartilhe este post com devs que estão aprendendo formulários no React!