form-handling skill

---
name: Form Handling with React Hook Form and Zod
description: Building type-safe, validated forms in React using React Hook Form for state management and Zod for schema validation.
---

# Form Handling with React Hook Form and Zod

## Overview

Form handling is a critical aspect of web applications that collect data from users. React Hook Form and Zod provide a powerful combination for building forms in React: React Hook Form reduces re-renders and improves performance, while Zod provides validation that is runtime-safe and type-safe.

This skill covers using React Hook Form and Zod to create forms with high validation quality, error handling, async validation, dynamic fields, and integration with UI libraries.

## Why This Matters

- **Increases Conversion Rate**: Easy-to-use forms with clear validation increase conversion rates by 20-30%
- **Reduces Form Abandonment**: Real-time validation and clear error messages reduce form abandonment
- **Improves Data Quality**: Good validation prevents incorrect data entry and reduces data cleaning time
- **Reduces Support Cost**: Clear, working error messages reduce confusion and support tickets
- **Improves User Satisfaction**: Forms that work well and respond quickly create good user experience

---

## Core Concepts

### 1. React Hook Form

Efficient form state management:

- **Reduces Re-renders**: Optimized to minimize unnecessary re-renders
- **Performance**: Fast even with large forms
- **Minimal Code**: Less boilerplate than controlled inputs
- **Integration**: Works with all UI libraries (Material UI, MUI, Chakra UI)

### 2. Zod Validation

Type-safe schema validation:

- **Runtime Validation**: Validates data at runtime
- **TypeScript Inference**: Auto-generates TypeScript types from schemas
- **Composable**: Build complex validation from simple schemas
- **Error Messages**: Customizable, localized error messages

### 3. Form Validation Types

Different validation approaches:

- **Client-Side**: Immediate feedback, better UX
- **Server-Side**: Final validation, security critical
- **Async Validation**: API calls for uniqueness checks
- **Field-Level**: Validate individual fields
- **Form-Level**: Validate multiple fields together

### 4. Error Handling

Managing form errors effectively:

- **Display Errors**: Show errors next to fields or at form level
- **Error Messages**: Clear, actionable error text
- **Validation States**: Show validation in progress for async checks
- **Form-Level Errors**: Display form-wide errors at top

## Quick Start

1. **Install Dependencies**: Install React Hook Form and Zod (`npm install react-hook-form zod @hookform/resolvers`)
2. **Define Zod Schema**: Create validation schema with types
3. **Set Up Form**: Initialize React Hook Form with Zod resolver
4. **Create Form Fields**: Build form with controlled inputs
5. **Add Error Display**: Show validation errors appropriately
6. **Handle Submission**: Process form submission with error handling
7. **Test Validation**: Verify all validation rules work correctly
8. **Integrate UI**: Style form to match design system

```typescript
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

const schema = z.object({
  name: z.string().min(2, 'Name must be at least 2 characters'),
  email: z.string().email('Invalid email address'),
  age: z.number().min(18, 'Must be 18 or older'),
});

type FormData = z.infer<typeof schema>;

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="Name" />
      {errors.name && <p>{errors.name.message}</p>}
      
      <input {...register('email')} placeholder="Email" />
      {errors.email && <p>{errors.email.message}</p>}
      
      <button type="submit">Submit</button>
    </form>
  );
}
```

## Production Checklist

- [ ] Zod schema defined with all validation rules
- [ ] TypeScript types inferred from schemas
- [ ] React Hook Form configured with resolver
- [ ] Error messages clear and localized
- [ ] Form fields properly registered
- [ ] Submission handling with error states
- [ ] Async validation implemented where needed
- [ ] Dynamic fields handling working
- [ ] Form accessible (labels, ARIA, keyboard navigation)
- [ ] Loading states during submission
- [ ] Success/error feedback displayed
- [ ] Form performance optimized
- [ ] Cross-browser tested
- [ ] Mobile responsive

## Anti-patterns

1. **No Validation**: Skipping validation leads to bad data and user frustration
2. **Poor Error Messages**: Vague errors don't help users fix issues
3. **Blocking Submission**: Submitting forms without validation causes server errors
4. **Ignoring Accessibility**: Inaccessible forms exclude users with disabilities
5. **Over-Validation**: Too strict validation frustrates users unnecessarily
6. **No Loading State**: Users don't know form is processing
7. **Silent Failures**: Forms fail without any user feedback

## Integration Points

- **React Hook Form**: [https://react-hook-form.com/](https://react-hook-form.com/)
- **Zod**: [https://zod.dev/](https://zod.dev/)
- **UI Libraries**: Material UI, Chakra UI, Mantine for form components
- **Validation**: Async validation patterns for API checks

## Further Reading

- [React Hook Form Documentation](https://react-hook-form.com/)
- [Zod Documentation](https://zod.dev/)
- [Form Validation Best Practices](https://www.smashingmagazine.com/2020/08/the-ultimate-guide-to-form-validation-in-react/)
- [Accessible Forms](https://web.dev/accessible-forms/)