Data Fetching with React Suspense

React Suspense simplifies async data handling. Here's how to use it for data fetching.

Basic Suspense#

import { Suspense } from 'react';

// Suspense catches loading state
function App() {
  return (
    <Suspense fallback={<Loading />}>
      <UserProfile userId="1" />
    </Suspense>
  );
}

function Loading() {
  return <div className="spinner">Loading...</div>;
}

// The component that fetches data
function UserProfile({ userId }: { userId: string }) {
  const user = use(fetchUser(userId));

  return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.email}</p>
    </div>
  );
}

The use Hook (React 19+)#

import { use } from 'react';

// use() unwraps promises during render
function UserProfile({ userId }: { userId: string }) {
  const user = use(fetchUser(userId));

  return <div>{user.name}</div>;
}

// Can be called conditionally (unlike hooks)
function ConditionalData({ shouldFetch }: { shouldFetch: boolean }) {
  if (!shouldFetch) {
    return <div>No data</div>;
  }

  const data = use(fetchData());
  return <div>{data.value}</div>;
}

// Works with Context too
function ThemedComponent() {
  const theme = use(ThemeContext);
  return <div style={{ color: theme.primary }}>Themed</div>;
}

Resource Pattern#

// Create a resource (cache for promise)
function createResource<T>(promise: Promise<T>) {
  let status: 'pending' | 'success' | 'error' = 'pending';
  let result: T;
  let error: Error;

  const suspender = promise.then(
    (data) => {
      status = 'success';
      result = data;
    },
    (err) => {
      status = 'error';
      error = err;
    }
  );

  return {
    read(): T {
      switch (status) {
        case 'pending':
          throw suspender;  // Suspense catches this
        case 'error':
          throw error;      // Error boundary catches this
        case 'success':
          return result;
      }
    },
  };
}

// Usage
const userResource = createResource(fetchUser('1'));

function UserProfile() {
  const user = userResource.read();  // Suspends if pending
  return <div>{user.name}</div>;
}

function App() {
  return (
    <ErrorBoundary fallback={<Error />}>
      <Suspense fallback={<Loading />}>
        <UserProfile />
      </Suspense>
    </ErrorBoundary>
  );
}

Error Boundaries#

import { Component, ReactNode } from 'react';

interface Props {
  children: ReactNode;
  fallback: ReactNode | ((error: Error, reset: () => void) => ReactNode);
}

interface State {
  hasError: boolean;
  error: Error | null;
}

class ErrorBoundary extends Component<Props, State> {
  state: State = { hasError: false, error: null };

  static getDerivedStateFromError(error: Error): State {
    return { hasError: true, error };
  }

  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
    console.error('Error caught:', error, errorInfo);
  }

  reset = () => {
    this.setState({ hasError: false, error: null });
  };

  render() {
    if (this.state.hasError) {
      if (typeof this.props.fallback === 'function') {
        return this.props.fallback(this.state.error!, this.reset);
      }
      return this.props.fallback;
    }

    return this.props.children;
  }
}

// Usage with reset
function App() {
  return (
    <ErrorBoundary
      fallback={(error, reset) => (
        <div>
          <p>Error: {error.message}</p>
          <button onClick={reset}>Try Again</button>
        </div>
      )}
    >
      <Suspense fallback={<Loading />}>
        <DataComponent />
      </Suspense>
    </ErrorBoundary>
  );
}

Nested Suspense#

// Multiple suspense boundaries for granular loading
function Dashboard() {
  return (
    <div className="dashboard">
      <Suspense fallback={<HeaderSkeleton />}>
        <Header />
      </Suspense>

      <div className="content">
        <Suspense fallback={<SidebarSkeleton />}>
          <Sidebar />
        </Suspense>

        <Suspense fallback={<MainSkeleton />}>
          <MainContent />
        </Suspense>
      </div>
    </div>
  );
}

// Each section loads independently
function Header() {
  const user = use(fetchCurrentUser());
  return <header>Welcome, {user.name}</header>;
}

function Sidebar() {
  const nav = use(fetchNavigation());
  return <nav>{/* nav items */}</nav>;
}

function MainContent() {
  const data = use(fetchDashboardData());
  return <main>{/* dashboard content */}</main>;
}

Streaming with Suspense#

// Server Components with streaming
// app/page.tsx
import { Suspense } from 'react';

async function SlowComponent() {
  const data = await fetchSlowData(); // 3 seconds
  return <div>{data.value}</div>;
}

async function FastComponent() {
  const data = await fetchFastData(); // 100ms
  return <div>{data.value}</div>;
}

export default function Page() {
  return (
    <div>
      {/* Fast content streams first */}
      <Suspense fallback={<p>Loading fast...</p>}>
        <FastComponent />
      </Suspense>

      {/* Slow content streams when ready */}
      <Suspense fallback={<p>Loading slow...</p>}>
        <SlowComponent />
      </Suspense>
    </div>
  );
}

React Query with Suspense#

import { useSuspenseQuery, useSuspenseQueries } from '@tanstack/react-query';

function UserProfile({ userId }: { userId: string }) {
  const { data: user } = useSuspenseQuery({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
  });

  return <div>{user.name}</div>;
}

// Multiple queries
function UserWithPosts({ userId }: { userId: string }) {
  const [{ data: user }, { data: posts }] = useSuspenseQueries({
    queries: [
      {
        queryKey: ['user', userId],
        queryFn: () => fetchUser(userId),
      },
      {
        queryKey: ['posts', userId],
        queryFn: () => fetchUserPosts(userId),
      },
    ],
  });

  return (
    <div>
      <h1>{user.name}</h1>
      <ul>
        {posts.map((post) => (
          <li key={post.id}>{post.title}</li>
        ))}
      </ul>
    </div>
  );
}

// Wrap with Suspense
function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <Suspense fallback={<Loading />}>
        <UserProfile userId="1" />
      </Suspense>
    </QueryClientProvider>
  );
}

SWR with Suspense#

import useSWR from 'swr';

function UserProfile({ userId }: { userId: string }) {
  const { data: user } = useSWR(
    `/api/users/${userId}`,
    fetcher,
    { suspense: true }
  );

  return <div>{user.name}</div>;
}

// Global config
function App() {
  return (
    <SWRConfig value={{ suspense: true }}>
      <Suspense fallback={<Loading />}>
        <UserProfile userId="1" />
      </Suspense>
    </SWRConfig>
  );
}

Transitions#

import { useTransition, useState, Suspense } from 'react';

function TabContainer() {
  const [tab, setTab] = useState('home');
  const [isPending, startTransition] = useTransition();

  function selectTab(nextTab: string) {
    startTransition(() => {
      setTab(nextTab);
    });
  }

  return (
    <div>
      <nav>
        <button onClick={() => selectTab('home')}>Home</button>
        <button onClick={() => selectTab('posts')}>Posts</button>
        <button onClick={() => selectTab('settings')}>Settings</button>
      </nav>

      <div className={isPending ? 'opacity-50' : ''}>
        <Suspense fallback={<TabSkeleton />}>
          {tab === 'home' && <HomeTab />}
          {tab === 'posts' && <PostsTab />}
          {tab === 'settings' && <SettingsTab />}
        </Suspense>
      </div>
    </div>
  );
}

Preloading Data#

// Preload on hover
function UserLink({ userId }: { userId: string }) {
  const queryClient = useQueryClient();

  const prefetch = () => {
    queryClient.prefetchQuery({
      queryKey: ['user', userId],
      queryFn: () => fetchUser(userId),
    });
  };

  return (
    <Link
      href={`/users/${userId}`}
      onMouseEnter={prefetch}
      onFocus={prefetch}
    >
      View User
    </Link>
  );
}

// Preload before navigation
function Navigation() {
  const router = useRouter();

  const navigateToUser = async (userId: string) => {
    // Start fetching
    const userPromise = fetchUser(userId);

    // Navigate immediately
    router.push(`/users/${userId}`);

    // Data is ready when component renders
  };

  return (
    <button onClick={() => navigateToUser('1')}>
      Go to User
    </button>
  );
}

Best Practices#

Loading States:
✓ Use skeleton components
✓ Place Suspense boundaries strategically
✓ Show meaningful loading states
✓ Avoid layout shift

Error Handling:
✓ Wrap Suspense with ErrorBoundary
✓ Provide retry mechanisms
✓ Show helpful error messages
✓ Log errors for debugging

Performance:
✓ Preload data on hover
✓ Use transitions for tab changes
✓ Cache data appropriately
✓ Stream server components

React Suspense transforms async data handling with declarative loading states. Use the use hook for simple cases, React Query or SWR for advanced caching, and ErrorBoundary for error handling. Place Suspense boundaries strategically for optimal user experience.