20/02/2025, 09:19 lazy – React
v19
API REFERENCE APIS
lazy
lazy lets you defer loading component’s code until it is rendered
for the first time.
const SomeComponent = lazy(load)
Reference
lazy(load)
load function
Usage
Lazy-loading components with Suspense
Troubleshooting
My lazy component’s state gets reset unexpectedly
Reference
lazy(load)
Call lazy outside your components to declare a lazy-loaded React
component:
import { lazy } from 'react';
const MarkdownPreview = lazy(() => import('./MarkdownPreview.js'));
https://react.dev/reference/react/lazy 1/6
20/02/2025, 09:19 lazy – React
See more examples below.
Parameters
load : A function that returns a Promise or another thenable (a Promise-
like object with a then method). React will not call load until the first
time you attempt to render the returned component. After React first
calls load , 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 call load
more than once. If the Promise rejects, React will throw 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 will suspend.
Use <Suspense> to display a loading indicator while it’s loading.
load function
Parameters
load receives no parameters.
Returns
You need to return a Promise or some other thenable (a Promise-like object
with a then method). It needs to eventually resolve to an object whose
.default property is a valid React component type, such as a function,
memo , or a forwardRef component.
Usage
Lazy-loading components with Suspense
https://react.dev/reference/react/lazy 2/6
20/02/2025, 09:19 lazy – React
Usually, you import components with the static import declaration:
import MarkdownPreview from './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';
const MarkdownPreview = lazy(() => import('./MarkdownPreview.js'));
This code relies on dynamic import() , which might require support from
your bundler or framework. Using this pattern requires that the lazy
component you’re importing was exported as the default 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:
<Suspense fallback={<Loading />}>
<h2>Preview</h2>
<MarkdownPreview />
</Suspense>
In this example, the code for MarkdownPreview won’t be loaded until you
attempt to render it. If MarkdownPreview hasn’t loaded yet, Loading will be
shown in its place. Try ticking the checkbox:
App.js Loading.js MarkdownPreview.js Reset
import { useState, Suspense, lazy } from 'react';
import Loading from './Loading.js';
https://react.dev/reference/react/lazy 3/6
20/02/2025, 09:19 lazy – React
const MarkdownPreview = lazy(() => delayForDemo(import('./MarkdownPre
export default function MarkdownEditor() {
const [showPreview, setShowPreview] = useState(false);
const [markdown, setMarkdown] = useState('Hello, **world**!');
return (
<>
<textarea value={markdown} onChange={e => setMarkdown(e target
Show more
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
My lazy component’s state gets reset unexpectedly
https://react.dev/reference/react/lazy 4/6
20/02/2025, 09:19 lazy – React
Do not declare lazy components inside other components:
import { lazy } from 'react';
function Editor() {
// 🔴 Bad: This will cause all state to be reset on re-renders
const MarkdownPreview = 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
const MarkdownPreview = lazy(() => import('./MarkdownPreview.js'));
function Editor() {
// ...
}
PREVIOUS
createContext
NEXT
memo
Copyright © Meta Platforms, Inc
https://react.dev/reference/react/lazy 5/6
20/02/2025, 09:19 lazy – React
uwu?
Learn React API Reference
Quick Start React APIs
Installation React DOM APIs
Describing the UI
Adding Interactivity
Managing State
Escape Hatches
Community More
Code of Conduct Blog
Meet the Team React Native
Docs Contributors Privacy
Acknowledgements Terms
https://react.dev/reference/react/lazy 6/6
