Next.js Dynamic Imports & Lazy Loading: The Complete Guide (2026)

Exit fullscreen mode

ssr: false — Client-Only Components

Some components can't render on the server at all: they use window, document, browser APIs, or libraries that aren't SSR-compatible.

Without ssr: false, these cause hydration errors or server-side exceptions. With it, Next.js skips server rendering entirely and renders only on the client:

// ❌ Breaks on the server — window is not defined
import { Map } from '@/components/map'

// ✅ Server renders nothing, client loads and renders normally
const Map = dynamic(() => import('@/components/map'), {
  ssr: false,
  loading: () => <div className="h-64 bg-muted rounded-lg" />,
})

Enter fullscreen mode Exit fullscreen mode

Common use cases for ssr: false:

// Rich text editor
const RichTextEditor = dynamic(() => import('@/components/rich-text-editor'), {
  ssr: false,
  loading: () => <div className="h-48 animate-pulse bg-muted rounded-lg" />,
})

// Interactive map
const InteractiveMap = dynamic(() => import('@/components/map'), {
  ssr: false,
  loading: () => <div className="h-96 bg-muted rounded-lg" />,
})

// QR code generator (uses Canvas API)
const QRGenerator = dynamic(() => import('@/components/qr-generator'), {
  ssr: false,
})

Enter fullscreen mode Exit fullscreen mode

Note: When you use ssr: false, the component is excluded from the server-rendered HTML entirely. The loading placeholder is what users with slow connections or JS disabled will see. Make sure it communicates something meaningful, not just a blank space.

Dynamic Imports with Named Exports

import() returns the default export. For named exports, map them in the promise:

// Named export: export function BarChart() { ... }
const BarChart = dynamic(
  () => import('@/components/charts').then((mod) => mod.BarChart),
  { loading: () => <ChartSkeleton /> }
)

// Or use a re-export file
// lib/dynamic-charts.ts
export const DynamicBarChart = dynamic(
  () => import('@/components/charts').then((mod) => mod.BarChart),
  { ssr: false }
)

Enter fullscreen mode Exit fullscreen mode

next/dynamic vs React.lazy

Both lazy-load components, but they're different tools:

next/dynamic

React.lazy

SSR control

ssr: false option

No SSR support

Loading state

loading prop

Requires <Suspense>

Works in Server Components

No (use in Client Components)

No

Named exports

.then((mod) => mod.Export)

Same pattern

Next.js integration

Yes — chunk naming, preloading

Partial

In the Next.js App Router, both work in Client Components. next/dynamic is more ergonomic for Next.js-specific patterns (especially ssr: false). React.lazy is fine for pure React component lazy loading where you don't need SSR control.

// React.lazy — fine for App Router Client Components
'use client'

import { lazy, Suspense } from 'react'

const HeavyComponent = lazy(() => import('@/components/heavy-component'))

export function Section() {
  return (
    <Suspense fallback={<div className="h-32 animate-pulse bg-muted rounded" />}>
      <HeavyComponent />
    </Suspense>
  )
}

Enter fullscreen mode Exit fullscreen mode

Conditional Loading: Load Only When Needed

The biggest win is loading components only when the user actually needs them:

'use client'

import { useState } from 'react'
import dynamic from 'next/dynamic'

const PDFViewer = dynamic(() => import('@/components/pdf-viewer'), {
  ssr: false,
  loading: () => <div className="h-96 animate-pulse bg-muted rounded" />,
})

export function DocumentCard({ url }: { url: string }) {
  const [showPreview, setShowPreview] = useState(false)

  return (
    <div>
      <button onClick={() => setShowPreview(true)}>
        Preview document
      </button>

      {/* PDFViewer chunk only downloads when the user clicks */}
      {showPreview && <PDFViewer url={url} />}
    </div>
  )
}

Enter fullscreen mode Exit fullscreen mode

The PDF viewer library — often 500KB+ — doesn't download until the user explicitly requests a preview.

Dynamic Imports for Heavy Libraries

When the heavy thing is a library rather than a component, use the dynamic import() function directly:

'use client'

import { useState } from 'react'

export function ExportButton({ data }: { data: unknown[] }) {
  const [isExporting, setIsExporting] = useState(false)

  async function handleExport() {
    setIsExporting(true)

    // xlsx only loads when the user clicks Export
    const { utils, writeFile } = await import('xlsx')

    const ws = utils.json_to_sheet(data)
    const wb = utils.book_new()
    utils.book_append_sheet(wb, ws, 'Data')
    writeFile(wb, 'export.xlsx')

    setIsExporting(false)
  }

  return (
    <button onClick={handleExport} disabled={isExporting}>
      {isExporting ? 'Exporting...' : 'Export to Excel'}
    </button>
  )
}

Enter fullscreen mode Exit fullscreen mode

Preloading: Anticipate Before the User Clicks

If you know the user is likely to trigger a dynamic import (hovering over a button, scrolling near a component), preload the chunk early:

import dynamic from 'next/dynamic'

const EditModal = dynamic(() => import('@/components/edit-modal'))

// Preload the chunk when the user hovers
function EditButton() {
  return (
    <button
      onMouseEnter={() => {
        // Starts fetching the chunk — by the time they click, it's ready
        import('@/components/edit-modal')
      }}
      onClick={() => setModalOpen(true)}
    >
      Edit
    </button>
  )
}

Enter fullscreen mode Exit fullscreen mode

This pattern eliminates the loading flash for fast users: the chunk starts downloading on hover and is usually ready by the time they click.

What to Dynamically Import (and What Not To)

Good candidates for dynamic imports:

• Heavy third-party libraries used conditionally (chart libraries, editors, PDF viewers)
• Components behind user interaction (modals, drawers, expanded sections)
• Components at the bottom of long pages (below the fold)
• Admin/settings pages that regular users rarely visit
• Anything with window or document access

Bad candidates for dynamic imports:

• Core UI components used everywhere (buttons, inputs, layout)
• Components needed for initial render (hero sections, navigation)
• Small utilities where the dynamic import overhead outweighs the savings
• Components used immediately on every page load

The test: if the user can complete their primary action on the page without ever rendering the component, it's a candidate for lazy loading.

Measuring the Impact

Bundle analyzer — see what's in your bundles before and after:

npm install --save-dev @next/bundle-analyzer

Enter fullscreen mode Exit fullscreen mode

// next.config.ts
import withBundleAnalyzer from '@next/bundle-analyzer'

const config = withBundleAnalyzer({
  enabled: process.env.ANALYZE === 'true',
})

export default config

Enter fullscreen mode Exit fullscreen mode

ANALYZE=true npm run build

Enter fullscreen mode Exit fullscreen mode

Open the visualization and look for large modules in your initial bundle that could be deferred.

Quick Reference

// Basic dynamic import with loading state
const Component = dynamic(() => import('./component'), {
  loading: () => <Skeleton />,
})

// Client-only component
const BrowserComponent = dynamic(() => import('./browser-component'), {
  ssr: false,
  loading: () => <Placeholder />,
})

// Named export
const NamedExport = dynamic(
  () => import('./module').then((m) => m.NamedExport)
)

// Conditional render (most impactful pattern)
{isOpen && <DynamicModal />}

// Preload on hover
onMouseEnter={() => import('./component')}

// Dynamic library import in a function
const { default: heavyLib } = await import('heavy-lib')

Enter fullscreen mode Exit fullscreen mode

The principle is the same throughout: defer downloading JavaScript until it's actually needed. The browser does less work on initial load, the user gets an interactive page sooner, and the code that most users never see doesn't cost them anything.

---

Full article at stacknotice.com/blog/nextjs-dynamic-imports-lazy-loading-2026