React hook form best practices

---
description: Forms rules and instructions
globs:
alwaysApply: false
---

# React Hook Form Best Practices
Standards for using React Hook Form. Auto-included for TSX and JSX files.
<rule>
name: react_hook_form_best_practices
description: Best practices for using React Hook Form. Auto-included for TSX and JSX files.
globs: ["**/*.{tsx,jsx}"]
filters:
- type: file_extension
pattern: "\.(tsx|jsx)$"
actions:
- type: suggest
message: |
Follow these React Hook Form best practices:
    1. Form Setup:
        - Use proper form initialization
        - Implement proper validation schema
        - Use proper default values
        - Handle form submission properly
    2. Field Registration:
        - Use register method properly
        - Implement proper field validation
        - Handle field errors properly
        - Use proper field naming
    3. Validation Integration:
        - Use Zod or Yup integration
        - Implement custom validation
        - Handle async validation
        - Use proper error messages
    4. Performance Optimization:
        - Use uncontrolled components
        - Implement proper form watching
        - Handle form state properly
        - Use proper re-render optimization
    5. Form State Management:
        - Handle form submission state
        - Implement proper error handling
        - Use proper form reset
        - Handle form dirty state
examples:
- input: |
// Bad: Not using form validation
const MyForm = () => {
const [values, setValues] = useState({});
return (
<form onSubmit={(e) => {
e.preventDefault();
// handle submit
}}>
<input onChange={(e) => setValues({...values, name: e.target.value})} />
</form>
);
};
- // Good: Using React Hook Form with Zod
const formSchema = z.object({
name: z.string().min(2),
email: z.string().email()
});
- const MyForm = () => {
const form = useForm<z.infer<typeof formSchema>>({
resolver: zodResolver(formSchema)
});
- `return (
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <input {...form.register("name")} />
    {form.formState.errors.name && (
      <span>{form.formState.errors.name.message}</span>
    )}
  </form>
);
`
- };
output: "Use React Hook Form with proper validation schema"
- input: |
// Bad: Using controlled components
const MyInput = () => {
const [value, setValue] = useState("");
return (
<input
value={value}
onChange={(e) => setValue(e.target.value)}
/>
);
};
- // Good: Using uncontrolled components with React Hook Form
const MyInput = () => {
const { register, formState: { errors } } = useFormContext();
return (
<>
<input {...register("fieldName")} />
{errors.fieldName && (
<span>{errors.fieldName.message}</span>
)}
</>
);
};
output: "Use uncontrolled components for better performance"
metadata:
priority: high
version: 1.0
</rule>
# Forms rules and instructions
Best practices for handling forms with React Hook Form in Next.js applications, especially with tRPC.
<rule>
name: react_hook_form_best_practices
description: Best practices for using React Hook Form with tRPC and Next.js. Auto-included for TSX files.
globs: ["**/*.tsx"]
filters:
- type: file_extension
pattern: "\.tsx$"
- type: content
pattern: "(?:useForm|Controller|register|handleSubmit|FormProvider)"
actions:
- type: suggest
message: |
Follow these React Hook Form best practices:
    1. Form Setup:
        - Use the `useForm` hook with explicit TypeScript typing
        - Define Zod schemas for validation
        - Use zodResolver for form validation
        - Initialize defaultValues directly from suspense queries when possible
        - Set sensible fallback values with the nullish coalescing operator (??)
    2. Form-Server Data Flow:
        - For client components with suspense queries:

            - Initialize form directly from query data
            - No need for a useEffect to reset form when data changes
            - Keep initial values in React.useMemo for reset functionality
    3. `// Good pattern for client components with suspense queries
const { data: settings } = useSuspenseQuery(
  trpc.settings.getSettings.queryOptions()
);

// Store initial values for reset
const initialValues = React.useMemo(() => ({
  setting1: settings?.setting1 ?? defaultValue,
  setting2: settings?.setting2 ?? defaultValue,
}), [settings]);

const { register, handleSubmit, reset } = useForm({
  resolver: zodResolver(formSchema),
  defaultValues: {
    setting1: settings?.setting1 ?? defaultValue,
    setting2: settings?.setting2 ?? defaultValue,
  }
});
`
    4. Form Controls:
        - Use register for simple inputs:
        - `<input {...register("fieldName")} />
`
        - Use Controller for complex components:
        - `<Controller
  name="fieldName"
  control={control}
  render={({ field }) => <Select {...field} />}
/>
`
        - For controlled components like switches, combine register with watch:
        - `<Switch.Root
  id={`field-id`}
  checked={watch("fieldName")}
  onCheckedChange={(checked) => setValue("fieldName", checked, { shouldDirty: true })}
  {...register("fieldName")}
/>
`
    5. Form Submission:
        - Use handleSubmit to process form data
        - Clear error state before submission
        - Use try/catch for error handling
        - Reset form with new data after successful submission
        - Invalidate queries with full queryOptions():
    6. `const onSubmit = async (data: FormValues) => {
  setError(null);
  try {
    await updateData(data);
    reset(data); // Reset with new values
    queryClient.invalidateQueries(trpc.data.getData.queryOptions());
  } catch (error) {
    setError(getErrorMessage(error));
  }
};
`
    7. Form Reset and Discard:
        - Implement a discard function using stored initial values:
        - `const handleDiscard = () => {
  reset(initialValues);
  setError(null);
};
`
        - Disable discard button when form is not dirty:
        - `<Button
  disabled={!isDirty || isSubmitting}
  onClick={handleDiscard}
>
  Discard
</Button>
`
    8. Form State Management:
        - Use formState for tracking form status:

            - isDirty - Has the form changed?
            - isSubmitting - Is the form currently submitting?
            - errors - Validation errors
        - Use these states for UI feedback:
        - `<SaveButton
  isDirty={isDirty}
  isPending={isSubmitting}
  type="submit"
/>
`
    9. Error Handling:
        - Display form-level errors with a global message component
        - Show field-level errors below each input
        - Provide clear error messages from both client and server validation
examples:
- input: |
// Bad: Unnecessary useEffect for form reset with suspense query
const { data: settings } = useSuspenseQuery(trpc.settings.getSettings.queryOptions());
- const { register, reset } = useForm({
defaultValues: initialValues // Defined elsewhere
});
- React.useEffect(() => {
if (settings) {
reset({
setting1: settings.setting1,
setting2: settings.setting2,
});
}
}, [settings, reset]);
- // Good: Direct initialization with suspense query data
const { data: settings } = useSuspenseQuery(trpc.settings.getSettings.queryOptions());
- const initialValues = React.useMemo(() => ({
setting1: settings?.setting1 ?? defaultValue,
setting2: settings?.setting2 ?? defaultValue,
}), [settings]);
- const { register, handleSubmit, reset } = useForm({
defaultValues: {
setting1: settings?.setting1 ?? defaultValue,
setting2: settings?.setting2 ?? defaultValue,
}
});
output: "Initialize forms directly from suspense query data without unnecessary useEffect"
- input: |
// Bad: Using just queryKey for invalidation after form submission
const onSubmit = async (data: FormValues) => {
try {
await updateSettings(data);
queryClient.invalidateQueries({
queryKey: trpc.settings.getSettings.queryKey
});
} catch (error) {
// Error handling
}
};
- // Good: Using full queryOptions() for invalidation
const onSubmit = async (data: FormValues) => {
try {
await updateSettings(data);
reset(data); // Reset with new values
queryClient.invalidateQueries(trpc.settings.getSettings.queryOptions());
} catch (error) {
// Error handling
}
};
output: "Reset form with new data and use full queryOptions() for invalidation after submission"
- input: |
// Bad: No proper handling for discard
const handleDiscard = () => {
reset();
};
- // Good: Proper discard implementation
const initialValues = React.useMemo(() => ({
setting1: settings?.setting1 ?? defaultValue,
setting2: settings?.setting2 ?? defaultValue,
}), [settings]);
- const handleDiscard = () => {
reset(initialValues);
setError(null);
};
- <Button
disabled={!isDirty || isSubmitting}
onClick={handleDiscard}
- `Discard
`
- </Button>
output: "Implement proper discard functionality with stored initial values"
metadata:
priority: high
version: 1.0
</rule>