🎛️ Controlled vs Uncontrolled Components

Two Ways to Hold a Value

Every form input has a value that lives somewhere. The only question is who owns it: React state, or the DOM node itself. That single choice defines the two patterns.

💡 Analogy: A controlled component is like dictating to an assistant who writes down every word as you speak — you always know exactly what's on the page. An uncontrolled component is handing someone a notepad and only reading it when they hand it back — simpler, but you don't see it change in real time.

Controlled Components

A controlled component takes its current value from state and reports changes back through onChange. React is the single source of truth, so the input can never drift out of sync with your data.

import { useState } from 'react';

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

  return (
    <div>
      <input
        value={value}
        onChange={(e) => setValue(e.target.value)}
        placeholder="Type something…"
      />
      <p>You typed: {value}</p>  {/* always up to date */}
    </div>
  );
}

Strengths

• Live value — the current text is always in state, ready for validation or display.
• Predictable — one source of truth means fewer surprises.
• Reactive UI — enable/disable buttons, show hints, or reformat as the user types.
• Coordination — one field can easily react to another.

Costs

• More code: state + handler per field (or the single-object pattern).
• A re-render on every keystroke — rarely a problem, occasionally worth optimizing.

Uncontrolled Components

An uncontrolled component lets the DOM keep the value. You set an initial value with defaultValue (not value) and grab the current value with a ref when you need it — usually at submit time.

import { useRef } from 'react';

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

  const handleSubmit = (e) => {
    e.preventDefault();
    alert(`You entered: ${inputRef.current.value}`); // read on demand
  };

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

Strengths

• Less code for simple forms — no state, no change handler.
• No per-keystroke re-render.
• Easy interop with non-React code and third-party DOM libraries.

Costs

• No live value — you only see it when you ask via the ref.
• Harder to do real-time validation or coordinate fields.

Side by Side

The same two-field form, both ways

// CONTROLLED — state is the source of truth
function ControlledForm() {
  const [name, setName] = useState('');
  const [email, setEmail] = useState('');

  const handleSubmit = (e) => {
    e.preventDefault();
    console.log({ name, email });
  };

  return (
    <form onSubmit={handleSubmit}>
      <input value={name} onChange={(e) => setName(e.target.value)} />
      <input value={email} onChange={(e) => setEmail(e.target.value)} />
      <button type="submit">Submit</button>
    </form>
  );
}

// UNCONTROLLED — the DOM holds the values; refs read them at submit
function UncontrolledForm() {
  const nameRef = useRef(null);
  const emailRef = useRef(null);

  const handleSubmit = (e) => {
    e.preventDefault();
    console.log({ name: nameRef.current.value, email: emailRef.current.value });
  };

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

Choosing an Approach

When you're unsure, walk this quick decision tree. In practice most branches lead to "controlled" — which is exactly why it's the default.

Special Cases & Hybrids

File inputs are always uncontrolled

For security, a browser won't let JavaScript set a file input's value, so <input type="file"> can't be controlled. Read the chosen files from the event or a ref — and you can still keep a little controlled state alongside to show feedback:

import { useRef, useState } from 'react';

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

  const handleChange = (e) => {
    const file = e.target.files[0];
    if (file) setFileName(file.name); // controlled state for display
  };

  return (
    <div>
      <input type="file" ref={fileRef} onChange={handleChange} />
      {fileName && <p>Selected: {fileName}</p>}
    </div>
  );
}

Controlled input + ref for DOM actions

A controlled input can still hold a ref when you need a genuine DOM operation like focusing. Here the value is controlled, but the ref lets us refocus after clearing:

function SearchBox() {
  const [query, setQuery] = useState('');
  const inputRef = useRef(null);

  const handleClear = () => {
    setQuery('');
    inputRef.current.focus(); // DOM action the state can't express
  };

  return (
    <div>
      <input
        ref={inputRef}
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Search…"
      />
      {query && <button type="button" onClick={handleClear}>Clear</button>}
    </div>
  );
}

Seeding controlled state from an API

When editing existing data, fetch it, drop it into state, and go fully controlled from there:

function ProfileEditor({ userId }) {
  const [profile, setProfile] = useState(null);

  useEffect(() => {
    let active = true;
    fetch(`/api/users/${userId}`)
      .then((r) => r.json())
      .then((data) => { if (active) setProfile(data); });
    return () => { active = false; }; // avoid setting state after unmount
  }, [userId]);

  if (!profile) return <p>Loading…</p>;

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

  return (
    <input name="displayName" value={profile.displayName} onChange={handleChange} />
  );
}

Hands-on Exercise

function ControlledContact() {
  const [form, setForm] = useState({ name: '', email: '', message: '' });
  const handleChange = (e) =>
    setForm((p) => ({ ...p, [e.target.name]: e.target.value }));
  const handleSubmit = (e) => { e.preventDefault(); console.log(form); };

  return (
    <form onSubmit={handleSubmit}>
      <input name="name" value={form.name} onChange={handleChange} />
      <input name="email" value={form.email} onChange={handleChange} />
      <textarea name="message" value={form.message} onChange={handleChange} />
      <button type="submit">Send</button>
    </form>
  );
}

// Part A — uncontrolled
import { useRef } from 'react';

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

  const handleSubmit = (e) => {
    e.preventDefault();
    console.log({
      name: nameRef.current.value,
      email: emailRef.current.value,
      message: messageRef.current.value,
    });
    e.target.reset();
  };

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

// Part B — hybrid search box
import { useState, useRef } from 'react';

function SearchBox() {
  const [query, setQuery] = useState('');
  const inputRef = useRef(null);

  const clear = () => {
    setQuery('');
    inputRef.current.focus();
  };

  return (
    <div>
      <input
        ref={inputRef}
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Search…"
      />
      {query && <button type="button" onClick={clear}>Clear</button>}
    </div>
  );
}

Best Practices

Summary & Quiz

📚 Further Reading

• React — Controlling an input with a state variable
• React — Referencing values with refs
• React — useRef reference

🚀 What's Next?

We touched useEffect when seeding state from an API. Next we go deep on it: the useEffect Hook for side effects — data fetching, subscriptions, timers, and cleaning them all up correctly.