React Controlled vs Uncontrolled Components

Understanding the difference between controlled and uncontrolled components is essential for React forms. Here's a comprehensive guide.

Controlled Components#

// Controlled: React manages the state
function ControlledInput() {
  const [value, setValue] = useState('');

  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    setValue(e.target.value);
  };

  return (
    <input
      type="text"
      value={value}
      onChange={handleChange}
    />
  );
}

// Benefits:
// - Single source of truth
// - Instant validation
// - Conditional disable/enable
// - Format input on the fly
// - Enforce input constraints

// Format input
function PhoneInput() {
  const [phone, setPhone] = useState('');

  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    const digits = e.target.value.replace(/\D/g, '');
    const formatted = digits.replace(
      /(\d{3})(\d{3})(\d{4})/,
      '($1) $2-$3'
    );
    setPhone(formatted);
  };

  return <input value={phone} onChange={handleChange} />;
}

// Enforce constraints
function MaxLengthInput() {
  const [value, setValue] = useState('');

  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    if (e.target.value.length <= 10) {
      setValue(e.target.value);
    }
  };

  return <input value={value} onChange={handleChange} />;
}

Uncontrolled Components#

// Uncontrolled: DOM manages the state
function UncontrolledInput() {
  const inputRef = useRef<HTMLInputElement>(null);

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    console.log('Value:', inputRef.current?.value);
  };

  return (
    <form onSubmit={handleSubmit}>
      <input type="text" ref={inputRef} defaultValue="initial" />
      <button type="submit">Submit</button>
    </form>
  );
}

// Benefits:
// - Less code for simple forms
// - Easier integration with non-React code
// - Better performance for many inputs
// - Required for file inputs

// File input (must be uncontrolled)
function FileUpload() {
  const fileRef = useRef<HTMLInputElement>(null);

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    const files = fileRef.current?.files;
    if (files && files.length > 0) {
      uploadFile(files[0]);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input type="file" ref={fileRef} />
      <button type="submit">Upload</button>
    </form>
  );
}

// Default values
function UncontrolledForm() {
  return (
    <form>
      <input type="text" defaultValue="John" />
      <input type="checkbox" defaultChecked />
      <select defaultValue="b">
        <option value="a">A</option>
        <option value="b">B</option>
      </select>
    </form>
  );
}

When to Use Each#

// Use CONTROLLED when:
// - Instant validation
// - Format input as user types
// - Conditional field behavior
// - Enforce input constraints
// - Dynamic form fields
// - Submit via onChange (auto-save)

function ValidatedEmail() {
  const [email, setEmail] = useState('');
  const [error, setError] = useState('');

  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    const value = e.target.value;
    setEmail(value);

    // Instant validation
    if (value && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
      setError('Invalid email');
    } else {
      setError('');
    }
  };

  return (
    <div>
      <input value={email} onChange={handleChange} />
      {error && <span className="error">{error}</span>}
    </div>
  );
}

// Use UNCONTROLLED when:
// - Simple forms with no validation
// - Integration with third-party libraries
// - Performance-critical many-input forms
// - File uploads
// - One-time form submission

function SimpleContactForm() {
  const formRef = useRef<HTMLFormElement>(null);

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    const formData = new FormData(formRef.current!);
    const data = Object.fromEntries(formData);
    sendMessage(data);
  };

  return (
    <form ref={formRef} onSubmit={handleSubmit}>
      <input name="name" defaultValue="" />
      <input name="email" type="email" defaultValue="" />
      <textarea name="message" defaultValue="" />
      <button type="submit">Send</button>
    </form>
  );
}

Hybrid Approaches#

// Mix controlled and uncontrolled
function HybridForm() {
  // Controlled for fields needing validation
  const [email, setEmail] = useState('');
  const [emailError, setEmailError] = useState('');

  // Uncontrolled for simple fields
  const nameRef = useRef<HTMLInputElement>(null);
  const messageRef = useRef<HTMLTextAreaElement>(null);

  const handleEmailChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    setEmail(e.target.value);
    // Validate email
  };

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    const data = {
      name: nameRef.current?.value,
      email,
      message: messageRef.current?.value,
    };
    submitForm(data);
  };

  return (
    <form onSubmit={handleSubmit}>
      <input name="name" ref={nameRef} />
      <input
        name="email"
        value={email}
        onChange={handleEmailChange}
      />
      <textarea name="message" ref={messageRef} />
      <button type="submit">Submit</button>
    </form>
  );
}

// Controlled with deferred updates (performance)
function DeferredInput() {
  const [displayValue, setDisplayValue] = useState('');
  const [debouncedValue, setDebouncedValue] = useState('');

  useEffect(() => {
    const timer = setTimeout(() => {
      setDebouncedValue(displayValue);
    }, 300);
    return () => clearTimeout(timer);
  }, [displayValue]);

  useEffect(() => {
    // Expensive operation only on debounced value
    if (debouncedValue) {
      search(debouncedValue);
    }
  }, [debouncedValue]);

  return (
    <input
      value={displayValue}
      onChange={(e) => setDisplayValue(e.target.value)}
    />
  );
}

Form Libraries#

// React Hook Form (uncontrolled by default)
import { useForm } from 'react-hook-form';

function HookForm() {
  const { register, handleSubmit, formState: { errors } } = useForm();

  const onSubmit = (data) => console.log(data);

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register('name', { required: true })} />
      {errors.name && <span>Required</span>}

      <input {...register('email', {
        required: true,
        pattern: /^\S+@\S+$/
      })} />
      {errors.email && <span>Invalid email</span>}

      <button type="submit">Submit</button>
    </form>
  );
}

// Controlled mode with React Hook Form
function ControlledHookForm() {
  const { control, handleSubmit } = useForm();

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <Controller
        name="email"
        control={control}
        rules={{ required: true }}
        render={({ field }) => <input {...field} />}
      />
    </form>
  );
}

Complex Form Patterns#

// Dynamic form fields (controlled)
function DynamicFields() {
  const [fields, setFields] = useState([{ id: 1, value: '' }]);

  const addField = () => {
    setFields([...fields, { id: Date.now(), value: '' }]);
  };

  const removeField = (id: number) => {
    setFields(fields.filter(f => f.id !== id));
  };

  const updateField = (id: number, value: string) => {
    setFields(fields.map(f =>
      f.id === id ? { ...f, value } : f
    ));
  };

  return (
    <div>
      {fields.map(field => (
        <div key={field.id}>
          <input
            value={field.value}
            onChange={(e) => updateField(field.id, e.target.value)}
          />
          <button onClick={() => removeField(field.id)}>Remove</button>
        </div>
      ))}
      <button onClick={addField}>Add Field</button>
    </div>
  );
}

// Dependent fields
function DependentFields() {
  const [country, setCountry] = useState('');
  const [state, setState] = useState('');
  const [states, setStates] = useState<string[]>([]);

  useEffect(() => {
    if (country) {
      fetchStates(country).then(setStates);
      setState(''); // Reset state when country changes
    }
  }, [country]);

  return (
    <div>
      <select value={country} onChange={(e) => setCountry(e.target.value)}>
        <option value="">Select Country</option>
        <option value="US">United States</option>
        <option value="CA">Canada</option>
      </select>

      <select
        value={state}
        onChange={(e) => setState(e.target.value)}
        disabled={!country}
      >
        <option value="">Select State</option>
        {states.map(s => (
          <option key={s} value={s}>{s}</option>
        ))}
      </select>
    </div>
  );
}

Comparison Table#

| Feature                | Controlled      | Uncontrolled    |
|------------------------|-----------------|-----------------|
| Value source           | React state     | DOM             |
| Validation timing      | Instant         | On submit       |
| Input formatting       | Yes             | No              |
| Performance (many)     | Can be slower   | Better          |
| Code complexity        | More            | Less            |
| Third-party libs       | May conflict    | Easier          |
| File inputs            | Not possible    | Required        |
| Testing                | Easier          | Need refs       |

Best Practices#

Controlled:
✓ Use for forms requiring validation
✓ Use for complex form logic
✓ Use for dependent fields
✓ Consider performance with many inputs

Uncontrolled:
✓ Use for simple forms
✓ Use for file uploads
✓ Use with third-party libs
✓ Use defaultValue, not value

General:
✓ Don't mix value and defaultValue
✓ Keep form state close to the form
✓ Consider form libraries for complex forms
✓ Use appropriate pattern for use case

Controlled components offer more control for validation and formatting, while uncontrolled components are simpler and better for basic forms. Choose based on your needs: controlled for complex validation, uncontrolled for simple forms and file uploads. Consider hybrid approaches and form libraries for complex scenarios.