Controlled и uncontrolled компоненты
На этой странице
Controlled (управляемый) компонент получает значение из state React через value/checked и сообщает об изменениях через onChange — источник правды в React. Uncontrolled (неуправляемый) хранит значение сам, в DOM; React задает только начальное значение через defaultValue/defaultChecked, а текущее читают через ref или FormData при отправке. Тот же принцип применяется к собственным компонентам: значение задает родитель или компонент хранит его сам.
Вопрос
Что такое controlled и uncontrolled компоненты? Чем они отличаются и когда что использовать?
Controlled
function SignupForm() {
const [email, setEmail] = useState("");
const isValid = email.includes("@");
return (
<form>
<input value={email} onChange={(e) => setEmail(e.target.value)} />
{!isValid && email && <p role="alert">Некорректный email</p>}
<button disabled={!isValid}>Зарегистрироваться</button>
</form>
);
}React всегда знает текущее значение: можно валидировать на лету, форматировать ввод (маски), блокировать кнопку, синхронизировать поля.
Uncontrolled
function SearchForm({ onSearch }) {
return (
<form
onSubmit={(e) => {
e.preventDefault();
const query = new FormData(e.currentTarget).get("q");
onSearch(query);
}}
>
<input name="q" defaultValue="" />
<button>Найти</button>
</form>
);
}
function FileUpload() {
const fileRef = useRef(null);
return <input type="file" ref={fileRef} />; // input file всегда uncontrolled
}Меньше кода и ререндеров, значение берется в момент отправки.
Сравнение
| Controlled | Uncontrolled | |
|---|---|---|
| Источник правды | state React | DOM |
| Атрибуты | value + onChange | defaultValue, ref, name |
| Ререндер на каждый ввод | да | нет |
| Валидация на лету, маски | удобно | сложнее |
| Интеграция с не-React кодом | сложнее | проще |
| Примеры | формы с логикой | простые формы, input type="file", React 19 Actions |
Типичная ошибка
<input value={name} /> // без onChange — поле только для чтения, предупреждение
<input value={undefined} onChange={...} /> // undefined → uncontrolled, затем строка → предупреждениеЗначение controlled-поля не должно быть undefined: инициализируйте state пустой строкой.
Controlled и uncontrolled собственные компоненты
function Accordion({ open: controlledOpen, defaultOpen = false, onOpenChange, children }) {
const [innerOpen, setInnerOpen] = useState(defaultOpen);
const isControlled = controlledOpen !== undefined;
const open = isControlled ? controlledOpen : innerOpen;
const toggle = () => {
if (!isControlled) setInnerOpen(!open);
onOpenChange?.(!open);
};
return (
<div>
<button onClick={toggle}>Подробнее</button>
{open && children}
</div>
);
}Так устроены компоненты библиотек (Radix, MUI): они работают в обоих режимах — паттерн control props.
Что важно помнить
- React Hook Form по умолчанию использует uncontrolled-поля ради производительности.
- React 19 Actions (
<form action={fn}>) естественно работают с uncontrolled-полями иFormData. - Не переключайте компонент между режимами во время жизни.
- Для больших форм controlled-подход может вызывать много ререндеров — выносите поля в отдельные компоненты или используйте библиотеку форм.
Мини-шпаргалка
Controlled: value + onChange, правда в state. Uncontrolled: defaultValue + ref/FormData, правда в DOM. Controlled — для валидации и масок, uncontrolled — для простых форм и файлов. Свои компоненты — оба режима через control props.
Документация
React: Controlling an input with a state variable, React: Controlled and uncontrolled components.