React Hook Form - Common Pitfalls & Gotchas

This is a collection of pitfalls I've come across when using React Hook Form, usually in conjunction with the Zod Resolver and shadcn Form components. It's written for my own benefit as a checklist when something isn't working.

Have you set default values?

Forgetting to set a proper default value is probably the most common issue with React Hook Form. This is especially important if you're using controlled components like shadcn, or an external validation library like Zod with the Zod Resolver.

Forgetting default values will lead to lots of strange bugs with form submission, form resetting, checking form state, checking which fields are dirty/modified etc.

const form = useForm({
  resolver: zodResolver(formSchema),
  defaultValues: {
    firstName: "", // empty string as a default value
    age: "", // can be coerced to a number with Zod
  },
});

Rules for React Hook Form's defaultValue:

• If your form will invoke reset with default values, you will need to provide useForm with defaultValues
• undefined is not a valid value - it conflicts with the default state of a controlled component
• defaultValues are cached - Reset them with the reset API
• avoid using custom objects containing prototype methods, such as Moment or Luxon, as defaultValues
• You can always coerce the value to something else later on with Zod if you need to - https://github.com/colinhacks/zod/discussions/330

Source: https://react-hook-form.com/docs/useform#defaultValues

Have you imported <Form> from the wrong package?

This is a common pitfall when using React Hook Form with shadcn form components, and your IDE has auto-imports or some kind of AI code completion enabled.

What you meant to do is:

import { useForm } from "react-hook-form" // RHF useForm hook
import { Form } "@/components/ui/form"    // shadcn <Form /> component

Unfortunately your IDE tries to be helpful and imports both from RHF like this

import { useForm, Form } from "react-hook-form"; // Thanks AI!

There's no red-squiggly errors and TypeScript isn't complaining so it's not immediately obvious what's wrong until you try to create your Form component. This is because RHF comes with it's own <Form> component to handle form submission.

So if you're using React Hook Form with shadcn always check your imports and don't trust your auto-completion.

Building forms with React Hook Form and Zod

Issues with the <Select> input

This is another React Hook Form with shadcn pitfall.

Normally when building a form with RHF and shadcn you can quickly destructure the form field data directly into the shadcn input component like this:

<FormField
  control={form.control}
  name="exampleField"
  render={({ field }) => (
    <FormItem>
      <FormLabel>An Example Field</FormLabel>
      <FormControl>
        <Input placeholder="Example" {...field} /> // Destructured field data
      </FormControl>
    </FormItem>
  )}
/>

At the time of writing this doesn't work with the <Select> component. Instead you need to manually wire it up like this:

<FormField
  control={form.control}
  name="exampleField"
  render={({ field }) => (
    <FormItem>
      <FormLabel>An Example Field</FormLabel>
      // Add field data manually
      <Select onValueChange={field.onChange} defaultValue={field.value}>
        <FormControl>
          <SelectTrigger>
            <SelectValue placeholder="Example" />
          </SelectTrigger>
        </FormControl>
        <SelectContent>
          <SelectItem value="1">Item 1</SelectItem>
          <SelectItem value="2">Item 2</SelectItem>
          <SelectItem value="3">Item 3</SelectItem>
        </SelectContent>
      </Select>
    </FormItem>
  )}
/>

RHF & Next.js server action mutations

Don't use form.reset() to show updated data after a server action mutation...

I wrote this down on a scrap of paper so it must be important, unfortunately I can't remember why.

Something to do with stale data overwriting the new data?

I'll update this when I find out!