Reduce initial JavaScript
A large widget is not needed immediately on the first view.
Next.js 16+ · Module
next/dynamic
next/dynamic lazy-loads Client Components and libraries so they can be omitted from the initial JavaScript bundle. It combines dynamic imports with React lazy loading and Suspense, with options for fallback UI and client-only rendering.
How it works
Import dynamic from next/dynamic and call it at module scope with a loader that performs a literal dynamic import. Next.js splits the component from the initial JavaScript and can show a loading component while the import resolves; set ssr: false when the component must only run in the browser.
Syntax
dynamic(() => import('./Component'), { loading: () => <p>Loading...</p>, ssr: false })Parameters
| Name | Type | Description |
|---|---|---|
loader | () => import(path) | A function returning a dynamic import() of the component module; the import path must be explicit and the import must be inside dynamic(). |
options | { loading?: () => ReactNode; ssr?: boolean } | Optional configuration including loading for fallback UI and ssr: false to disable server rendering. |
Returns
A React component that loads the imported component dynamically.
Key points
- The same dynamic-import pattern works in both routing systems, which supports gradual migration.
- A dynamically imported component can be excluded from the initial route bundle.
- Fallback content appears before the loaded component becomes available.
- Lazy loading can defer Client Components and libraries until they are needed.
Common mistakes
- Use a literal import path rather than a template string or variable so Next.js can identify the module and preload it.
- Declare dynamic components at module scope; creating them during render prevents the intended preloading behavior.
- Use
ssr: falsefor browser-only dependencies, such as code that requireswindow.
Example: Client-only dynamic component
import dynamic from 'next/dynamic'
const ClientOnlyChart = dynamic(() => import('./ClientOnlyChart'), {
ssr: false,
loading: () => <p>Loading chart...</p>,
})
export default function Dashboard() {
return <ClientOnlyChart />
}Loads the chart as a separate client-side component and displays fallback content while it loads.
When to use it
Load browser-only code
A component depends on browser globals such as window.
Provide deferred UI feedback
A component should appear behind a loading state while its chunk resolves.
Interview questions
QWhat problem does next/dynamic solve?
next/dynamic combines the behavior of React.lazy() and Suspense. It lets Next.js defer a component's JavaScript so that component is not part of the route's initial bundle.
Follow-up: How would you avoid server-rendering a browser-dependent component? Set ssr: false in the options passed to dynamic.
QWhat constraints apply to the dynamic import?
The loader should be an inline dynamic import with an explicit path, for example dynamic(() => import('./Widget')). Keeping that import inside the call lets Next.js associate the module with the dynamic component and preload it.
Follow-up: Why must the component declaration be outside render? Next.js needs a stable module-level declaration to perform preloading, similarly to React.lazy.
QHow can a dynamic component show loading UI and become client-only?
The loading option supplies fallback UI while the dynamically imported component is being resolved. Without it, the component still loads dynamically, but this API call does not provide custom loading content.
Follow-up: What happens when ssr: false is used? The component is skipped during server rendering and loaded in the browser instead.
Related
React.lazy()SuspenseClient ComponentsDynamic Importsloadingssr