Controlled and Uncontrolled Components
Form inputs in React can be handled in two ways. In a controlled component, React state holds the current value and the input simply displays it. In an uncontrolled component, the browser's DOM keeps the value, and React reads it only when needed, usually through a ref. Both are valid. Choosing well depends on how much your component needs to know about the value while the user is typing.
A controlled input
A controlled input has a value prop bound to state and an onChange handler that updates the state. Each keystroke flows from the input to state and back to the input. Because React holds the value, you can transform it, validate it on every change, or disable the submit button until it is acceptable.
import { useRef, useState } from 'react';
function PincodeField() {
const [pin, setPin] = useState('');
return (
<>
<input
value={pin}
onChange={e => setPin(e.target.value.replace(/\D/g, '').slice(0, 6))}
inputMode="numeric"
/>
<button disabled={pin.length !== 6}>Check delivery</button>
</>
);
}
function FeedbackForm() {
const messageRef = useRef(null);
const fileRef = useRef(null);
function handleSubmit(event) {
event.preventDefault();
console.log(messageRef.current.value, fileRef.current.files[0]);
}
return (
<form onSubmit={handleSubmit}>
<textarea ref={messageRef} defaultValue="Great session!" />
<input type="file" ref={fileRef} />
<button>Send</button>
</form>
);
}
The pincode field strips non-digits and limits the length as the user types. That kind of live control is only possible when React owns the value.
An uncontrolled input
The feedback form leaves its values in the DOM. defaultValue sets the starting text once, after which the browser manages it. A ref created with useRef gives you the DOM node, and you read .value on submit. File inputs are always uncontrolled, because their value can only be set by the user for security reasons.
Checkboxes and radio buttons follow the same rules with a different prop. A controlled checkbox uses checked and onChange, reading e.target.checked, while an uncontrolled one uses defaultChecked. A select is controlled through value on the select itself, not by marking an option as selected.
Choosing between them
| Need | Better fit |
|---|---|
| Validate or format while typing | Controlled |
| Enable or disable buttons based on input | Controlled |
| One field affects another | Controlled |
| Read values only on submit | Uncontrolled is simpler |
| File uploads | Uncontrolled |
| Wrapping a non-React widget | Uncontrolled |
Many large-form libraries use uncontrolled inputs internally to avoid re-rendering on every keystroke, then expose a controlled-style API to you.
Switching from uncontrolled to controlled
React warns "A component is changing an uncontrolled input to be controlled" when an input's value starts as undefined and later becomes a string. This often happens with useState() called without an initial value, or when data loads from an API after the first render. Initialise state with an empty string, or write value={name ?? ''}.
The opposite mistake is setting value without onChange, which freezes the field so the user cannot type. And mixing both value and defaultValue on one input makes React ignore the default and log a warning.
Performance is rarely a reason to avoid controlled inputs in normal forms. Re-rendering one small component per keystroke is cheap. It becomes noticeable only when the state sits high in a large tree, so keep form state in the form component itself rather than in a distant parent.
Rule of thumb
Use controlled inputs when the component reacts to the value as it changes, and uncontrolled inputs with refs when you only need the final value or are dealing with files.
Ready to master real-world web development?
Learn HTML, CSS3, Bootstrap and JavaScript hands-on with mentor-led sessions.