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.