React

Verified against Claude Code · 2026-07-24

Design Suspense boundaries that don't turn into one big spinner

Places Suspense boundaries around real data-fetching seams so a page reveals content progressively instead of waterfalling requests or blocking on one top-level spinner.

Claude CodeCursorClaudeChatGPT

The prompt

Ready to copy — highlighted parts are example details you can swap.

<role>
You are designing where Suspense boundaries go on a data-heavy page, so the page reveals content progressively instead of either waterfalling requests or blocking everything behind one top-level spinner.
</role>

<page>
A creator profile page: header with avatar and follow button, a stats row, a paginated grid of posts, and a "similar creators" rail below the fold.
</page>

<data_dependencies>
Profile header needs a fast /profile call; stats row needs a separate /stats call that is usually slower; posts grid needs /posts?page=1, independent of the others; similar creators needs a slow recommendation call.
</data_dependencies>

<fetching_approach>
TanStack Query hooks with suspense: true
</fetching_approach>

<design_rules>
- Start requests as early as possible — as close to the route/component entry point as the fetching approach allows — even if the component that renders the result is deep in the tree and behind its own Suspense boundary. Never gate the start of a fetch behind the boundary that displays it.
- One Suspense boundary per independently-loading region of the UI, not one boundary per component. Group things that should visually appear together and can tolerate loading together.
- Never put a slow, non-critical section (comments, related items, a sidebar widget) in the same boundary as the primary content — an unrelated slow request should not delay what the user actually came for.
- Name a fallback for every boundary that matches the shape of what it's replacing (a skeleton with the right layout, not a generic spinner), so the loading state doesn't cause a visible layout jump.
- Call out any place where two sibling boundaries would race in a way that produces a confusing partial layout, and resolve it by grouping them into one boundary instead.
</design_rules>

<output_format>
1. A tree diagram (text is fine) showing where each Suspense boundary sits and what's inside it.
2. For each boundary: what triggers its fallback, and what the fallback should look like.
3. Any request-waterfall risk you found and how the boundary placement avoids it.
</output_format>
Customize the highlighted detailsoptional — the prompt above already works

Why this works

The "start the fetch before the boundary that displays it" rule targets React's own documented render-as-you-fetch guidance: if a component only starts fetching inside its own effect or on mount, and that component is the thing hidden by a Suspense fallback, the fetch can't even begin until the boundary above it has already resolved something else — that's a self-inflicted waterfall, and it's the single most common Suspense mistake. Grouping boundaries by what should visually appear together, rather than one boundary per component, is the documented fix for the "popcorn" effect where unrelated pieces of a page pop in one at a time in a distracting, unplanned order. Separating a slow non-critical section (recommendations, comments) into its own boundary is what actually delivers the promised benefit of Suspense — a fast primary experience — instead of accidentally re-creating one big spinner because everything shares a boundary with the slowest request on the page.

What you get back

<ProfilePage> <Suspense fallback={<HeaderSkeleton />}> ← header + stats, fetch started at route entry <ProfileHeader /> <StatsRow /> </Suspense> <Suspense fallback={<PostsGridSkeleton />}> ← independent, can resolve before or after header <PostsGrid page={1} /> </Suspense> <Suspense fallback={<SimilarCreatorsSkeleton />}> ← slow recommendation call, isolated so it never blocks the above <SimilarCreators /> </Suspense> </ProfilePage> Waterfall risk: header and stats were originally one call each — merged into one boundary since they're requested together and always appear together, avoiding a two-step pop-in for content that reads as one unit.

Verified against

Claude Code Sonnet 4.6 · 2026-07-24

Claude Sonnet 4.6 · 2026-07-30

Changelog

  • 2026-07-24 Initial publish, verified against Claude Code and Claude on Sonnet 4.6 with TanStack Query.

Need this built into your business?

If a prompt isn't enough — custom software, built and maintained for you — that's Scult's day job.

EXPLORE CUSTOM SOFTWARE
All React prompts

Check your AI visibility

One URL in, a 0–100 score and the exact fixes out.

RUN THE CHECK

Browse all the tools

15 tools across six categories
13 of them never send your data anywhere

Free · No signup · No trial clock

SEE THE DIRECTORY