本文へ移動

k8o

お問い合わせ

255文字以内で入力してください

GitHub Issueからのお問い合わせもお待ちしております。

Blog

公開: 2025年6月21日(土)更新: 2026年11月9日(月)約14分で読めます

SuspenseListで複数のSuspenseの表示順を制御する

ReactのSuspenseListは、並べた複数のSuspenseを上から順に、または全部そろってから表示させるコンポーネントです。revealOrderとtailの値ごとの見え方と、実験版のReactで変わった既定値を確かめます。

はじめに

SuspenseListは、並べた複数のSuspenseを、読み込みが終わった順ではなく上から順に、または全部そろってから表示させるReactのコンポーネントです。Reactの実験版でだけ、unstable_SuspenseListという名前で使えます(以後はSuspenseListと呼びます)。

それぞれのSuspenseを読み込めたものから表示するときは、Suspenseを並べます。全部そろってから表示するだけなら、外側を1つのSuspenseで包んでも同じです。読み込みの速さに関わらず上から順に表示したいときや、次に表示するものだけにフォールバックUIを出したいときに、SuspenseListが要ります。

SuspenseListとは

SuspenseListは2019年に実験的な機能として追加され、今も実験版(react@experimental)にだけあります。安定版とcanary版のReactには含まれていません。

次のコンポーネントは、読み込みに1.5秒、2秒、0.5秒、1秒かかる4つのSuspenseを並べています。

jsx
import { Suspense, unstable_SuspenseList as SuspenseList, use } from 'react';

const wait = (ms) => new Promise((resolve) => setTimeout(() => resolve(ms), ms));
const items = [1500, 2000, 500, 1000].map(wait);

const Item = ({ promise }) => <p>{use(promise)}ms</p>;

export default function App() {
  return (
    <SuspenseList revealOrder="forwards" tail="collapsed">
      {items.map((promise, i) => (
        <Suspense key={i} fallback={<p>Loading {i + 1}...</p>}>
          <Item promise={promise} />
        </Suspense>
      ))}
    </SuspenseList>
  );
}

実験版のReactで動かすと、最初はLoading 1...だけが出ます。1.5秒ほどで1500msとLoading 2...に変わり、2秒ほどで4つがそろって表示されます。0.5秒で読み込みが終わる3つ目も、上の2つが表示されるまで待ちます。SuspenseListを外すと、3つ目が0.5秒ほどで先に表示されます。

基本的な使い方

SuspenseListは、revealOrderとtailの2つのpropsで子要素の表示順を決めます。

jsx
<SuspenseList revealOrder="forwards" tail="collapsed">
  <Suspense fallback={<div>Loading 1...</div>}>
    <Component1 />
  </Suspense>
  <Suspense fallback={<div>Loading 2...</div>}>
    <Component2 />
  </Suspense>
  <Suspense fallback={<div>Loading 3...</div>}>
    <Component3 />
  </Suspense>
</SuspenseList>

revealOrder

revealOrderは、子要素を表示する順を決めます。省くとforwardsになります。

forwards(順次表示)

子要素を上から順番に表示します。最初の要素が完了するまで、次の要素は表示されません。

jsx
<SuspenseList revealOrder="forwards" tail="collapsed">
  {/* 1番目が完了してから2番目、2番目が完了してから3番目... */}
</SuspenseList>
backwards(逆順表示)

子要素を逆の順に並べて、下から順番に表示します。最初の子要素がいちばん下に置かれ、そこから上へ表示されます。

jsx
<SuspenseList revealOrder="backwards" tail="hidden">
  {/* 最初の子要素をいちばん下に置き、下から順に表示 */}
</SuspenseList>

先ほどの4つのSuspenseをbackwardsで並べると、画面には4つ目が上、1つ目がいちばん下に並び、その1つ目から表示されます。並びを変えずに最後の要素から表示する以前のbackwardsは、unstable_legacy-backwardsという値に残っています。こちらは上から1つ目、2つ目の順に並んだまま、4つ目と3つ目が先に表示されます。

together(同時表示)

すべての子要素が準備できるまで待機し、準備が完了したら一斉に表示します。

jsx
<SuspenseList revealOrder="together">
  {/* すべて準備完了後に一斉表示 */}
</SuspenseList>
independent(独立表示)

子要素は、ほかの子要素の読み込みに関わらず、読み込めたものから表示されます。SuspenseListが無いときと同じ動きです。

jsx
<SuspenseList revealOrder="independent">
  {/* 各要素が独立して表示 */}
</SuspenseList>

independentは、以前はrevealOrderを省いたときの動作でした。今は値として渡せ、revealOrderの既定値はforwardsに変わっています。

tail

tailは、まだ表示していない子要素のフォールバックUIをどう出すかを決めます。revealOrderがforwardsかbackwardsのときだけ効き、省くとhiddenになります。togetherにtailを渡すと、開発用のビルドでは<SuspenseList tail="collapsed" /> is only valid if revealOrder is "forwards" (default) or "backwards".という警告がコンソールに出て、tailは無視されます。

collapsed

次に表示する子要素のフォールバックUIだけを出します。forwardsなら、最初は1番目のフォールバックUIだけが出ます。

jsx
<SuspenseList revealOrder="forwards" tail="collapsed">
  {/* 次のfallbackのみ表示 */}
</SuspenseList>
hidden

まだ表示していない子要素のフォールバックUIを出しません。前の子要素が表示されるまで、その下には何も出ません。

jsx
<SuspenseList revealOrder="forwards" tail="hidden">
  <Suspense fallback={<div>Loading 1...</div>}>
    <Component1 />
  </Suspense>
  <Suspense fallback={<div>Loading 2...</div>}>
    <Component2 />
  </Suspense>
</SuspenseList>
visible

まだ表示していない子要素のフォールバックUIを、すべて出します。

jsx
<SuspenseList revealOrder="forwards" tail="visible">
  <Suspense fallback={<div>Loading 1...</div>}>
    <Component1 />
  </Suspense>
  <Suspense fallback={<div>Loading 2...</div>}>
    <Component2 />
  </Suspense>
</SuspenseList>

visibleは、以前はtailを省いたときの動作でした。今は値として渡せます。

SuspenseListの利点

SuspenseListには、次の利点があります。

  • レイアウトシフトが減る:上から順に表示するので、読み込みの終わった順でレイアウトが動くことがありません。
  • 待ち時間が短く感じられる:読む人が思う順に内容が出るので、子要素の読み込み時間に大きな差がなければ、速く読み込めたように感じられます。

SuspenseListを使わずに並べた場合

このサイトの例は安定版のReactで動くので、SuspenseListを使えません。代わりに、SuspenseListを使わずに4つのSuspenseを並べると、読み込みの終わった順にばらばらに表示されることを確かめられます。チェックを切り替えると、フォールバックUIの有無で見え方がどう変わるかも比べられます。

tsx
import { Suspense, use, useState } from 'react';

const wait = (ms: number): Promise<number> =>
  new Promise((resolve) => {
    setTimeout(() => resolve(ms), ms);
  });

const load = () => [
  { key: 'key1', time: wait(1500) },
  { key: 'key2', time: wait(2000) },
  { key: 'key3', time: wait(500) },
  { key: 'key4', time: wait(1000) },
];

function Item({ name, time }: { name: string; time: Promise<number> }) {
  const ms = use(time);
  return (
    <li>
      {name}: {ms}ms
    </li>
  );
}

export default function App() {
  const [items, setItems] = useState(load);
  const [hasFallback, setHasFallback] = useState(true);

  return (
    <>
      <label>
        <input
          type="checkbox"
          checked={hasFallback}
          onChange={(event) => {
            setHasFallback(event.target.checked);
            setItems(load());
          }}
        />
        フォールバックUIを表示する
      </label>
      <ul className="items">
        {items.map(({ key, time }) => (
          <Suspense
            key={key}
            fallback={hasFallback ? <li className="fallback">Loading...</li> : null}
          >
            <Item name={key} time={time} />
          </Suspense>
        ))}
      </ul>
    </>
  );
}
結果

おわりに

SuspenseListを使うと、並べたSuspenseを上から順に、または全部そろってから表示できます。今も実験版にだけあり、既定値やbackwardsの意味も変わっているので、使うときは入れた実験版でrevealOrderとtailの動きを確かめます。