React Reference ยท Concepts and Pitfalls
Controlled vs uncontrolled
Compare controlled inputs, where React state owns the value, with uncontrolled inputs, where the DOM owns it, and learn when to use each and how to avoid switching.
A form field has a value, and someone has to own it. In a controlled component, React owns it: you pass value (or checked) and an onChange handler, and the field always displays whatever your state says. In an uncontrolled component, the browser owns it: you give an optional starting value with defaultValue and read the result later through a ref or FormData.
Both are valid. Controlled fields are the right choice when the UI reacts to every keystroke: validation as you type, formatting, disabling a button, mirroring the text elsewhere. Uncontrolled fields are simpler and cheaper when you only need the value on submit. The same idea applies to your own components: a component is controlled when its parent passes the value and the change callback, and uncontrolled when it keeps its own state.
// controlled <input value={text} onChange={(e) => setText(e.target.value)} /> // uncontrolled <input defaultValue="start" ref={inputRef} />
Try it
This controlled field forces upper-case letters. The state decides what is shown, so the transformation happens in the handler and the user cannot type a lower-case letter.
The uncontrolled version reads the values only when the form is submitted. Typing causes no renders. The last part of the example shows the warning React prints when a field switches between the two modes.
Press "Give it a value" and check the console for the warning that an uncontrolled input became controlled.
Syntax
| Aspect | Controlled | Uncontrolled |
|---|---|---|
| Source of truth | React state | The DOM element |
| Props | value / checked plus onChange |
defaultValue / defaultChecked, optional ref or name |
| Reading the value | Directly from state | ref.current.value or new FormData(form) |
| Renders per keystroke | One | None |
| Resetting | Set the state | form.reset(), or give the field a new key |
| File input | Not possible | Always uncontrolled (<input type="file">) |
Edge cases: value without onChange makes the field read-only and React warns about it (use readOnly or defaultValue if that was intended). Setting value={null} or undefined makes the field uncontrolled; keep a controlled field's state as a string (''), never undefined or null.
Usage notes
- Pick one mode per field for its whole life. Switching from
undefinedto a string (or the other way) logs a warning because the DOM was previously in charge of the value. defaultValueis read only on the first render. Changing it later does nothing. To start over with a new default, change the component'skey.- Controlled does not mean slow, but a big form with a large tree below each keystroke can lag. Move the state down to the field, or switch the heavy parts to uncontrolled.
- Form Actions favor uncontrolled fields.
<form action={fn}>hands your function aFormData; the form is also reset after a successful action in React 19. - Libraries differ: React Hook Form is built on uncontrolled inputs with refs; Formik uses controlled ones.
- Your own components follow the same rule: if a parent can pass
valueandonChange, support both, using internal state only whenvalueisundefined. - Checkbox and radio inputs use
checked, notvalue, to be controlled.