useDeferredValue

const deferredValue = useDeferredValue(value)

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

リファレンス

useDeferredValue(value, initialValue?)

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

import { useState, useDeferredValue } from 'react';

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

さらに例を見る

引数

• value: 遅延させたい値。任意の型を持つことができます。
• 省略可能 initialValue: コンポーネントの初回レンダー時に使用する値です。このオプションが省略された場合、初回レンダー時には代わりにレンダーできる value の前のバージョンがないことになるので、useDeferredValue は値の遅延を行いません。

返り値

• currentValue: 初回レンダー時には、initialValue を遅延された値として返すか、もしくはあなたが渡した値をそのまま返します。更新時には、React はまず古い値で再レンダーを試み（つまり返り値は古い値になり）、次に新しい値でバックグラウンドで再レンダーを試みます（返り値は更新後の値になります）。

注意点

• 更新がトランジション内で発生する場合、更新は既に遅延されているため、useDeferredValue は常に新しい value のみを返し、新たな遅延レンダーを発生させません。

• 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 はできるだけ早くリストを更新しようとしますが、ユーザの入力をブロックすることはなくなります。