const Chart = lazy(() => import('./Chart.jsx')) declares a component whose code isn't loaded yet:
- Splitting. A dynamic
import()gives bundlers a split point:Chart.jsxand whatever only it imports go into a separate chunk, so the main bundle shrinks. (Where to split is a performance and tooling question.) - When it loads. Declaring does nothing. React calls the loader the first time it renders
<Chart />. Until the promise settles, rendering suspends and the nearest<Suspense>shows its fallback. - What it expects. The loader must return a promise or thenable resolving to an object whose
.defaultis a component: exactly whatimport()of a module with a default export gives you. For a named export, map it:import('./Chart.jsx').then((m) => ({ default: m.Chart })). - Caching. React caches both the promise and the result, so the loader runs at most once per
lazytype. Unmounting and remounting<Chart />renders the cached component synchronously. A rejected load goes to the nearest error boundary, and the rejection is cached too.
Declare it at the top level of a module. Each lazy() call creates a new component type with its own cache. Inside a component, every render makes a new type: React calls the loader again, the component suspends again, and its fallback replaces visible content on each re-render. The docs warn that state gets reset as well.
Two ways to avoid the loading state: render the lazy component during a Transition inside a boundary that's already showing content, so the old UI stays until the code arrives; or pre-render it hidden in <Activity>, which loads the code ahead of time.