forwardRef в React: передача ref и ref как пропс в React 19

forwardRef позволяет родительскому компоненту передать ref через ваш компонент к элементу DOM внутри него, чтобы родитель мог вызывать на этом элементе focus(), scrollIntoView() и похожие методы. В React 19 он больше не нужен: функциональные компоненты получают ref как обычный пропс. forwardRef по-прежнему работает, и вы увидите его в большей части существующего кода, поэтому эта страница показывает оба варианта.

import { forwardRef, useRef } from 'react';

const FancyInput = forwardRef(function FancyInput(props, ref) {
    return <input ref={ref} {...props} style={{ padding: 6, border: '2px solid #6c5ce7' }} />;
});

export default function App() {
    const inputRef = useRef(null);

    function handleClick() {
        inputRef.current.focus();
        console.log('the ref points to an', inputRef.current.tagName);
    }

    return (
        <div>
            <FancyInput ref={inputRef} placeholder="Name" />{' '}
            <button onClick={handleClick}>Focus</button>
        </div>
    );
}

forwardRef принимает функцию рендера с двумя аргументами: props и ref, переданный родителем. ref не входит в props; он приходит отдельно. Нажмите Focus, и консоль подтвердит, что inputRef.current это настоящий узел <input>.

Способ React 19: ref это пропс

Начиная с React 19 функциональный компонент получает ref в пропсах, как любой другой пропс. Ни обёртки, ни второго аргумента:

import { useRef } from 'react';

function FancyInput({ ref, ...props }) {
    return <input ref={ref} {...props} style={{ padding: 6, border: '2px solid #00b894' }} />;
}

export default function App() {
    const inputRef = useRef(null);

    return (
        <div>
            <FancyInput ref={inputRef} placeholder="Email" />{' '}
            <button onClick={() => inputRef.current.focus()}>Focus</button>{' '}
            <button onClick={() => console.log('value:', inputRef.current.value)}>
                Log value
            </button>
        </div>
    );
}

Напишите что-нибудь и нажмите Log value: родитель читает текущий текст поля прямо из узла DOM. Удалите ref={ref} у <input> и нажмите Focus: консоль покажет ошибку, потому что inputRef.current теперь null.

Ref, который дочерний компонент игнорирует, остаётся null

Передача ref в компонент сама по себе ничего не делает. Компонент должен поставить его на элемент. Если он этого не делает, ref.current остаётся null:

import { useRef } from 'react';

function Forgetful({ placeholder }) {
    return <input placeholder={placeholder} />;
}

function Careful({ ref, placeholder }) {
    return <input ref={ref} placeholder={placeholder} />;
}

export default function App() {
    const a = useRef(null);
    const b = useRef(null);

    function check() {
        console.log('Forgetful ref:', a.current);
        console.log('Careful ref:', b.current && b.current.tagName);
    }

    return (
        <div>
            <Forgetful ref={a} placeholder="Forgetful" />{' '}
            <Careful ref={b} placeholder="Careful" />{' '}
            <button onClick={check}>Check refs</button>
        </div>
    );
}

Консоль показывает Forgetful ref: null и Careful ref: INPUT. Это самая частая причина «ref.current is null» на пользовательском компоненте. До React 19 Careful тоже был бы null, если бы не был обёрнут в forwardRef, потому что ref вообще не передавался в функцию.

useImperativeHandle: открыть меньший API

Если дать родителю весь узел DOM, он сможет делать с ним что угодно: менять стили, удалять детей, читать значения, которые вы хотели оставить приватными. useImperativeHandle позволяет вместо этого решить, что содержит ref.current:

import { useImperativeHandle, useRef } from 'react';

function SearchBox({ ref }) {
    const inputRef = useRef(null);

    useImperativeHandle(ref, () => ({
        focus() {
            inputRef.current.focus();
        },
        clear() {
            inputRef.current.value = '';
            console.log('cleared by the parent');
        },
    }), []);

    return <input ref={inputRef} placeholder="Search" defaultValue="react hooks" />;
}

export default function App() {
    const searchRef = useRef(null);

    return (
        <div>
            <SearchBox ref={searchRef} />{' '}
            <button onClick={() => searchRef.current.focus()}>Focus</button>{' '}
            <button onClick={() => searchRef.current.clear()}>Clear</button>{' '}
            <button onClick={() => console.log('the parent sees:', Object.keys(searchRef.current))}>
                What can the parent see?
            </button>
        </div>
    );
}

Последняя кнопка выводит ["focus", "clear"]: родитель получает эти два метода и больше ничего, не узел поля. Добавьте в объект метод select() и кнопку, которая его вызывает, и родитель получит ровно одну новую возможность.

Дочерний компонент хранит собственный ref, inputRef, для настоящего поля, а handle оборачивает его. Третий аргумент это массив зависимостей, как у useEffect: handle пересоздаётся, когда эти значения меняются.

Прибегайте к этому экономно. Большинство того, что нужно родителю (открыть, закрыть, показать ошибку), лучше делать пропсами, например isOpen или error. Императивные методы нужны для действий, у которых нет естественного пропса: фокус, прокрутка, воспроизведение видео, запуск анимации.

Использование ref и внутри дочернего компонента

Иногда дочернему компоненту нужен тот же узел DOM для собственной работы, например чтобы измерить его или поставить фокус после ошибки, а родитель тоже держит на него ref. Атрибут ref может принимать только одно значение, поэтому объедините два через ref-колбэк:

function AutoGrowTextarea({ ref, ...props }) {
    const localRef = useRef(null);

    function setRefs(node) {
        localRef.current = node;
        if (typeof ref === 'function') ref(node);
        else if (ref) ref.current = node;
    }

    return <textarea ref={setRefs} {...props} />;
}

ref родителя может быть объектом из useRef или функцией, поэтому обрабатывайте оба случая. Когда родителю нужно лишь несколько действий, useImperativeHandle выше аккуратнее, потому что дочерний компонент оставляет узел себе.

Передача ref через несколько уровней

Ref передаётся по одному компоненту за раз. Если Form рендерит Field, который рендерит TextInput, который рендерит <input>, каждый из этих компонентов должен передать ref следующему. В React 19 это ещё один пропс для передачи (<TextInput ref={ref} />); с forwardRef каждый уровень приходилось оборачивать. Spread пропсов ({...props}) в старых версиях его не переносит, потому что до React 19 ref никогда не был частью props.

Обычно это важно в компонентах дизайн-системы: Button, Input или Select, которые оборачивают нативный элемент, должны передавать свой ref, чтобы использующее их приложение могло поставить на них фокус, измерить их или отдать библиотеке, которая позиционирует всплывающие окна.

Миграция с forwardRef

Изменение механическое: уберите обёртку и читайте ref из пропсов.

// Before
const Button = forwardRef(function Button({ variant, ...props }, ref) {
    return <button ref={ref} className={variant} {...props} />;
});

// After (React 19)
function Button({ variant, ref, ...props }) {
    return <button ref={ref} className={variant} {...props} />;
}

Спешить некуда. forwardRef продолжает работать в React 19, а библиотека, которая должна поддерживать React 18, обязана его сохранить, потому что React 18 не передаёт ref как пропс. Классовых компонентов это не касается: ref на классовом компоненте по-прежнему указывает на экземпляр компонента.

TypeScript

С forwardRef аргументы типа идут в порядке: тип ref, затем пропсы:

import { forwardRef } from 'react';

type FancyInputProps = { label: string };

const FancyInput = forwardRef<HTMLInputElement, FancyInputProps>(
    function FancyInput({ label }, ref) {
        return <input ref={ref} aria-label={label} />;
    }
);

В React 19 типизируйте ref как любой другой пропс. ComponentProps<'input'> его уже включает:

import { useImperativeHandle, useRef, type ComponentProps, type Ref } from 'react';

function FancyInput(props: ComponentProps<'input'>) {
    return <input {...props} />;
}

type SearchHandle = { focus: () => void; clear: () => void };

function SearchBox({ ref }: { ref?: Ref<SearchHandle> }) {
    const inputRef = useRef<HTMLInputElement>(null);
    useImperativeHandle(ref, () => ({
        focus: () => inputRef.current?.focus(),
        clear: () => {
            if (inputRef.current) inputRef.current.value = '';
        },
    }));
    return <input ref={inputRef} />;
}

// In the parent
const searchRef = useRef<SearchHandle>(null);

Страница о useRef разбирает сами рефы: доступ к DOM, значения, которые сохраняются без рендера, и ref-колбэки. О типизации компонентов в целом см. React с TypeScript.