API · Code splitting
lazy
Import on demand
lazy() receives a function that returns a dynamic import, and produces a component that loads its code only when rendered for the first time. Combined with Suspense, it splits the bundle automatically.
Where it shines
Views not seen until the user navigates, heavy modals that few users open, rich editors, charts. Anything that inflates the initial bundle without justifying its cost for the first paint.
Suspense is mandatory
While the code downloads, the component suspends. You need a <Suspense fallback=...> above it or React throws an error.
Common pitfalls
- 01lazy() requires a Suspense boundary above it — without it, React throws.
- 02Don't declare lazy() inside a component — it recreates the lazy reference on every render, losing the cache.
- 03In SSR with Next.js use dynamic() instead of lazy() — it handles server-side behavior properly.
Was this helpful?
Sign in to give feedback