React.lazy: Load Components On Demand

Why it exists

By default, modern JavaScript bundlers often create a single, large bundle file containing all your application's code. This means users download code for features they might never use, slowing down the initial page load. React.lazy was created to solve this by enabling code-splitting at the component level.

The mental model

Think of React.lazy as on-demand loading for your UI components. Instead of importing everything upfront, you create a placeholder. When React attempts to render this placeholder for the first time, it triggers a background download for the actual component's code, rendering it only when it arrives.

How it works

You declare a lazy component by calling lazy() with a function that itself calls a dynamic import(). This import() function returns a Promise. When the lazy component is first rendered, React "suspends" that part of the UI tree. You must wrap the lazy component in a <Suspense> boundary and provide a fallback prop, which is a temporary UI (like a spinner) to show during the download. Once the Promise resolves, React renders the component from the module's default export. React caches the result, so the code is only fetched once.

When to use it

Use React.lazy for components that are not critical for the initial render. Good candidates include: modals and popups, complex charts or data visualizations, admin-only sections of an app, or any content that is "below the fold" and not immediately visible to the user. This strategy significantly improves initial load performance.

When not to use it

Avoid using React.lazy for small, simple components where the overhead of a network request might be slower than just including it in the main bundle. Do not use it for components that are always visible on the initial page load, like a site header or main navigation, as this would only delay their appearance unnecessarily.

One canonical example

A common use case is loading a heavy markdown editor that isn't needed immediately. Instead of a static import MarkdownEditor from './MarkdownEditor';, you declare it lazily: const MarkdownEditor = lazy(() => import('./MarkdownEditor'));. Then, in your component, you wrap it with Suspense: <Suspense fallback={Loading editor...}><MarkdownEditor /></Suspense>. The user sees 'Loading editor...' until the editor's code is fetched and ready to render.