Understanding Controlled vs Uncontrolled Inputs in React
SkillVeris Team
Engineering Team
A controlled input stores its value in React state and updates on every keystroke; an uncontrolled input keeps its value in the DOM and is read with a ref.
In this guide, you'll learn:
- Controlled inputs give React full authority over the value, enabling instant validation, formatting, and conditional logic.
- Uncontrolled inputs are simpler and lighter for basic forms where you only need the value at submit time.
- The presence of a value prop plus onChange makes an input controlled; defaultValue makes it uncontrolled.
- Switching an input between controlled and uncontrolled mid-render triggers a React warning and bugs.
1Controlled vs Uncontrolled Inputs Explained
A controlled input is a form field whose value is stored in React state, so React is the single source of truth; an uncontrolled input keeps its value inside the DOM itself, and you read it with a ref when you need it. The difference comes down to who owns the current value — React or the browser.
With a controlled input, every keystroke fires onChange, updates state, and re-renders the field with the new value. With an uncontrolled input, the DOM tracks typing on its own and React only peeks at the value on demand, such as at submit time.
2How Controlled Inputs Work
A controlled input binds its value prop to state and updates that state in onChange. Because React drives the displayed value, you can transform, validate, or reject input as the user types.
- const [name, setName] = useState('')
- <input value={name} onChange={e => setName(e.target.value)} />
- The value always reflects state, so the UI and data can never drift apart.
- You can format on the fly, like uppercasing or stripping invalid characters, inside onChange.
🔑Single Source of Truth
With controlled inputs, state is the one place the value lives. The input merely displays it, which makes validation and conditional logic straightforward.
3How Uncontrolled Inputs Work
An uncontrolled input lets the DOM manage its own value. You attach a ref to read the value when needed and optionally set an initial value with defaultValue instead of value.
- const inputRef = useRef(null)
- <input defaultValue='' ref={inputRef} />
- inputRef.current.value # read the value, usually on submit
- Use defaultValue, not value, so React does not take control of the field.
When Uncontrolled Fits
Uncontrolled inputs suit simple forms where you only need values once, on submit, and do not need per-keystroke logic. They involve less code and fewer re-renders, which can matter on very large forms.
4Comparing the Two Approaches
Each approach trades control for simplicity. Seeing them side by side clarifies which to reach for.
- Controlled: value in state, re-renders per keystroke, easy validation and formatting, more code.
- Uncontrolled: value in DOM, read via ref, fewer re-renders, less code, harder live validation.
- Controlled enables features like disabling submit until valid or showing a live character count.
- Uncontrolled is handy for quick forms, integrating non-React widgets, or migrating legacy code.
- File inputs are always uncontrolled because their value is read-only for security reasons.
💡Default to Controlled
Most React teams use controlled inputs because live validation and consistent state usually outweigh the extra code. Reach for uncontrolled when simplicity clearly wins.
5Common Mistakes to Avoid
The controlled/uncontrolled distinction produces some of React's most common warnings. These pitfalls cause the majority of them.
- Passing value without onChange, which makes a read-only field the user cannot type into.
- Initializing state to undefined, so the input starts uncontrolled and switches to controlled on first keystroke.
- Mixing value and defaultValue on the same input.
- Using value where you meant defaultValue on an intentionally uncontrolled input.
- Reading a controlled value from a ref instead of from state, getting stale or duplicate logic.
⚠️Never Switch Modes Mid-Life
React warns when an input flips from uncontrolled to controlled. Initialize controlled state to an empty string, not undefined, so the input is controlled from the first render.
6Where Form Libraries Fit
As forms grow, wiring state and validation by hand becomes tedious. Form libraries manage the plumbing and often use uncontrolled inputs under the hood for performance while giving you a controlled-feeling API.
- React Hook Form: uses refs and uncontrolled inputs for speed, with built-in validation.
- Formik: a controlled-input approach with helpers for values, errors, and touched state.
- Native constraint validation: HTML attributes like required and pattern for simple cases.
- Schema validators like Zod pair with either approach to validate shapes centrally.
Why Libraries Prefer Uncontrolled
Reading values from the DOM avoids re-rendering the whole form on every keystroke, which keeps large forms responsive. The library subscribes only where needed, so you get performance without hand-managing dozens of state variables.
7Handling Multiple Fields
Managing a separate state variable per field gets tedious fast. A common controlled-form pattern keeps all values in one state object and uses a single change handler keyed by the input's name attribute.
Each input carries a name that matches a key in the state object, and one handler updates the right key. This scales to any number of fields with almost no extra code, and it pairs naturally with validation that reads the whole values object at once.
- const [values, setValues] = useState({ email: '', password: '' })
- const onChange = e => setValues(v => ({ ...v, [e.target.name]: e.target.value }))
- <input name='email' value={values.email} onChange={onChange} />
- One handler serves every field because it reads e.target.name.
💡Key by name
Giving each input a name that matches a state key lets a single onChange update the correct field, so adding a field means adding one input, not new state.
8Key Takeaways
The controlled versus uncontrolled choice shapes how you build every React form. Keep these points in mind.
- Controlled inputs store the value in state and update on every change; uncontrolled inputs keep it in the DOM.
- Controlled inputs enable live validation, formatting, and a single source of truth.
- Uncontrolled inputs mean less code and fewer re-renders for simple forms, read via refs.
- Initialize controlled state to a string, never undefined, to avoid the mode-switch warning.
- File inputs are always uncontrolled, and form libraries often use uncontrolled inputs for speed.
9Frequently Asked Questions
Q: Which should I use, controlled or uncontrolled inputs? A: Default to controlled inputs for most forms because they make validation, formatting, and conditional logic simple with state as the single source of truth. Choose uncontrolled inputs for very simple forms or when integrating non-React code, reading values via refs.
Q: Why do I get a 'changing an uncontrolled input to controlled' warning? A: It usually means the input's state started as undefined, so React saw an uncontrolled field, then a value arrived and made it controlled. Initialize the state to an empty string instead of undefined so the input is controlled from the first render.
Q: Can file inputs be controlled? A: No. For security reasons a file input's value cannot be set by JavaScript, so file inputs are always uncontrolled. You read the selected files through a ref or the change event's target.files.
Q: Do controlled inputs hurt performance? A: For typical forms the extra re-renders are negligible. On very large forms with many fields, the per-keystroke re-renders can add up, which is why some libraries use uncontrolled inputs internally to stay fast.
Related Reading
Get The Print Version
Download a PDF of this article for offline reading.
About the Publisher
SkillVeris Team
Engineering Team
Our engineering writers turn abstract code concepts into hands-on, project-driven learning experiences.
View all postsRelated Posts
Never miss an update
Get the latest tutorials and guides delivered to your inbox.
No spam. Unsubscribe anytime.