Skip to content

Controlled Component

In one line

A controlled component is a form input whose value is controlled by React state — the input always reflects the state, and changes update the state.

In simple words

A controlled input is one where React state is the "single source of truth" for the input's value. You set value={state} and onChange={(e) => setState(e.target.value)}. The input always shows the current state, and every keystroke flows through React.

This makes form data immediately available in your component for validation, formatting, or conditional UI. You can transform the value on input (e.g., uppercase), prevent invalid characters, or disable submission based on the current value.

The alternative is an uncontrolled component, where the DOM itself holds the value and you read it with a ref on submit. Controlled components are the React-idiomatic approach and are recommended for most forms.

Example

jsx
function NameForm() {
  const [name, setName] = useState("");
  return (
    <input
      value={name}
      onChange={(e) => setName(e.target.value)}
    />
  );
}

// `name` always equals the input's current value.

The input's value is bound to state. Every keystroke updates state, and the input re-renders with the new value — they are always in sync.

Common confusions

  • Confused with: uncontrolled component

    The difference: A controlled component's value comes from React state. An uncontrolled component's value lives in the DOM and is read via a ref. Controlled is React-idiomatic; uncontrolled is simpler for basic one-time-read forms.

Related terms

Related Resources

Related Lessons

  • Forms

    Learn controlled inputs and form handling.

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors

← Back to glossary