re:re:actable
Урок 093 минуты чтения

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
}

Меньше кода и ререндеров, значение берется в момент отправки.

Сравнение

ControlledUncontrolled
Источник правдыstate ReactDOM
Атрибутыvalue + onChangedefaultValue, 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.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам