React Controlled Components: Inputs, Checkboxes, and Forms

🔍 What Is It?

A controlled component keeps its value in React state:

const [email, setEmail] = useState('');
<input value={email} onChange={e => setEmail(e.target.value)} />

Contrast with an uncontrolled component where the DOM owns the value:

const inputRef = useRef<HTMLInputElement>(null);
<input ref={inputRef} />
// read when mounted: inputRef.current?.value

Both approaches are supported. Choose controlled state when rendering or validation depends on the current value; choose an uncontrolled input with defaultValue, a ref, or FormData when you only need its value at submission.

Choose the right controlled prop

Initialize a controlled text value to an empty string, not undefined or null. Keep its ownership stable for that input's lifetime. defaultValue and defaultChecked set initial uncontrolled values; they do not keep an input synchronized with later state changes.

🎯 Why Do We Need It?

Controlled components give you:

• →Real-time validation — validate as the user types
• →Conditional rendering — show/hide fields based on other field values
• →Pre-filling — populate forms from API data
• →Programmatic reset — clear the form after submission
• →Derived state — compute dependent fields automatically
• →Testability — test form behaviour by simulating state changes

🏗️ What Happens in Real Projects?

In a claims submission form:

• →Multi-step form where step 2 data depends on step 1 selections
• →Real-time field validation (email format, phone number, date ranges)
• →Auto-populate fields from a policy lookup
• →Conditional fields (show "secondary claimant" section only if "joint claim" is checked)
• →Calculate premium estimate as the user fills in coverage details

⚙️ How It Works

The controlled input cycle:

1. State holds the current value: const [value, setValue] = useState('')
2. Input renders with the state value: <input value={value} />
3. User types a character
4. onChange fires: onChange={e => setValue(e.target.value)}
5. State updates
6. React re-renders the input with the new value

Update the state backing value or checked synchronously in onChange. Debounce an expensive search request or derived calculation separately rather than delaying the input's own state update. For an intentionally read-only input, provide readOnly explicitly.

Number fields and resetting

Keep a number input's editable state as text so an empty field remains representable. Convert and validate at the boundary where a number is required; Number('') is 0, so test emptiness first. A native form reset does not replace React state: reset the controlled state as part of your reset handler.

💻 Example

Controlled Forms in Production — A complete native-input example followed by an enterprise form excerpt using project UI components.

import { useState, type FormEvent } from 'react';

const initialProfile = { name: '', role: 'reader', bio: '', subscribed: false };

export default function ControlledProfileForm() {
  const [profile, setProfile] = useState(initialProfile);
  const [submitted, setSubmitted] = useState('');

  function handleSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    setSubmitted(JSON.stringify(profile));
  }

  return (
    <form onSubmit={handleSubmit} onReset={() => {
      setProfile({ ...initialProfile });
      setSubmitted('');
    }}>
      <label>Name
        <input name="name" required value={profile.name}
          onChange={event => setProfile(previous => ({ ...previous, name: event.target.value }))} />
      </label>
      <label>Role
        <select name="role" value={profile.role}
          onChange={event => setProfile(previous => ({ ...previous, role: event.target.value }))}>
          <option value="reader">Reader</option>
          <option value="editor">Editor</option>
        </select>
      </label>
      <label>Bio
        <textarea name="bio" value={profile.bio}
          onChange={event => setProfile(previous => ({ ...previous, bio: event.target.value }))} />
      </label>
      <label>
        <input name="subscribed" type="checkbox" checked={profile.subscribed}
          onChange={event => setProfile(previous => ({ ...previous, subscribed: event.target.checked }))} />
        Subscribe
      </label>
      <button type="submit">Save</button>
      <button type="reset">Reset</button>
      <output aria-live="polite">{submitted}</output>
    </form>
  );
}

🤔 Common Confusions

🚨 Common Production Issues

✅ Best Practices

🏛️ Architect's Note

💬 Frequently Asked Questions

🎯 Key Takeaways

🔗 Related Topics

🎯 Practice this topic in interviews

↗ Where this topic fits