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

forwardRef и передача ref в дочерний компонент

На этой странице
Кратко

forwardRef позволяет компоненту получить ref от родителя и передать его дальше. В React 19 ref можно принимать обычным prop, поэтому forwardRef больше не обязателен.

Вопрос

Для чего нужен forwardRef? Как отличается работа с ref в React 18 и React 19?

Основная идея

Пользовательский компонент скрывает внутреннюю DOM-структуру. Если родитель хочет поставить фокус на поле внутри SearchInput, компонент должен явно предоставить такой доступ. Сам по себе ref на компоненте не означает, что React выберет первый вложенный input.

В React 18 функциональный компонент обычно оборачивают в forwardRef. Функция рендера получает props первым аргументом и ref вторым. Затем ref передают внутреннему DOM-узлу. forwardRef — API-обёртка для компонента, а не хук, поэтому её обычно вызывают на уровне модуля.

Начиная с React 19 функциональный компонент может принять ref в props и передать его дальше. Документация рекомендует этот вариант для нового кода. Если нужно открыть только ограниченный набор команд, например focus() и reset(), используйте useImperativeHandle: родитель получит созданный интерфейс, а не весь DOM-узел. Это полезно для переиспользуемых полей, но обычные данные всё равно лучше передавать декларативно.

Пример

import { forwardRef, useRef, type ComponentPropsWithoutRef } from 'react';
 
// Вариант, совместимый с React 18 и React 19.
const SearchInput = forwardRef<HTMLInputElement, ComponentPropsWithoutRef<'input'>>(
  function SearchInput(props, ref) {
    return <label>Поиск книги <input {...props} ref={ref} /></label>;
  }
);
 
export default function Library() {
  const searchRef = useRef<HTMLInputElement>(null);
  return <>
    <SearchInput ref={searchRef} placeholder="Например, Дюна" />
    <button onClick={() => searchRef.current?.focus()}>Начать поиск</button>
  </>;
}

После commit searchRef.current указывает на внутренний input. Кнопка фокусирует его, хотя разметка поля находится в другом компоненте. В React 19 тот же контракт можно записать как function SearchInput({ ref, ...props }: ComponentPropsWithRef<'input'>) с соответствующим импортом типа.

Тот же компонент в React 19

import { useRef, type ComponentPropsWithRef } from 'react';
 
// ref — обычный prop, forwardRef не нужен
function SearchInput({ ref, ...props }: ComponentPropsWithRef<'input'>) {
  return <label>Поиск книги <input {...props} ref={ref} /></label>;
}
 
export default function Library() {
  const searchRef = useRef<HTMLInputElement>(null);
  return <>
    <SearchInput ref={searchRef} placeholder="Например, Дюна" />
    <button onClick={() => searchRef.current?.focus()}>Начать поиск</button>
  </>;
}

Миграция: codemod npx codemod@latest react/19/remove-forward-ref переписывает обёртки автоматически.

useImperativeHandle: открыть команды, а не весь DOM

import { useImperativeHandle, useRef, type Ref } from 'react';
 
export type VideoHandle = { play: () => void; pause: () => void };
 
function VideoPlayer({ src, ref }: { src: string; ref?: Ref<VideoHandle> }) {
  const videoRef = useRef<HTMLVideoElement>(null);
 
  useImperativeHandle(ref, () => ({
    play: () => videoRef.current?.play(),
    pause: () => videoRef.current?.pause(),
  }), []);
 
  return <video ref={videoRef} src={src} />;
}
 
function Lesson() {
  const player = useRef<VideoHandle>(null);
  return <>
    <VideoPlayer ref={player} src="/lesson.mp4" />
    <button onClick={() => player.current?.play()}>Смотреть</button>
  </>;
  // player.current.style или .remove() недоступны — родитель видит только play/pause
}
ref без useImperativeHandle:  родитель получает весь <video> → может сломать что угодно
ref с useImperativeHandle:    родитель получает { play, pause } → явный контракт

Что важно помнить

  • Передайте ref до нужного узла: если забыть это, ссылка останется null.
  • Условно скрытый внутренний input также означает отсутствие узла.
  • Не открывайте внутренний DOM каждого компонента без практической причины: это усиливает связанность.
  • useImperativeHandle требует корректных зависимостей методов, которые читает его callback.
  • Не называйте forwardRef удалённым API: он существует, но в React 19 уже не необходим.

Мини-шпаргалка

React 18: forwardRef((props, ref) => ...). React 19: ref в props. Ограниченные команды: useImperativeHandle.

Документация

forwardRef, useImperativeHandle.

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

Поиск

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