Concept

An important feature to know about React Suspense is the concept of a Suspense boundary. This allows you to easily consolidate multiple loading states into a single place, which prevents the cascade of loading indicators.

Suspense boundaries allow you coordinate which parts of your UI should always “pop in” together at the same time.
You can group different portions of the UI into different boundaries to create the perfect user experience for your specific use case.

Examples

Consider a simple application (similar to BooleanArt) that shows a nav, table of contents (TOC), Video and a Description.

---------------------------
|          Nav            |
---------------------------
|       |                 |
|       |                 |
|       |      Video      |
|       |                 |
|  TOC  |                 |
|       |-----------------|
|       |                 |
|       |    Description  |
|       |                 |
---------------------------

The following components can take a while to load because they depend on external data:

TableOfContents
LessonVideo
LessonDescription

If we don't use suspense the page is not returned (even the Nav) till all components are done rendering. This is bad:

app/none/page.tsx

app/none/Lesson.tsx

import { PageRoot, Row } from "@/lib/Layout";
import { Nav } from "@/lib/Nav";
import { TableOfContents } from "@/lib/TableOfContents";
import { Lesson } from "./Lesson";

export default function Home() {
  return (
    <PageRoot>
      <Nav />
      <Row flex={1}>
        <TableOfContents />
        <Lesson />
      </Row>
    </PageRoot>
  );
}

We can go extreme and wrap each of these in their own suspense boundary:

app/three/page.tsx

app/three/Lesson.tsx

import { PageRoot, Row } from "@/lib/Layout";
import { TableOfContentsLoading } from "@/lib/Loaders/TableOfContentsLoading";
import { Nav } from "@/lib/Nav";
import { TableOfContents } from "@/lib/TableOfContents";
import { Suspense } from "react";
import { Lesson } from "./Lesson";

export default function Home() {
  return (
    <PageRoot>
      <Nav />
      <Row flex={1}>
        <Suspense fallback={<TableOfContentsLoading />}>
          <TableOfContents />
        </Suspense>
        <Lesson />
      </Row>
    </PageRoot>
  );
}

Or we can do clever organization, e.g. wrapping the "LessonVideo+LessonDescription" in one suspense boundary and TableOfContents in another:

app/two/page.tsx

app/two/Lesson.tsx

import { PageRoot, Row } from "@/lib/Layout";
import { TableOfContentsLoading } from "@/lib/Loaders/TableOfContentsLoading";
import { Nav } from "@/lib/Nav";
import { TableOfContents } from "@/lib/TableOfContents";
import { Suspense } from "react";
import { Lesson } from "./Lesson";

export default function Home() {
  return (
    <PageRoot>
      <Nav />
      <Row flex={1}>
        <Suspense fallback={<TableOfContentsLoading />}>
          <TableOfContents />
        </Suspense>
        <Lesson />
      </Row>
    </PageRoot>
  );
}

Or even take the simple path of wrapping the portion of the UI that might take a while to render in a single Suspense. Note that Suspense automatically goes the the fallback UI even for children (or grandchildren and so on...).

app/one/page.tsx

app/one/Lesson.tsx

import { PageRoot, Row } from "@/lib/Layout";
import { PageLoading } from "@/lib/Loaders/PageLoading";
import { Nav } from "@/lib/Nav";
import { TableOfContents } from "@/lib/TableOfContents";
import { Suspense } from "react";
import { Lesson } from "./Lesson";

export default function Home() {
  return (
    <PageRoot>
      <Nav />
      <Row flex={1}>
        <Suspense fallback={<PageLoading />}>
          <TableOfContents />
          <Lesson />
        </Suspense>
      </Row>
    </PageRoot>
  );
}

Transcript