React Lazy Loading: Code Splitting, Suspense and the Right Way

Why Your Bundle Size Is Hurting You

Most React apps ship way too much JavaScript on the initial page load. You're sending down code for the settings page, the admin panel, the analytics dashboard — all before the user has even seen the homepage. That's a real problem, not a hypothetical one.

Honestly, the gap between a fast app and a sluggish one often isn't clever state management or memo tricks. It's just how much JavaScript the browser has to parse before it can do anything useful. Parse times on mid-range mobile devices in 2026 are still painful.

Code splitting solves this by breaking your bundle into smaller chunks that only load when needed. React gives you React.lazy() and Suspense to do this with almost zero boilerplate. Worth noting: this isn't a micro-optimisation — shaving 200–400kb off your initial JS payload is the kind of win that moves your Lighthouse score by 15+ points.

The question isn't whether you should do this. It's whether you're doing it in the right places.

React.lazy() — The Basics You Actually Need

The API is intentionally simple. React.lazy() takes a function that returns a dynamic import(), and React handles the rest. Pair it with <Suspense> and you've got route-level code splitting in about ten lines.

Here's the minimal working pattern:

``jsx import React, { lazy, Suspense } from 'react'; const Dashboard = lazy(() => import('./pages/Dashboard')); const Settings = lazy(() => import('./pages/Settings')); function App() { return ( <Suspense fallback={<div className="loading-spinner" />}> <Router> <Route path="/dashboard" element={<Dashboard />} /> <Route path="/settings" element={<Settings />} /> </Router> </Suspense> ); } ``

That fallback prop is doing real work. While the chunk downloads, React renders whatever you pass there. Keep it lightweight — a spinner, a skeleton, or even just null. A heavy fallback component defeats the point.

One more thing — React.lazy() only works with default exports. If your component uses named exports, you'll need a small wrapper: lazy(() => import('./MyModule').then(m => ({ default: m.MyComponent }))). Annoying? A bit. Deal-breaker? No.

Suspense Boundaries — Where to Put Them

Putting a single <Suspense> at the root of your app is fine to start, but you'll want to get more surgical as your app grows. The boundary placement determines what flashes and what doesn't.

Think of Suspense boundaries like error boundaries — they catch something (in this case, a loading state) and isolate the fallback to a specific part of the UI. If your sidebar and main content each have their own boundary, a slow chart component won't flash the entire page layout. That 200ms of stability matters a lot perceptually.

In practice, you want boundaries at route level minimum, and then individually around anything that loads asynchronously — heavy data viz components, rich text editors, map widgets. Anything that weighs more than ~50kb of JS on its own is a candidate.

Quick aside: nested Suspense boundaries work exactly how you'd expect. The inner boundary catches first. If it doesn't have a boundary, it bubbles up to the nearest parent. React 18's concurrent features actually made this more predictable — no more accidental waterfalls from bad boundary placement.

Code Splitting Beyond Routes

Route-level splitting is table stakes. The real gains come from component-level splitting — deferring things the user might never interact with.

Think about a modal that contains a rich text editor. Why are you loading a 180kb library on page load when the modal only opens if someone clicks "Edit"? Lazy-load the whole modal component. Load it on demand. The user won't notice the 100–200ms delay because they just clicked a button — there's already an expected pause.

Same logic applies to tabs. If you've got a four-tab UI, lazy-load tabs 2 through 4. Tab 1 loads instantly, and the others fetch as needed. You can even preload aggressively — start fetching tab 2's chunk when the user hovers over the tab. Webpack (and Vite in 2025+) support magic comments for this:

``jsx const HeavyChart = lazy(() => import(/* webpackPrefetch: true */ './components/HeavyChart') ); ``

The webpackPrefetch comment tells the browser to fetch that chunk in the background during idle time. By the time the user clicks, it's already cached. That's the kind of invisible performance that makes apps feel instant.

If you're building something component-heavy — like a UI toolkit or design system — this pattern is essential. Browse the components at Empire UI and you'll see this exact approach used for anything interactive that doesn't need to be in the critical path.

Error Handling with Error Boundaries

Suspense handles the loading state. But what happens when the chunk fails to load? Bad network, CDN blip, deploy mid-session — it happens. Without an error boundary, your users get a blank white screen with no explanation.

You need an error boundary wrapping your <Suspense>. React doesn't have a hook for this yet (yes, really — still class-only in 2026 unless you use a library), so you'll want something like react-error-boundary:

``jsx import { ErrorBoundary } from 'react-error-boundary'; function ChunkErrorFallback({ error, resetErrorBoundary }) { return ( <div role="alert" style={{ padding: '24px' }}> <p>Failed to load this section. Check your connection.</p> <button onClick={resetErrorBoundary}>Try again</button> </div> ); } <ErrorBoundary FallbackComponent={ChunkErrorFallback}> <Suspense fallback={<Spinner />}> <LazyComponent /> </Suspense> </ErrorBoundary> ``

That resetErrorBoundary call will re-attempt the import. Combined with a retry mechanism on the dynamic import itself, you've got a resilient loading flow that handles flaky networks gracefully.

Look, this is the step most tutorials skip. Don't skip it.

Measuring the Impact and Avoiding Over-Splitting

Before you go lazy-loading everything, measure first. Webpack Bundle Analyzer or Vite's built-in rollup-plugin-visualizer will show you exactly what's in each chunk and where the fat is. Fix the actual problem, not a theoretical one.

Over-splitting is a real issue. If you create 40 tiny chunks that each load in parallel, you're hammering the HTTP/2 multiplexing limit and adding overhead for each module evaluation. There's a sweet spot — usually chunks of at least 20–30kb after gzip, and not more than 10–15 on any given page.

One metric to track: your Time to Interactive (TTI) on a throttled 4G connection. If React.lazy() pushes that number down by more than 300ms, it was worth doing. If it doesn't move the needle, you split too aggressively or split the wrong things.

The gradient generator and other tools on Empire UI use this exact approach — only loading the heavy canvas and export logic when the user actually interacts with the tool, keeping the initial shell load under 80kb. It's not magic, it's just careful splitting.

Quick Wins Checklist

If you want a fast path to measurable improvement, here's the order of operations. Start with routes — those are the highest-impact, lowest-risk splits. Then audit any modal or drawer that imports something heavy. Then tackle tabs. That sequence alone handles 80% of the gains for most apps.

Audit your package.json too. Date pickers, rich text editors, charting libraries — these are the usual suspects eating your bundle. Lazy-load the components that wrap them and you're done. No need to rewrite anything.

Worth noting: Vite handles code splitting automatically when you use dynamic imports, and the chunk naming is predictable. With Webpack you might need to configure optimization.splitChunks — but the defaults in Webpack 5 are already pretty good for most setups.

If you're building anything visually complex — dashboards, design tools, interactive UI builders — check out Empire UI. The whole library is built with performance in mind, and the component patterns map well to what we've covered here. Same ideas, different scale.

FAQ

Read next