Course contentsShow
← React
Lesson 1364 of 2,39634. Suspense FundamentalsFree lesson

Relay's Suspense Integration

How Relay's preloaded queries and fragments coordinate with Suspense for GraphQL data fetching.

Relay's Suspense Integration

What you'll learn: How Relay's preloaded queries and fragments coordinate with Suspense to deliver seamless GraphQL data fetching.

The Core Idea

Relay is Facebook's GraphQL client built with Suspense integration from the ground up. Unlike libraries that bolted Suspense on later, Relay's architecture naturally "suspends" when GraphQL data isn't ready. When you use Relay's usePreloadedQuery or useFragment hooks, they throw promises automatically if data is still loading—triggering the nearest Suspense boundary to show its fallback.

How Relay Works with Suspense

Relay encourages query preloading: you start fetching data before rendering the component that needs it. A typical pattern uses loadQuery to initiate the fetch early (like on route transition), then passes the resulting query reference to your component. When the component calls usePreloadedQuery(query, queryRef), it suspends if data isn't ready yet.

Fragments work similarly—useFragment suspends when its parent query data isn't available. This creates a declarative data dependency tree where each component suspends independently, and Relay's cache coordination ensures minimal waterfalls.

The Relay Advantage

Unlike TanStack Query's useSuspenseQuery (which fetches when the component renders), Relay's preload pattern starts fetching earlier in your app flow. This "render-as-you-fetch" approach reduces perceived loading time because data arrives before components mount. Combined with Relay's aggressive normalization and cache updates, you get smooth transitions between Suspense states.

Relay also handles fragments as first-class Suspense citizens—child components can suspend for their fragment data without blocking siblings, enabling fine-grained loading states.

Key Takeaway: Relay's preloaded queries and fragment system are designed for Suspense, enabling early data fetching and granular component-level suspension for optimal GraphQL loading experiences.