Declarative Data Loading with React Suspense in React 18+

Problem: Boilerplate Loading States in React

When a component needs remote data, developers typically add isLoading flags, conditional rendering, and sometimes manual retry logic. The UI quickly becomes cluttered with loading spinners, error messages, and duplicated state handling.

Thesis: Let Suspense Turn Async Data into Declarative UI States

React 18’s Suspense boundary can catch promises thrown by components, automatically displaying a fallback until the promise resolves. This pattern moves loading logic out of the component tree, making the UI easier to reason about.

How Suspense Works for Data Fetching

• Components call a data‑resource function that returns a value or throws a Promise.
• If the promise is pending, Suspense intercepts it and renders its fallback.
• Once the promise resolves, the component re‑renders with the data.
• If the promise rejects, an ErrorBoundary is required to catch it.

Concrete Example: A Simple Resource Wrapper

// createResource.js (run in the browser or Node)
export function createResource(asyncFn) {
  const cache = new Map();
  return (...args) => {
    const key = JSON.stringify(args);
    if (cache.has(key)) return cache.get(key);
    const promise = asyncFn(...args).then(data => {
      cache.set(key, data);
      return data;
    });
    cache.set(key, promise);
    throw promise; // Suspense will catch this
  };
}

// App.jsx
import { Suspense } from "react";
import { createResource } from "./createResource";

const fetchPost = createResource(id => fetch(`/api/posts/${id}`).then(r => r.json()));

function Post({ id }) {
  const post = fetchPost(id); // may throw a promise
  return <<div><h1>{post.title}</h1><p>{post.body}</p></div>;
}

function Spinner() { return <div>Loading…</div>; }

export default function App() {
  return (
    <Suspense fallback={<Spinner />}>
      <Post id={1} />
    </Suspense>
  );
}

When Post calls fetchPost, the promise is thrown. The nearest <Suspense> boundary catches it, renders <Spinner />, and once the data arrives the component re‑renders with the real content.

Using a Library: React Query + Suspense

React Query already implements the promise‑throwing pattern. Enable it with the suspense option:

import { useQuery } from "react-query";

function Post({ id }) {
  const { data } = useQuery(["post", id], () => fetchPost(id), {
    suspense: true,
  });
  return <<div><h1>{data.title}</h1><p>{data.body}</p></div>;
}

Trade‑offs and Limitations

• Experimental API: The Suspense data‑fetching API is still flagged experimental in React 18. Lock your project to a specific 18.x release and monitor changelogs.
• Error Handling: A rejected promise will bubble up to the nearest ErrorBoundary. Without one, the entire tree crashes.
• SSR Coordination: In server‑side rendering, the server may pre‑fetch data, but the client can end up refetching unless you share a cache. Use a shared cache strategy (e.g., react-query’s dehydrate / hydrate) to avoid double requests.
• Concurrent Mode Dependency: Suspense relies on the concurrent rendering engine. Mixing it with legacy DOM manipulation can cause unexpected behavior.

Practical Checklist Before Production

1. Pin React to a stable 18.x version (e.g., 18.3.0).
2. Wrap the root of your app in an <ErrorBoundary> to catch data‑fetch errors.
3. If SSR is used, implement a shared cache (React Query’s dehydrate / hydrate or a custom LRU cache).
4. Test the fallback UI manually: toggle network throttling to see the spinner appear.
5. Monitor for double‑fetching: open the network tab on first load and confirm the client does not request data already provided by the server.
6. Keep an eye on React’s release notes for changes to the Suspense data‑fetching API.

Actionable Takeaway

Suspense lets you write cleaner, more declarative data‑fetching components. By throwing promises and relying on a <Suspense> boundary, you can eliminate manual loading flags, centralize error handling, and create a smoother user experience. Just remember the experimental status, enforce error boundaries, and coordinate SSR caching to avoid pitfalls.