forwardRef

const SomeComponent = forwardRef(render)

• リファレンス
  • forwardRef(render)
  • render 関数
• 使用法
  • 親コンポーネントに DOM ノードを公開する
  • 複数コンポーネントを経由した ref �?転送
  • DOM ノード�?代わりに命令型ハンドルを公開する
• トラブルシューティング
  • コンポーネントを forwardRef でラップしている�?に、ref が常に null になる

リファレンス

forwardRef(render)

forwardRef() を呼び出すことで、コンポーネントが ref を受け取ってそれを子コンポーネントに転送 (forward) できるようになります。

import { forwardRef } from 'react';

const MyInput = forwardRef(function MyInput(props, ref) {
  // ...
});

さらに例を見る

引数

• render: コンポーネント�?レンダー関数です。React はこ�?関数を親から受け取った props および ref とともに呼び出します。返す JSX がコンポーネント�?出力となります。

返り値

forwardRef は JSX でレンダーできる React コンポーネントを返します。プレーンな関数として�?�義された React コンポーネントとは異なり、forwardRef によって返されるコンポーネントは ref 属性を受け取ることもできます。

注意点

• Strict Mode では、React はレンダー関数が誤って純関数でなくなってしまう問題を見つけやすくするため、レンダー関数を 2 回呼び出します。これは開発環境専用�?挙動であり、本番環境には影響しません。レンダー関数が純粋である場合（そうであるべきです）、これはコンポーネント�?ロジックに影響を与えません。呼び出し�?うち�?一方から�?結果は無視されます。

render 関数

forwardRef は引数としてレンダー関数を受け取ります。React はこ�?関数を props および ref とともに呼び出します。

const MyInput = forwardRef(function MyInput(props, ref) {
  return (
    <label>
      {props.label}
      <input ref={ref} />
    </label>
  );
});

引数

• props: 親コンポーネントから渡された props です。

• ref: 親コンポーネントから渡された ref 属性です。ref はオブジェクト�?場合と関数�?場合があります。親コンポーネントが ref を渡していない場合は null になります。受け取った ref は、別�?コンポーネントに渡すか、useImperativeHandle に渡します。

返り値

forwardRef は JSX でレンダーできる React コンポーネントを返します。プレーンな関数として�?�義された React コンポーネントとは異なり、forwardRef によって返されるコンポーネントは ref 属性を受け取ることができます。

使用法

親コンポーネントに DOM ノードを公開する

デフォルトでは、各コンポーネント内�? DOM ノードはプライベートです。しかし、時には親に DOM ノードを公開することが有用な場合があります。例えば、ノードにフォーカスを当てることを許可したい場合です。これを明示的に許可するために、コンポーネント�?�義を forwardRef() でラップします。

import { forwardRef } from 'react';

const MyInput = forwardRef(function MyInput(props, ref) {
  const { label, ...otherProps } = props;
  return (
    <label>
      {label}
      <input {...otherProps} />
    </label>
  );
});

props �?後�?第 2 引数として ref が渡されます。公開したい DOM ノードにそれを渡してください。

import { forwardRef } from 'react';

const MyInput = forwardRef(function MyInput(props, ref) {
  const { label, ...otherProps } = props;
  return (
    <label>
      {label}
      <input {...otherProps} ref={ref} />
    </label>
  );
});

これで、親�? Form コンポーネントが、MyInput によって公開された <input> DOM ノードにアクセスできるようになります。

function Form() {
  const ref = useRef(null);

  function handleClick() {
    ref.current.focus();
  }

  return (
    <form>
      <MyInput label="Enter your name:" ref={ref} />
      <button type="button" onClick={handleClick}>
        Edit
      </button>
    </form>
  );
}

こ�? Form コンポーネントは MyInput に ref を渡しています。MyInput コンポーネントはそ�? ref をブラウザ�? <input> タグに転送しています。そ�?結果、Form コンポーネントはこ�? <input> DOM ノードにアクセスし、focus() を呼び出すことができるようになります。

コンポーネント内�? DOM ノードへ�? ref を公開することで、後でコンポーネント�?内部を変更する�?が難しくなることに注意してください。通常は、ボタンやテキスト入力フィールドなど�?再利用可能な低レベルコンポーネントからは DOM ノード�?公開を行いますが、アバターやコメント�?ようなアプリケーションレベル�?コンポーネントでは行いません。

複数コンポーネントを経由した ref �?転送

ref を DOM ノードに転送する代わりに、独自コンポーネントである MyInput に転送することもできます。

const FormField = forwardRef(function FormField(props, ref) {
  // ...
  return (
    <>
      <MyInput ref={ref} />
      ...
    </>
  );
});

さらにそ�? MyInput コンポーネントが自身�? <input> に ref を転送すれば、FormField へ�? ref はそ�? <input> へ�?参照を受け取ることになります。

function Form() {
  const ref = useRef(null);

  function handleClick() {
    ref.current.focus();
  }

  return (
    <form>
      <FormField label="Enter your name:" ref={ref} isRequired={true} />
      <button type="button" onClick={handleClick}>
        Edit
      </button>
    </form>
  );
}

Form コンポーネントは ref を�?�義し、それを FormField に渡しています。FormField コンポーネントはそ�? ref を MyInput に転送し、MyInput はそれをブラウザ�? <input> DOM ノードに転送しています。これで Form が DOM ノードにアクセスできるようになります。

DOM ノード�?代わりに命令型ハンドルを公開する

DOM ノードをまるごと公開する代わりに、使用できるメソッドを制限したカスタムオブジェクトである、命令型ハンドル (imperative handle) を公開することができます。これを行うには、DOM ノードを保持するため�?別�? ref を�?�義します。

const MyInput = forwardRef(function MyInput(props, ref) {
  const inputRef = useRef(null);

  // ...

  return <input {...props} ref={inputRef} />;
});

そして受け取った ref を useImperativeHandle に渡し、ref で公開したい値を指�?�します。

import { forwardRef, useRef, useImperativeHandle } from 'react';

const MyInput = forwardRef(function MyInput(props, ref) {
  const inputRef = useRef(null);

  useImperativeHandle(ref, () => {
    return {
      focus() {
        inputRef.current.focus();
      },
      scrollIntoView() {
        inputRef.current.scrollIntoView();
      },
    };
  }, []);

  return <input {...props} ref={inputRef} />;
});

何らか�?コンポーネントが MyInput へ�? ref を取得すると、DOM ノード�?代わりにあなたが書いた { focus, scrollIntoView } というオブジェクトを受け取ります。これにより、DOM ノードについて公開する情報を最小限に制限することができます。

命令型ハンドル�?使用について詳しく読む

トラブルシューティング

コンポーネントを forwardRef でラップしている�?に、ref が常に null になる

これは通常、受け取った ref を�?�際に使用する�?を忘れていることを意味します。

例えば、こ�?コンポーネントは ref を全く使用していません：

const MyInput = forwardRef(function MyInput({ label }, ref) {
  return (
    <label>
      {label}
      <input />
    </label>
  );
});

�?正するにはこ�? ref を、DOM ノードか、ref を受け入れることができる別�?コンポーネントに渡します。

const MyInput = forwardRef(function MyInput({ label }, ref) {
  return (
    <label>
      {label}
      <input ref={ref} />
    </label>
  );
});

一部�?ロジックが条件付きである場合にも、MyInput へ�? ref が null になることがあります。

const MyInput = forwardRef(function MyInput({ label, showInput }, ref) {
  return (
    <label>
      {label}
      {showInput && <input ref={ref} />}
    </label>
  );
});

showInput が false �?場合、ref はど�?ノードにも転送されないため、MyInput へ�? ref は空�?ままになります。特に、以下�?例�?ように条件が別�?コンポーネント、例えば Panel �?中に隠されている場合、これを見落としがちです。

const MyInput = forwardRef(function MyInput({ label, showInput }, ref) {
  return (
    <label>
      {label}
      <Panel isExpanded={showInput}>
        <input ref={ref} />
      </Panel>
    </label>
  );
});