Controlled vs Uncontrolled Components in React

A controlled component is a form element whose value lives in React state: you pass value and update the state in onChange, so React decides what the input shows. An uncontrolled component keeps its value in the DOM, like plain HTML: you pass a starting defaultValue and read the current value later through a ref or FormData.

import { useRef, useState } from 'react';

export default function App() {
    const [controlled, setControlled] = useState('Ada');
    const uncontrolledRef = useRef(null);

    function readBoth() {
        console.log('controlled:', controlled);
        console.log('uncontrolled:', uncontrolledRef.current.value);
    }

    return (
        <div style={{ display: 'grid', gap: 8, maxWidth: 260 }}>
            <input
                value={controlled}
                onChange={(e) => setControlled(e.target.value)}
            />
            <input defaultValue="Linus" ref={uncontrolledRef} />
            <p>Controlled value in state: {controlled}</p>
            <button onClick={readBoth}>Read both</button>
        </div>
    );
}

Type in both inputs. The paragraph follows the first one on every keystroke, because each change sets state and renders again. The second input changes only in the DOM; React does not render, and you see its value only when "Read both" asks for it.

Controlled inputs

With a controlled input, React state is the single source of truth. The flow on every keystroke is:

1. The user types, and the browser fires an input event.
2. Your onChange handler reads e.target.value and calls the setter.
3. React renders again and writes the new state back into the input's value.

Because your code sits in the middle of that loop, you can do things an uncontrolled input cannot: reject or reshape characters, show the value somewhere else, disable a button until the value is valid, or set the value from code (a "Clear" button, a suggestion the user clicks).

import { useState } from 'react';

export default function App() {
    const [code, setCode] = useState('');

    function handleChange(e) {
        const digits = e.target.value.replace(/\D/g, '').slice(0, 6);
        setCode(digits);
    }

    return (
        <div>
            <input
                value={code}
                onChange={handleChange}
                placeholder="6 digit code"
                style={{ letterSpacing: 6, fontSize: 18, width: 150 }}
            />{' '}
            <button disabled={code.length !== 6}>Verify</button>{' '}
            <button onClick={() => setCode('123456')}>Fill demo code</button>
        </div>
    );
}

Try typing letters: they never appear, because the handler strips anything that is not a digit before setting state. The Verify button stays disabled until there are exactly six digits.

Controlled is what the form examples on the forms page use, and it is the default choice in most React code.

Uncontrolled inputs

An uncontrolled input works like plain HTML. React renders it once with defaultValue (or defaultChecked for checkboxes and radios) and then leaves it alone. To read the value, either keep a ref to the element or read all named fields from the form on submit with FormData.

import { useState } from 'react';

export default function App() {
    const [result, setResult] = useState(null);

    function handleSubmit(e) {
        e.preventDefault();
        const data = new FormData(e.target);
        setResult(Object.fromEntries(data));
    }

    return (
        <form onSubmit={handleSubmit}>
            <input name="city" defaultValue="Oslo" />{' '}
            <label>
                <input name="subscribe" type="checkbox" defaultChecked />
                Subscribe
            </label>{' '}
            <button type="submit">Send</button>
            {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
        </form>
    );
}

There is no state for the fields and no onChange. The values are collected only when the form submits. Untick the checkbox and send again: the subscribe key disappears, because an unchecked checkbox is not part of FormData at all.

Changing defaultValue after the first render does nothing to the input, since React applies it only when the element is created. To reset an uncontrolled form, call e.target.reset(), or give the form a new key so React creates fresh inputs.

An input you cannot type in

If you pass value but no onChange, the input is controlled, but nothing ever updates the state. React writes the same value back after every keystroke, so the input looks frozen.

import { useState } from 'react';

export default function App() {
    const [name, setName] = useState('Ada');

    return (
        <div style={{ display: 'grid', gap: 8, maxWidth: 260 }}>
            <input value={name} />
            <input value={name} onChange={(e) => setName(e.target.value)} />
            <input defaultValue={name} />
            <input value={name} readOnly />
        </div>
    );
}

Try typing in each field. The first one does not change. The second one is the fix for a controlled input, and as you type there, the first and last fields follow it, because all three read the same state. The third accepts typing because it is uncontrolled. The fourth says on purpose that it cannot be edited.

In development, React logs a warning for the first input: "You provided a value prop to a form field without an onChange handler". The preview runs like a production build, so you will not see that warning here, but you will in your own dev server.

Changing from uncontrolled to controlled

React decides whether an input is controlled by looking at value. If value is undefined or null, the input is uncontrolled. So an input whose value starts as undefined and later becomes a string switches from uncontrolled to controlled during its life, and React warns in development: "A component is changing an uncontrolled input to be controlled".

The warning points at a real bug. Going back the other way, from a string to undefined, turns the input uncontrolled again, and React stops writing to it.

import { useState } from 'react';

export default function App() {
    const [buggy, setBuggy] = useState(undefined);
    const [fixed, setFixed] = useState('');

    return (
        <div style={{ display: 'grid', gap: 8, maxWidth: 300 }}>
            <input
                value={buggy}
                onChange={(e) => setBuggy(e.target.value)}
                placeholder="Starts as undefined"
            />
            <button onClick={() => setBuggy(undefined)}>Clear first</button>
            <input
                value={fixed}
                onChange={(e) => setFixed(e.target.value)}
                placeholder="Starts as an empty string"
            />
            <button onClick={() => setFixed('')}>Clear second</button>
        </div>
    );
}

Type something in both inputs and press each Clear button. The second input empties. The first keeps its text: setting state to undefined made it uncontrolled, so React no longer controls what it shows.

The usual source of undefined is data that has not loaded yet (value={user.name} before the user arrives) or an object field that does not exist yet. Two fixes:

const [name, setName] = useState('');   // start with a string
<input value={user?.name ?? ''} />       // or fall back to one

For checkboxes the same rule applies to checked: start it at false, not undefined.

File inputs are always uncontrolled

An <input type="file"> cannot be controlled, because browsers do not let a page set its value (a page that could pick files on your disk would be a security hole). Read the chosen files from e.target.files in onChange, or through a ref when the form submits.

import { useRef, useState } from 'react';

export default function App() {
    const inputRef = useRef(null);
    const [files, setFiles] = useState([]);

    function handleChange(e) {
        setFiles(Array.from(e.target.files, (f) => `${f.name} (${f.size} bytes)`));
    }

    function clear() {
        inputRef.current.value = '';
        setFiles([]);
    }

    return (
        <div>
            <input type="file" multiple ref={inputRef} onChange={handleChange} />
            <button onClick={clear}>Clear</button>
            <ul>
                {files.map((f) => (
                    <li key={f}>{f}</li>
                ))}
            </ul>
            {files.length === 0 && <p>No files chosen.</p>}
        </div>
    );
}

Choose a file or two from your computer; nothing is uploaded, the example only lists names and sizes. The one value you may set on a file input is the empty string, which is how the Clear button resets it.

When to choose which

Pick controlled when the screen has to react to the value while the user types. Pick uncontrolled when you only need the values at the end, which is also how React 19 form actions work: <form action={fn}> hands your function a FormData and resets the uncontrolled fields afterward.

Rendering on every keystroke sounds expensive, but for a normal form it is not a problem. It becomes one only when a large, slow tree re-renders with the input; then keep the state close to the input, or move the slow part into its own component.

The same two words describe your own components too. A component that gets its value and an onChange from its parent through props is controlled by the parent; one that keeps its own state is uncontrolled. Moving state up to make a component controlled is what lifting state up is about.