React Controlled vs Uncontrolled Components

Understanding when to use controlled versus uncontrolled components is essential for building React forms. Here's a comprehensive guide to both approaches.

Controlled Components#

import React, { useState } from 'react';

function ControlledInput() {
  const [value, setValue] = useState('');

  const handleChange = (e) => {
    setValue(e.target.value);
  };

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

// React controls the input value
// Every keystroke triggers a re-render
// You have full control over the input state

Uncontrolled Components#

import React, { useRef } from 'react';

function UncontrolledInput() {
  const inputRef = useRef(null);

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

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

// DOM controls the input value
// Read value only when needed
// Less React involvement

Controlled Form Example#

function ControlledForm() {
  const [formData, setFormData] = useState({
    name: '',
    email: '',
    message: '',
  });
  const [errors, setErrors] = useState({});

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

    // Real-time validation
    if (name === 'email' && !value.includes('@')) {
      setErrors((prev) => ({ ...prev, email: 'Invalid email' }));
    } else {
      setErrors((prev) => ({ ...prev, [name]: null }));
    }
  };

  const handleSubmit = (e) => {
    e.preventDefault();
    console.log('Form data:', formData);
  };

  return (
    <form onSubmit={handleSubmit}>
      <div>
        <input
          name="name"
          value={formData.name}
          onChange={handleChange}
          placeholder="Name"
        />
      </div>

      <div>
        <input
          name="email"
          value={formData.email}
          onChange={handleChange}
          placeholder="Email"
        />
        {errors.email && <span>{errors.email}</span>}
      </div>

      <div>
        <textarea
          name="message"
          value={formData.message}
          onChange={handleChange}
          placeholder="Message"
        />
      </div>

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

Uncontrolled Form Example#

function UncontrolledForm() {
  const nameRef = useRef(null);
  const emailRef = useRef(null);
  const messageRef = useRef(null);

  const handleSubmit = (e) => {
    e.preventDefault();

    const formData = {
      name: nameRef.current.value,
      email: emailRef.current.value,
      message: messageRef.current.value,
    };

    console.log('Form data:', formData);
  };

  return (
    <form onSubmit={handleSubmit}>
      <div>
        <input ref={nameRef} defaultValue="" placeholder="Name" />
      </div>

      <div>
        <input ref={emailRef} defaultValue="" placeholder="Email" />
      </div>

      <div>
        <textarea ref={messageRef} defaultValue="" placeholder="Message" />
      </div>

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

File Inputs (Always Uncontrolled)#

function FileInput() {
  const fileRef = useRef(null);
  const [fileName, setFileName] = useState('');

  const handleFileChange = (e) => {
    const file = e.target.files[0];
    if (file) {
      setFileName(file.name);
    }
  };

  const handleSubmit = (e) => {
    e.preventDefault();
    const file = fileRef.current.files[0];
    console.log('Selected file:', file);
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="file"
        ref={fileRef}
        onChange={handleFileChange}
      />
      {fileName && <p>Selected: {fileName}</p>}
      <button type="submit">Upload</button>
    </form>
  );
}

Hybrid Approach#

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

  // Uncontrolled for simple fields
  const nameRef = useRef(null);
  const notesRef = useRef(null);

  const validateEmail = (value) => {
    if (!value.includes('@')) {
      setEmailError('Invalid email address');
    } else {
      setEmailError('');
    }
  };

  const handleSubmit = (e) => {
    e.preventDefault();

    const formData = {
      name: nameRef.current.value,
      email: email,
      notes: notesRef.current.value,
    };

    console.log(formData);
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        ref={nameRef}
        defaultValue=""
        placeholder="Name"
      />

      <input
        type="email"
        value={email}
        onChange={(e) => {
          setEmail(e.target.value);
          validateEmail(e.target.value);
        }}
        placeholder="Email"
      />
      {emailError && <span>{emailError}</span>}

      <textarea
        ref={notesRef}
        defaultValue=""
        placeholder="Notes"
      />

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

Controlled Select#

function ControlledSelect() {
  const [selected, setSelected] = useState('');

  return (
    <select value={selected} onChange={(e) => setSelected(e.target.value)}>
      <option value="">Select an option</option>
      <option value="option1">Option 1</option>
      <option value="option2">Option 2</option>
      <option value="option3">Option 3</option>
    </select>
  );
}

// Multi-select
function ControlledMultiSelect() {
  const [selected, setSelected] = useState([]);

  const handleChange = (e) => {
    const values = Array.from(e.target.selectedOptions, (opt) => opt.value);
    setSelected(values);
  };

  return (
    <select multiple value={selected} onChange={handleChange}>
      <option value="a">A</option>
      <option value="b">B</option>
      <option value="c">C</option>
    </select>
  );
}

Controlled Checkbox#

function ControlledCheckbox() {
  const [checked, setChecked] = useState(false);

  return (
    <label>
      <input
        type="checkbox"
        checked={checked}
        onChange={(e) => setChecked(e.target.checked)}
      />
      Accept terms
    </label>
  );
}

// Multiple checkboxes
function CheckboxGroup() {
  const [selected, setSelected] = useState(new Set());

  const handleChange = (value) => {
    setSelected((prev) => {
      const next = new Set(prev);
      if (next.has(value)) {
        next.delete(value);
      } else {
        next.add(value);
      }
      return next;
    });
  };

  const options = ['red', 'green', 'blue'];

  return (
    <div>
      {options.map((option) => (
        <label key={option}>
          <input
            type="checkbox"
            checked={selected.has(option)}
            onChange={() => handleChange(option)}
          />
          {option}
        </label>
      ))}
    </div>
  );
}

Controlled Radio Buttons#

function ControlledRadio() {
  const [selected, setSelected] = useState('');

  const options = [
    { value: 'small', label: 'Small' },
    { value: 'medium', label: 'Medium' },
    { value: 'large', label: 'Large' },
  ];

  return (
    <div>
      {options.map((option) => (
        <label key={option.value}>
          <input
            type="radio"
            name="size"
            value={option.value}
            checked={selected === option.value}
            onChange={(e) => setSelected(e.target.value)}
          />
          {option.label}
        </label>
      ))}
    </div>
  );
}

Formatting Input Values#

function PhoneInput() {
  const [value, setValue] = useState('');

  const formatPhone = (input) => {
    const digits = input.replace(/\D/g, '').slice(0, 10);
    if (digits.length <= 3) return digits;
    if (digits.length <= 6) return `(${digits.slice(0, 3)}) ${digits.slice(3)}`;
    return `(${digits.slice(0, 3)}) ${digits.slice(3, 6)}-${digits.slice(6)}`;
  };

  const handleChange = (e) => {
    setValue(formatPhone(e.target.value));
  };

  return (
    <input
      type="tel"
      value={value}
      onChange={handleChange}
      placeholder="(555) 123-4567"
    />
  );
}

// Currency input
function CurrencyInput() {
  const [value, setValue] = useState('');

  const formatCurrency = (input) => {
    const digits = input.replace(/\D/g, '');
    const number = parseInt(digits || '0', 10) / 100;
    return number.toLocaleString('en-US', {
      style: 'currency',
      currency: 'USD',
    });
  };

  return (
    <input
      type="text"
      value={value}
      onChange={(e) => setValue(formatCurrency(e.target.value))}
      placeholder="$0.00"
    />
  );
}

Reset Form#

function ResettableForm() {
  const initialState = { name: '', email: '' };
  const [formData, setFormData] = useState(initialState);

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

  const handleReset = () => {
    setFormData(initialState);
  };

  return (
    <form>
      <input
        name="name"
        value={formData.name}
        onChange={handleChange}
      />
      <input
        name="email"
        value={formData.email}
        onChange={handleChange}
      />
      <button type="button" onClick={handleReset}>
        Reset
      </button>
    </form>
  );
}

Comparison Table#

Feature                  | Controlled        | Uncontrolled
-------------------------|-------------------|------------------
Value source             | React state       | DOM
Re-renders on input      | Yes               | No
Real-time validation     | Easy              | Manual
Form submission          | From state        | From refs
Initial value            | value prop        | defaultValue prop
File inputs              | Not supported     | Supported
Performance              | More re-renders   | Fewer re-renders
Testing                  | Easier            | Requires DOM

Best Practices#

Use Controlled When:
✓ Real-time validation needed
✓ Conditional field disabling
✓ Input formatting required
✓ Dynamic form modifications
✓ Multiple inputs depend on each other

Use Uncontrolled When:
✓ Simple forms with minimal validation
✓ File inputs
✓ Performance is critical
✓ Integrating with non-React code
✓ One-time value reading

General Tips:
✓ Stay consistent within a form
✓ Use controlled for complex interactions
✓ Consider form libraries for large forms
✓ defaultValue, not value, for uncontrolled

Controlled components give you full control over form state through React, enabling real-time validation, formatting, and dynamic behavior. Uncontrolled components let the DOM handle state, offering better performance for simple forms. Choose controlled for interactive forms needing validation, and uncontrolled for simple forms or file inputs. For complex forms, consider using form libraries like React Hook Form that offer the best of both approaches.