React Forms

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: react topic: forms for comprehensive documentation on React form patterns and validation strategies.

Full Reference: See advanced.md for Server Actions, Multi-Step Forms, Dependent Fields, Auto-Save, Validation Patterns, and Accessibility.

Controlled vs Uncontrolled

Controlled Forms

React state controls the input:

function ControlledForm() { const [formData, setFormData] = useState({ email: '', password: '', }); const [errors, setErrors] = useState<Record<string, string>>({});

const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => { const { name, value } = e.target; setFormData(prev => ({ ...prev, [name]: value }));

if (errors[name]) {
  setErrors(prev => ({ ...prev, [name]: '' }));
}

};

const handleSubmit = (e: React.FormEvent) => { e.preventDefault();

const newErrors: Record<string, string> = {};
if (!formData.email) newErrors.email = 'Email required';
if (!formData.password) newErrors.password = 'Password required';

if (Object.keys(newErrors).length > 0) {
  setErrors(newErrors);
  return;
}

console.log('Submitting:', formData);

};

return ( <form onSubmit={handleSubmit}> <div> <input name="email" type="email" value={formData.email} onChange={handleChange} /> {errors.email && <span className="error">{errors.email}</span>} </div>

  <div>
    <input
      name="password"
      type="password"
      value={formData.password}
      onChange={handleChange}
    />
    {errors.password && <span className="error">{errors.password}</span>}
  </div>

  <button type="submit">Submit</button>
</form>

); }

Uncontrolled Forms (useRef)

DOM controls the input:

function UncontrolledForm() { const emailRef = useRef<HTMLInputElement>(null); const passwordRef = useRef<HTMLInputElement>(null);

const handleSubmit = (e: React.FormEvent) => { e.preventDefault();

const data = {
  email: emailRef.current?.value,
  password: passwordRef.current?.value,
};

console.log('Submitting:', data);

};

return ( <form onSubmit={handleSubmit}> <input ref={emailRef} name="email" type="email" /> <input ref={passwordRef} name="password" type="password" /> <button type="submit">Submit</button> </form> ); }

FormData API (Uncontrolled)

function FormDataForm() { const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => { e.preventDefault(); const formData = new FormData(e.currentTarget);

const data = {
  email: formData.get('email') as string,
  password: formData.get('password') as string,
};

console.log('Submitting:', data);

};

return ( <form onSubmit={handleSubmit}> <input name="email" type="email" required /> <input name="password" type="password" required /> <button type="submit">Submit</button> </form> ); }

React Hook Form

Most popular form library - uncontrolled with great DX:

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

const schema = z.object({ email: z.string().email('Invalid email'), password: z.string().min(8, 'Password must be at least 8 characters'), confirmPassword: z.string(), }).refine(data => data.password === data.confirmPassword, { message: 'Passwords must match', path: ['confirmPassword'], });

type FormData = z.infer<typeof schema>;

function SignUpForm() { const { register, handleSubmit, formState: { errors, isSubmitting }, reset, } = useForm<FormData>({ resolver: zodResolver(schema), defaultValues: { email: '', password: '', confirmPassword: '' }, });

const onSubmit = async (data: FormData) => { try { await signUp(data); reset(); } catch (error) { console.error('Sign up failed:', error); } };

return ( <form onSubmit={handleSubmit(onSubmit)}> <div> <input {...register('email')} type="email" placeholder="Email" /> {errors.email && <span className="error">{errors.email.message}</span>} </div>

  <div>
    <input {...register('password')} type="password" placeholder="Password" />
    {errors.password && <span className="error">{errors.password.message}</span>}
  </div>

  <div>
    <input {...register('confirmPassword')} type="password" placeholder="Confirm Password" />
    {errors.confirmPassword && <span className="error">{errors.confirmPassword.message}</span>}
  </div>

  <button type="submit" disabled={isSubmitting}>
    {isSubmitting ? 'Signing up...' : 'Sign Up'}
  </button>
</form>

); }

Form Arrays

import { useFieldArray, useForm } from 'react-hook-form';

interface OrderForm { items: { productId: string; quantity: number }[]; notes: string; }

function OrderForm() { const { register, control, handleSubmit } = useForm<OrderForm>({ defaultValues: { items: [{ productId: '', quantity: 1 }], notes: '', }, });

const { fields, append, remove } = useFieldArray({ control, name: 'items', });

return ( <form onSubmit={handleSubmit(onSubmit)}> {fields.map((field, index) => ( <div key={field.id} className="flex gap-2"> <select {...register(items.${index}.productId)}> <option value="">Select product</option> {products.map(p => ( <option key={p.id} value={p.id}>{p.name}</option> ))} </select>

      <input
        {...register(`items.${index}.quantity`, { valueAsNumber: true })}
        type="number"
        min="1"
      />

      <button type="button" onClick={() => remove(index)}>
        Remove
      </button>
    </div>
  ))}

  <button type="button" onClick={() => append({ productId: '', quantity: 1 })}>
    Add Item
  </button>

  <textarea {...register('notes')} placeholder="Notes" />
  <button type="submit">Submit Order</button>
</form>

); }

Controlled Components with RHF

import { Controller, useForm } from 'react-hook-form'; import { DatePicker } from '@/components/date-picker';

function EventForm() { const { control, handleSubmit } = useForm();

return ( <form onSubmit={handleSubmit(onSubmit)}> <Controller name="date" control={control} rules={{ required: 'Date is required' }} render={({ field, fieldState }) => ( <div> <DatePicker value={field.value} onChange={field.onChange} /> {fieldState.error && ( <span className="error">{fieldState.error.message}</span> )} </div> )} />

  <button type="submit">Create Event</button>
</form>

); }

Best Practices

Do Don't

Use React Hook Form for complex forms Manage all form state manually

Use Zod/Yup for validation Write validation from scratch

Show inline errors Show all errors at once

Use aria-* attributes Forget accessibility

Debounce expensive validations Validate async on every keystroke

• ✅ Use controlled inputs when you need real-time validation

• ✅ Use uncontrolled inputs (RHF) for better performance

• ✅ Validate on blur for better UX

• ✅ Show loading state during submission

• ❌ Don't disable submit button on empty form

• ❌ Don't clear form on error

• ❌ Don't show errors before user interaction

When NOT to Use This Skill

• React Hook Form with Zod schemas - Use react-hook-form skill for detailed patterns

• React 19 Server Actions forms - Use react-19 skill for useActionState and useFormStatus

• Simple input handling - Use react skill for basic controlled/uncontrolled inputs

• Form libraries other than RHF - Follow library-specific documentation

Anti-Patterns

Anti-Pattern Problem Solution

Managing all form state manually Boilerplate, bugs Use React Hook Form

Not validating user input Security/UX issues Use Zod validation schema

Showing all errors on mount Bad UX Validate on blur or submit

Disabling submit on empty form Prevents validation messages Allow submit, show errors

Clearing form on validation error User loses data Keep form data, show errors

Not showing loading state Confusing UX Show loading during submission

Missing accessibility attributes Not accessible Add aria labels and roles

Validating async on every keystroke Performance issues Debounce async validation

Quick Troubleshooting

Issue Likely Cause Fix

Form not submitting Missing onSubmit or action Add onSubmit handler to form

Validation not working Schema not applied Check resolver in useForm

Input not updating Not controlled properly Ensure value and onChange are set

Errors not showing Missing FormMessage Add FormMessage component

Submit button always disabled Wrong isPending check Use formState.isSubmitting

Values not resetting Not calling reset() Call form.reset() after success

Async validation too frequent No debounce Debounce validation function

Reference Documentation

• React Hook Form

• Zod

• MCP: mcp__documentation__fetch_docs → technology: react , topic: forms