Code Splitting in React with lazy() and Suspense

Code splitting in React breaks a large JavaScript bundle into smaller chunks that load only when they are needed. The lazy and Suspense pair is how you split a component's code so it downloads on first render instead of with the initial page.

Why split the bundle

A growing app ships as one large JavaScript file by default. Users wait for all of it before the first paint, even for screens they never open.

Code splitting lets a feature's code arrive later, when the user actually reaches it. Heavy features such as a chart editor or a markdown preview are the best candidates.

A markdown preview can pull in a full parser, adding tens of kilobytes that readers do not need when the preview is hidden. Splitting it removes that weight from the initial download.

Defer a component with lazy

The lazy function wraps a dynamic import so the component loads on demand. It relies on your bundler's support for dynamic import(), which Vite, webpack, and most current tools provide.

The dynamic import returns a promise, and the bundler turns the requested module into a separate chunk file. lazy resolves the promise's default property as the component to render.

App.jsx

import { lazy } from "react";
 
const MarkdownPreview = lazy(() => import("./MarkdownPreview.js"));

The imported module must have a default export. Call lazy at module top level, outside your components. Declaring it inside a component re-creates it on every render, which resets the component's state.

Show a fallback with Suspense

While the chunk downloads, React suspends the component. Wrap it in Suspense and supply a fallback.

App.jsx

import { lazy, Suspense } from "react";
 
const MarkdownPreview = lazy(() => import("./MarkdownPreview.js"));
 
export default function Preview({ markdown }) {
  return (
    <Suspense fallback={<p>Loading preview...</p>}>
      <MarkdownPreview markdown={markdown} />
    </Suspense>
  );
}

The first time Preview renders, React requests the MarkdownPreview chunk and shows the fallback paragraph. When the chunk resolves, the fallback is replaced by the real preview. Later renders reuse the cached component, so the fallback never appears again.

Keep the fallback small so it appears instantly. A spinner or a skeleton works better than a full loading page, because the fallback is the only thing on screen while the chunk downloads.

The diagram shows the one-time path of a lazy component. The request happens only on the first render, which is why the fallback appears once and then never again.

Where to place boundaries

Put a Suspense boundary around a whole section, not around every component. Boundaries define your loading sequence, so they should match the granularity the user actually sees. A page-level boundary shows one spinner, while nested boundaries reveal sections progressively.

A common pattern is to render the lazy component only after the user enables it, such as ticking a Show preview checkbox. The first tick triggers the download, and later ticks reuse the cached chunk.

Do not use a Suspense boundary for data fetched in an Effect or event handler. Suspense only activates for lazy code, a Promise read with use, or a Suspense-enabled framework's data source.

What lazy requires

• A default export in the lazy module.
• A module-top-level declaration.
• A bundler that supports dynamic import().
• In a framework with Server Components, lazy applies to Client Components, while the framework splits Server Components itself.

Keep navigation smooth with transitions

A lazy component that suspends during navigation can flash its fallback over already visible content. Marking the navigation update as a transition keeps the current page on screen while the new chunk loads.

See useTransition for that pattern, and React Compiler for the build-time optimizations that pair with code splitting. Confirm the bundle was worth splitting with the measure-first workflow.