React forwardRefの使い方：refの受け渡しとReact 19のref prop

forwardRef を使うと、親コンポーネントは自分のコンポーネントを通して、その中のDOM要素に ref を渡せます。そうすれば親はその要素で focus() や scrollIntoView() などのメソッドを呼べます。React 19ではもう必要ありません。関数コンポーネントが ref を普通のpropとして受け取るからです。それでも 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 という2つの引数を持つ描画関数を受け取ります。ref は props の中にはなく、別に届きます。Focusをクリックすると、inputRef.current が本物の <input> ノードであることがコンソールで確かめられます。

React 19の書き方：refはprop

React 19以降、関数コンポーネントはほかのpropと同じように ref をpropsで受け取ります。ラッパーも2つ目の引数もいりません。

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ノードから直接読みます。<input> から ref={ref} を削除して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がnull」になる一番よくある原因がこれです。React 19より前は、refが関数に渡されることがなかったので、forwardRef で包まない限り Careful も null になっていました。

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"] を記録します。親が手にするのはその2つのメソッドだけで、入力欄のノードではありません。オブジェクトに select() メソッドを追加し、それを呼ぶボタンを足すと、親ができることがちょうど1つ増えます。

子は本物の入力欄のために自分のref inputRef を持ち、ハンドルがそれを包みます。第3引数は useEffect と同じような依存配列で、その値が変わるとハンドルが作り直されます。

これは控えめに使ってください。親がしたいこと（開く、閉じる、エラーを表示する）のほとんどは、isOpen や error のようなpropsのほうが適しています。命令的なメソッドは、フォーカス、スクロール、動画の再生、アニメーションの開始など、自然なpropがない操作のためのものです。

子の中でもrefを使う

子が自分の仕事のために同じDOMノードを必要とすることがあります。たとえばサイズを測ったり、エラーの後にフォーカスしたりしつつ、親もそのノードへのrefを持っている場合です。1つの ref 属性が受け取れる値は1つだけなので、refコールバックで2つをまとめます。

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は1つのコンポーネントずつ伝わります。Form が Field を描画し、それが TextInput を描画し、それが <input> を描画するなら、それぞれのコンポーネントが次へ ref を渡す必要があります。React 19では転送するpropが1つ増えるだけです（<TextInput ref={ref} />）。forwardRef では、すべての層を包む必要がありました。古いバージョンでは、propsのスプレッド（{...props}）ではrefは運ばれません。React 19より前は、ref が props に含まれることはなかったからです。

これが問題になるのは主にデザインシステムのコンポーネントです。ネイティブ要素を包む Button、Input、Select はrefを転送すべきです。そうすれば、それを使うアプリがフォーカスしたり、サイズを測ったり、ポップオーバーを配置するライブラリに渡したりできます。

forwardRefから移行する

変更は機械的です。ラッパーを取り除き、propsから 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 をpropとして渡さないからです。クラスコンポーネントには影響しません。クラスコンポーネントに付けたrefは、今もコンポーネントのインスタンスを指します。

TypeScript

forwardRef では、型引数はrefの型、propsの順で指定します。

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 にほかのpropと同じように型を付けます。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);

ref自体（DOMへのアクセス、レンダリングなしで保たれる値、refコールバック）についてはuseRefのページで扱っています。コンポーネントへの型付け全般は、ReactとTypeScriptを参照してください。