Controlled vs uncontrolled

Controlled means the parent owns the state; the component is a pure function of the value prop. It renders what you pass and reports intent through onChange — it never remembers anything itself. This is the React mental model applied to a single field: UI = f(state), where state lives in the parent. You get full control: derive the value, validate before committing, sync it to a URL, reset it on demand.

function Tabs({ value, onChange }: { value: string; onChange: (v: string) => void }) {
  // no useState here — the active tab is whatever the parent says it is
  return (
    <div role="tablist">
      {["a", "b"].map((id) => (
        <button key={id} aria-selected={value === id} onClick={() => onChange(id)}>
          {id}
        </button>
      ))}
    </div>
  );
}
// caller owns the state and every transition
const [tab, setTab] = useState("a");
<Tabs value={tab} onChange={setTab} />;

The cost: every caller must wire up useState and an onChange, even ones that only want the obvious behaviour.

Uncontrolled means the component owns the state; the parent only seeds it with defaultValue. The component keeps its own useState, initialised once from defaultValue, and never reads that prop again. The caller writes one line and walks away. This is exactly how a native <input defaultValue="hi" /> behaves: you set the starting text, the DOM remembers the rest.

function Tabs({ defaultValue }: { defaultValue: string }) {
  const [value, setValue] = useState(defaultValue); // seeded once, then owned internally
  return (
    <div role="tablist">
      {["a", "b"].map((id) => (
        <button key={id} aria-selected={value === id} onClick={() => setValue(id)}>
          {id}
        </button>
      ))}
    </div>
  );
}
// caller does nothing but pick a starting tab
<Tabs defaultValue="a" />;

The cost: the parent can’t read or steer the value — no URL sync, no programmatic reset, no “validate before applying”. Terse, but a dead end the moment a caller needs control.

A reusable widget should support both modes from one implementation — the prop’s presence picks the mode. The convention React itself uses: if value is passed, you’re controlled (the prop wins); if it’s absent, you’re uncontrolled (internal state wins, seeded by defaultValue). The whole decision collapses into one hook, useControllableState, that every reusable widget can share. It always keeps an internal state cell as a fallback, but reads from the prop whenever the prop is defined.

function useControllableState<T>(opts: {
  value: T | undefined;            // the controlled prop (undefined ⇒ uncontrolled)
  defaultValue: T;                 // seed for uncontrolled mode
  onChange?: (next: T) => void;    // notify the parent on every change
}): [T, (next: T) => void] {
  const isControlled = opts.value !== undefined;
  const [internal, setInternal] = useState(opts.defaultValue);
  const value = isControlled ? (opts.value as T) : internal;

  const setValue = (next: T) => {
    if (!isControlled) setInternal(next); // only own the state when uncontrolled
    opts.onChange?.(next);                // always report, so controlled parents hear it
  };
  return [value, setValue];
}

Notice the asymmetry: in controlled mode setValue does not touch internal state — it only calls onChange and lets the prop flow back in. That keeps a single source of truth instead of two competing copies.

The failure mode has two faces: forcing controlled-only, and silently switching modes mid-life. Force controlled-only and you tax every trivial caller — a one-off tab strip on a settings page now needs its own useState, for nothing. That friction is why developers abandon otherwise-good components. The subtler bug is switching modes during the component’s life: a value that starts undefined and later becomes defined (or vice-versa) flips the component between owning and not owning its state, and React fires the classic “a component is changing an uncontrolled input to be controlled” warning — symptomatic of a lost or duplicated source of truth.

// BUG: value is undefined on first render, then defined → mode flips mid-life
function Field({ user }: { user?: User }) {
  // user?.name is undefined until the fetch resolves
  return <Tabs value={user?.name} onChange={onChange} />; // uncontrolled → controlled ⚠️
}

// FIX: commit to one mode. Coalesce to a stable default so value is never undefined…
<Tabs value={user?.name ?? "a"} onChange={onChange} />;
// …or go fully uncontrolled and let the widget own it:
<Tabs defaultValue={user?.name ?? "a"} />;

The rule the hook enforces: a component is controlled or uncontrolled for its whole lifetime, decided on the first render, never flipped.