useDeferredValue

const deferredValue = useDeferredValue(value)

• リファレンス
  • useDeferredValue(value)
• 使用法
  • 新しいコンテンツが読み込まれている間、古いコンテンツを表示する
  • コンテンツが古いことをインジケータで表示する
  • UI �?一部分�?再レンダーを遅延させる

リファレンス

useDeferredValue(value)

コンポーネント�?トップレベルで useDeferredValue を呼び出し、そ�?値�?遅延されたバージョンを取得します。

import { useState, useDeferredValue } from 'react';

function SearchPage() {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);
  // ...
}

さらに例を見る

引数

• value: 遅延させたい値。任意�?型を持つことができます。

返り値

初回レンダー時には、返される値はあなたが渡した値と同一になります。更新時には、React はまず古い値で再レンダーを試み（つまり返り値は古い値になり）、次に新しい値でバックグラウンドで再レンダーを試みます（返り値は更新後�?値になります）。

注意点

• useDeferredValue に渡す値は、プリミティブな値（文字列や数値など）またはレンダー�?外部で作成されたオブジェクトであるべきです。レンダー中に新しいオブジェクトを作成してすぐにそれを useDeferredValue に渡すと、それは毎回�?レンダーで異なるも�?となるため、不必要なバックグラウンドで�?再レンダーを引き起こします。

• useDeferredValue が（Object.is で比較して）異なる値を受け取ると、（前回�?値を使用する）現在�?レンダーに加えて、新しい値でバックグラウンドで再レンダーをスケジュールします。バックグラウンドで�?再レンダーは中断可能です。value に別�?更新があると、React はバックグラウンドで�?再レンダーを最初からやり直します。例えば、ユーザが素早く入力を行い、それがそ�?値を受け取るチャートコンポーネントが再レンダーできるよりも速かった場合、チャートはユーザがタイプを止めたあとに再表示されることになります。

• useDeferredValue は <Suspense> と統合されています。新しい値によって引き起こされるバックグラウンド更新が UI をサスペンドした場合でも、ユーザにフォールバックは表示されません。データが読み込まれるまで、以前�?遅延された値が表示され続けます。

• useDeferredValue 自体に余計なネットワークリクエストを防ぐ仕組みはありません。

• useDeferredValue 自体による固�?��?遅延はありません。React が元�?再レンダーを終えるとすぐに、新しい遅延値で�?バックグラウンド再レンダー作業を開始します。イベント（タイピングなど）による更新は、バックグラウンド�?再レンダーを中断して優先的に処理されます。

• useDeferredValue によるバックグラウンド�?再レンダーは、画面にコミットされるまでエフェクトを�?�行しません。バックグラウンド�?再レンダーがサスペンドする場合、そ�?再レンダーに対応するエフェクトはデータ�?読み込みと UI �?更新�?後に�?�行されます。

使用法

新しいコンテンツが読み込まれている間、古いコンテンツを表示する

UI �?一部�?更新を遅延させるために、コンポーネント�?トップレベルで useDeferredValue を呼び出します。

import { useState, useDeferredValue } from 'react';

function SearchPage() {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);
  // ...
}

初回レンダー時には、遅延される値は関数に渡した値と同じになります。

更新時には、遅延される値は最新�?値から「遅れ」ます。具体的には、React はまず遅延値を更新せずに再レンダーを行い、次に新たに受け取った値でバックグラウンドで�?再レンダーを試みます。

例を使って、これが役立つ場面を見ていきましょう。

こ�?例では、SearchResults コンポーネントは検索結果をフェッチする間サスペンドします。"a" を入力し、結果を待ってから "ab" に書き換えてみてください。"a" �?検索結果が、ロード中フォールバックに�?換されてしまいます。

こ�?代わりに一般的に使われる UI パターンは、結果リスト�?更新を遅延させて、新しい結果が準備できるまで前�?結果を表示し続けるというも�?です。遅延バージョン�?クエリ文字列を渡すために useDeferredValue を呼び出します：

export default function App() {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);
  return (
    <>
      <label>
        Search albums:
        <input value={query} onChange={e => setQuery(e.target.value)} />
      </label>
      <Suspense fallback={<h2>Loading...</h2>}>
        <SearchResults query={deferredQuery} />
      </Suspense>
    </>
  );
}

query �?方はすぐに更新されるため、入力フィールドは新しい値を表示します。しかし、deferredQuery はデータが読み込まれるまで前�?値を保持するため、SearchResults はしばらく古い結果を表示します。

以下�?例で "a" を入力し、結果が読み込まれる�?を待ち、次に入力欄を "ab" に書き換えてみてください。新しい結果が読み込まれるまでは、サスペンスによるフォールバック�?代わりに古い結果リストが表示され続けることに着�?してください。

コンテンツが古いことをインジケータで表示する

上記�?例では、最新�?クエリ�?結果リストがまだロード中であることを示すインジケータがありません。新しい結果がロードされる�?に時間がかかると、ユーザ�?混乱を招く可能性があります。結果リストが最新�?クエリと一致していないことをユーザに明確に伝えるために、古い結果リストが表示されているときに視覚的なインジケータを追加することができます：

<div style={{
  opacity: query !== deferredQuery ? 0.5 : 1,
}}>
  <SearchResults query={deferredQuery} />
</div>

これにより、入力を開始すると直ちに、古い結果リストがわずかに暗くなり、新しい結果リストがロードされるまでそ�?状態が続きます。以下�?例�?ように、暗くなる�?を遅延させる CSS トランジションを追加することで、徐々に変化するように感じさせることもできます。

UI �?一部分�?再レンダーを遅延させる

useDeferredValue をパフォーマンス最適化として適用することもできます。これは、UI �?一部�?再レンダーに時間がかかり、それを最適化する簡単な方法がないが、それによって UI �?他�?部分がブロックされる�?を防ぎたい、という場合に有用です。

テキストフィールドと、各キーストロークごとに再レンダーするコンポーネント（チャートや長いリストなど）があると想像してみてください：

function App() {
  const [text, setText] = useState('');
  return (
    <>
      <input value={text} onChange={e => setText(e.target.value)} />
      <SlowList text={text} />
    </>
  );
}

まずは SlowList を最適化して、props が同じ場合は再レンダーをスキップするようにします。これを行うには、memo でラップします。

const SlowList = memo(function SlowList({ text }) {
  // ...
});

しかし、これが有用な�?は SlowList �? props が前回�?レンダー時と同一である場合�?みです。現在直面している問題は、props が異なっており現に別�?見た�?�?結果を表示しないといけない場合に遅い、ということです。

具体的には、主なパフォーマンス�?問題は、入力フィールドに何かを入力するたびに、SlowList が新しい props を受け取り、そ�?ツリー全体を再レンダーするため、入力がもたつく感じになるということです。こ�?ようなケースでは、useDeferredValue を使うことで、入力フィールド�?更新（速くなければならない）を結果リスト�?更新（遅くても許される）よりも優先することが可能です。

function App() {
  const [text, setText] = useState('');
  const deferredText = useDeferredValue(text);
  return (
    <>
      <input value={text} onChange={e => setText(e.target.value)} />
      <SlowList text={deferredText} />
    </>
  );
}

これによって SlowList �?再レンダー自体を高速化しているわけではありません。しかし、React に対して、リスト�?再レンダーは優先度を下げても良いと伝えることで、キーストロークをブロックしないようにします。リストは入力フィールド�?「後を追う」形になり、そ�?後「追いつきます」。元と同様に、React はできるだけ早くリストを更新しようとしますが、ユーザ�?入力をブロックすることはなくなります。