Suggest an edit

Improve this article

Refine the answer for “What is a "Controlled Component"?”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

## Definition

> A **Controlled Component** is a component whose **value is fully controlled by React state**.
>
> In other words: **UI = a function of state.**

---

## The idea

A regular HTML `<input>` stores its own value internally, in the DOM.
In React, if you make it a **controlled component**,
that field's value is stored **in the component's state**, not in the DOM.

---

## Example of a controlled component

```javascript
function NameForm() {
  const [name, setName] = useState('');

return (
    <div>
      <input
        type="text"
        value={name}                 // <- the value comes from state
        onChange={(e) => setName(e.target.value)} // <- update the state on input
      />
      <p>Hello, {name || 'guest'}!</p>
    </div>
  );
}
```

> Here the `input` **is controlled by the** `name` **state**:
>
> - React stores the field's value in its own `state`;
> - `onChange` updates the state on every change;
> - the UI automatically re-renders with the new value.

---

## Example of an uncontrolled component (for comparison)

```javascript
function NameForm() {
  const inputRef = useRef();

function handleSubmit() {
    alert(`Hello, ${inputRef.current.value}`);
  }

return (
    <div>
      <input type="text" ref={inputRef} /> {/* the value lives in the DOM */}
      <button onClick={handleSubmit}>Submit</button>
    </div>
  );
}
```

> Here the `<input>` **is uncontrolled** - React does not know its value,
> it lives inside the DOM. We can only read it through a `ref`.

---

## Differences

| Criterion | Controlled | Uncontrolled |
|---|---|---|
| Where the value is stored | In React `state` | Inside the DOM |
| How the value changes | Through `onChange` and `setState` | The user types directly |
| When the UI updates | When `state` changes | React does not control it |
| Two-way binding | Yes | No |
| Testability | High | Low |
| Use in forms | Recommended | Only for simple cases |

---

## Why controlled components matter

1. **React fully controls the state** -> the UI is always in sync.
2. **You can validate data on every input.**
3. **You can reset, change, or auto-fill values** programmatically.
4. **A single source of truth** - the field's value = React's state.

---

## Example of use in a form

```javascript
function LoginForm() {
  const [form, setForm] = useState({ email: '', password: '' });

function handleChange(e) {
    setForm({ ...form, [e.target.name]: e.target.value });
  }

function handleSubmit(e) {
    e.preventDefault();
    console.log(form); // use the data from state
  }

return (
    <form onSubmit={handleSubmit}>
      <input
        name="email"
        value={form.email}
        onChange={handleChange}
      />
      <input
        name="password"
        type="password"
        value={form.password}
        onChange={handleChange}
      />
      <button type="submit">Log in</button>
    </form>
  );
}
```

> Here both `<input>`s are fully **controlled by the** `form` **state** -
> React knows about every change in real time.

---

## Summary

| What it is | A component whose value is stored in React state |
|---|---|
| Where the state lives | In React, not in the DOM |
| How it updates | Through `onChange` -> `setState` |
| Example | `<input value={name} onChange={...} />` |
| Benefits | Predictability, validation, a "single source of truth" |
| Analogy | "React holds the steering wheel, not the DOM" |

---

> **Main idea:**
> A controlled component is one
> whose **value React controls**.
>
> The UI simply reflects the current state, rather than storing it itself.

Markdown · drag & drop images · ⌘B / ⌘I shortcuts548 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.