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
⚡ Common Errors
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
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.
Add a Suspense Boundary Above the Lazy Component
Most common error — missing Suspense wrapperEvery 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.
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>
)
}Ensure the Lazy Import Uses a Default Export
React.lazy requires default export — named exports fail// ❌ 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 }))
)Fix React.lazy in Next.js — Use next/dynamic
Dynamic require not supported / SSR errorsIn Next.js, prefer next/dynamic over React.lazy . It handles SSR, loading states, and works with both App and Pages Router.
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>
)
}Add an Error Boundary for Lazy Load Failures
Network errors or chunk failures crashing the whole page"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>
)
}Preload Lazy Components on Hover/Intent
Reduce perceived load time — start fetching before clickTrigger the dynamic import early — on link hover or button mouseenter — so the chunk is already loading when the user actually clicks.
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
- Always wrap lazy components in a Suspense boundary with a fallback prop
- Ensure every lazy-imported component has a default export
- In Next.js, use next/dynamic instead of React.lazy — it handles SSR automatically
- Wrap Suspense in an Error Boundary to handle chunk load failures gracefully
- Use ssr: false in next/dynamic for any component that uses window, document, or browser APIs
- Preload chunks on hover with import('./Component') to reduce perceived latency
Frequently Asked Questions
Why does React lazy throw 'A React component suspended while rendering'?+−
Can React.lazy be used in Next.js App Router?+−
Why does React.lazy only work with default exports?+−
What is the difference between React.lazy and next/dynamic?+−
How do I handle errors when a lazy component fails to load?+−
Can I preload a lazy component before the user navigates to it?+−
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