lazy

constSomeComponent =lazy(load)

• Reference
  • lazy(load)
  • load function
• Usage
  • Lazy-loading components with Suspense
• Troubleshooting
  • Mylazy component’s state gets reset unexpectedly

Reference

lazy(load)

Calllazy outside your components to declare a lazy-loaded React component:

import{lazy}from'react';

constMarkdownPreview =lazy(()=>import('./MarkdownPreview.js'));

See more examples below.

Parameters

• load: A function that returns aPromise or anotherthenable (a Promise-like object with athen method). React will not callload until the first time you attempt to render the returned component. After React first callsload, it will wait for it to resolve, and then render the resolved value’s.default as a React component. Both the returned Promise and the Promise’s resolved value will be cached, so React will not callload more than once. If the Promise rejects, React willthrow the rejection reason for the nearest Error Boundary to handle.

Returns

lazy returns a React component you can render in your tree. While the code for the lazy component is still loading, attempting to render it willsuspend. Use<Suspense> to display a loading indicator while it’s loading.

load function

Parameters

load receives no parameters.

Returns

You need to return aPromise or some otherthenable (a Promise-like object with athen method). It needs to eventually resolve to an object whose.default property is a valid React component type, such as a function,memo, or aforwardRef component.

Usage

Lazy-loading components with Suspense

Usually, you import components with the staticimport declaration:

importMarkdownPreviewfrom'./MarkdownPreview.js';

To defer loading this component’s code until it’s rendered for the first time, replace this import with:

import{lazy}from'react';

constMarkdownPreview =lazy(()=>import('./MarkdownPreview.js'));

This code relies ondynamicimport(), which might require support from your bundler or framework. Using this pattern requires that the lazy component you’re importing was exported as thedefault export.

Now that your component’s code loads on demand, you also need to specify what should be displayed while it is loading. You can do this by wrapping the lazy component or any of its parents into a<Suspense> boundary:

<Suspensefallback={<Loading/>}>
<h2>Preview</h2>
<MarkdownPreview/>
</Suspense>

In this example, the code forMarkdownPreview won’t be loaded until you attempt to render it. IfMarkdownPreview hasn’t loaded yet,Loading will be shown in its place. Try ticking the checkbox:

This demo loads with an artificial delay. The next time you untick and tick the checkbox,Preview will be cached, so there will be no loading state. To see the loading state again, click “Reset” on the sandbox.

Learn more about managing loading states with Suspense.

Troubleshooting

Mylazy component’s state gets reset unexpectedly

Do not declarelazy componentsinside other components:

import{lazy}from'react';

functionEditor(){
// 🔴 Bad: This will cause all state to be reset on re-renders
constMarkdownPreview =lazy(()=>import('./MarkdownPreview.js'));
// ...
}

Instead, always declare them at the top level of your module:

import{lazy}from'react';

// ✅ Good: Declare lazy components outside of your components
constMarkdownPreview =lazy(()=>import('./MarkdownPreview.js'));

functionEditor(){
// ...
}