ReactCode SplittingError Fix2026 Updated

React lazy and Suspense Not Working— Fixed [Complete Guide 2026]

Also covers: missing Suspense boundary · default export requirement · Next.js next/dynamic · Error Boundary · preloading

January 20266 min readReact 18/19 · Next.js · TypeScript

⚡ Common Errors

Error
Error: A React component suspended while rendering, but no fallback UI was specified.
// OR:
Error: React.lazy requires a default export.
// OR (Next.js):
Error: Dynamic require of "..." is not supported

✅ Correct pattern

React lazy + Suspense — correct structure
import { lazy, Suspense } from "react"

const HeavyChart = lazy(() => import("./HeavyChart"))  // must default export

function Dashboard() {
  return (
    <Suspense fallback={<div>Loading chart...</div>}>  {/* ← required */}
      <HeavyChart />
    </Suspense>
  )
}

Why React lazy and Suspense Fail

React.lazy is a code-splitting API that defers loading a component's JavaScript bundle until it is first rendered. It works in two parts: React.lazy() wraps the dynamic import, and <Suspense> provides the loading fallback. Both parts are required — missing either one throws an error.

1

Add a Suspense Boundary Above the Lazy Component

Most common error — missing Suspense wrapper
2 min

Every React.lazy component must have at least one <Suspense> ancestor. The boundary can be anywhere above the lazy component in the tree — the nearest one is used.

Correct Suspense placement
import { lazy, Suspense } from "react"

// ✅ Lazy components
const Modal = lazy(() => import("./Modal"))
const Chart = lazy(() => import("./Chart"))
const DataTable = lazy(() => import("./DataTable"))

// ✅ One Suspense boundary can cover multiple lazy components
function App() {
  return (
    <Suspense fallback={<div className="p-8 text-center">Loading...</div>}>
      {/* All lazy components covered by this single boundary */}
      <Modal />
      <Chart />
      <DataTable />
    </Suspense>
  )
}

// ✅ Or granular boundaries per component
function Dashboard() {
  return (
    <div>
      <Suspense fallback={<ChartSkeleton />}>
        <Chart />
      </Suspense>
      <Suspense fallback={<TableSkeleton />}>
        <DataTable />
      </Suspense>
    </div>
  )
}
2

Ensure the Lazy Import Uses a Default Export

React.lazy requires default export — named exports fail
2 min
Default export requirement
// ❌ Named export — lazy will throw
// HeavyChart.tsx:
export function HeavyChart() { return <canvas /> }

// ❌ This fails:
const HeavyChart = lazy(() => import("./HeavyChart"))  // no default export

// ✅ Option A — add default export to the component file
// HeavyChart.tsx:
export function HeavyChart() { return <canvas /> }
export default HeavyChart  // add this

// ✅ Option B — create a wrapper re-export
// HeavyChart.lazy.ts:
export { HeavyChart as default } from "./HeavyChart"
const LazyChart = lazy(() => import("./HeavyChart.lazy"))

// ✅ Option C — use a dynamic import with destructuring inside lazy
const HeavyChart = lazy(() =>
  import("./HeavyChart").then(m => ({ default: m.HeavyChart }))
)
3

Fix React.lazy in Next.js — Use next/dynamic

Dynamic require not supported / SSR errors
3 min

In Next.js, prefer next/dynamic over React.lazy . It handles SSR, loading states, and works with both App and Pages Router.

next/dynamic — the Next.js way
import dynamic from "next/dynamic"

// ✅ Basic dynamic import with loading state
const HeavyChart = dynamic(() => import("@/components/HeavyChart"), {
  loading: () => <div>Loading chart...</div>,
})

// ✅ Disable SSR for browser-only components
const MapComponent = dynamic(() => import("@/components/Map"), {
  ssr: false,          // won't render on server — avoids window/document errors
  loading: () => <div>Loading map...</div>,
})

// ✅ Named export — use .then() to select it
const LineChart = dynamic(
  () => import("recharts").then(m => m.LineChart),
  { ssr: false }
)

// Usage — no Suspense needed (next/dynamic handles it internally)
export default function Dashboard() {
  return (
    <div>
      <HeavyChart data={data} />
      <MapComponent center={coords} />
    </div>
  )
}
4

Add an Error Boundary for Lazy Load Failures

Network errors or chunk failures crashing the whole page
5 min
Error boundary wrapping lazy + Suspense
"use client"

import { Component, type ErrorInfo, type ReactNode } from "react"

class LazyErrorBoundary extends Component<
  { children: ReactNode; fallback?: ReactNode },
  { hasError: boolean }
> {
  constructor(props: any) {
    super(props)
    this.state = { hasError: false }
  }

  static getDerivedStateFromError() {
    return { hasError: true }
  }

  componentDidCatch(error: Error, info: ErrorInfo) {
    console.error("Lazy load failed:", error, info)
  }

  render() {
    if (this.state.hasError) {
      return this.props.fallback ?? (
        <div className="p-6 text-center border rounded-xl">
          <p className="text-gray-600 mb-3">Failed to load. Please try again.</p>
          <button onClick={() => this.setState({ hasError: false })} className="text-indigo-600 underline">
            Retry
          </button>
        </div>
      )
    }
    return this.props.children
  }
}

// Usage
function App() {
  return (
    <LazyErrorBoundary>
      <Suspense fallback={<div>Loading...</div>}>
        <HeavyChart />
      </Suspense>
    </LazyErrorBoundary>
  )
}
5

Preload Lazy Components on Hover/Intent

Reduce perceived load time — start fetching before click
3 min

Trigger the dynamic import early — on link hover or button mouseenter — so the chunk is already loading when the user actually clicks.

Preload on hover
import { lazy, Suspense } from "react"

// Define the lazy component
const HeavyModal = lazy(() => import("./HeavyModal"))

// Preload function — triggers import without rendering
function preloadHeavyModal() {
  import("./HeavyModal")  // starts fetching the chunk
}

function Dashboard() {
  const [showModal, setShowModal] = useState(false)

  return (
    <div>
      {/* Start loading on hover — chunk ready by the time user clicks */}
      <button
        onMouseEnter={preloadHeavyModal}
        onClick={() => setShowModal(true)}
      >
        Open Heavy Modal
      </button>

      {showModal && (
        <Suspense fallback={<div>Loading...</div>}>
          <HeavyModal onClose={() => setShowModal(false)} />
        </Suspense>
      )}
    </div>
  )
}

Prevention

Frequently Asked Questions

Why does React lazy throw 'A React component suspended while rendering'?+
This error means a lazy component suspended but there was no Suspense boundary above it in the component tree. Every React.lazy component must have a parent Suspense component with a fallback prop. Without it, React does not know what to show while loading and throws an error.
Can React.lazy be used in Next.js App Router?+
React.lazy works in Next.js Client Components. However, the recommended approach in Next.js is next/dynamic, which integrates better with SSR and adds support for server-side loading states. Use dynamic(() => import('./Component'), { ssr: false }) for components that use browser-only APIs.
Why does React.lazy only work with default exports?+
React.lazy requires the dynamically imported module to have a default export that is a React component. Named exports are not supported directly. If you need a named export, create a wrapper module that re-exports it as default, or use a dynamic import with destructuring inside the lazy factory.
What is the difference between React.lazy and next/dynamic?+
React.lazy is a core React API for code splitting with client-side dynamic imports. next/dynamic is Next.js's wrapper that adds SSR support, server-side loading states, and better integration with the Next.js bundler. In a Next.js app, prefer next/dynamic over React.lazy.
How do I handle errors when a lazy component fails to load?+
Wrap your Suspense boundary with an Error Boundary component. When a lazy component's chunk fails to load (network error, deployment update), the error boundary catches the error and shows a fallback UI with a reload option.
Can I preload a lazy component before the user navigates to it?+
Yes — call the lazy factory function directly to trigger the import without rendering the component. For example, on link hover: const lazyLoad = React.lazy(() => import('./HeavyPage')); then call import('./HeavyPage') on hover to start loading the chunk early.

Need Expert Help?

We Build Fast React Applications with Code Splitting

Softplix engineers architect React apps with lazy loading, Suspense, and optimal bundle strategies. Let us help.

Talk to an Engineer