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