How to use React.lazy

Edit this page on GitHubEdit this page on GitHub

React.lazy is here to help you code-split your app!

Available from the React 16.6.0 release, it might just be what you need to significantly reduce your bundle size.

What is a bundle

It is a common practice for JavaScript applications to assemble all files into a single one, usually called bundle. This bundle can then be served to the user to load the application.

So what?

As an application grows larger, so does its bundle size. For big applications, bundle sizes can get pretty large—significantly increasing loading times and worsening the user experience.

What is Code-splitting

Code-splitting is a technique used to delay the loading of non-critical resources in order to increase the performance of an app.

Show me what you got!

Without code-splitting

The code below is an example of a component that is not using lazy loading.

<MyComponent /> will be loaded together with the main bundle:

import React from 'react';
import MyComponent from './MyComponent';
const App = () => (
    <MyComponent /> // will be loaded with the main bundle  </div>

export default App;

With code-splitting

Code-splitting with React.lazy looks something like this:

import React, { lazy, Suspense } from 'react';
const MyComponent = lazy(() => import('./MyComponent'));
const App = () => (
    <Suspense fallback={'loading MyComponent'}>      <MyComponent /> // will be lazy loaded    </Suspense>  </div>

export default App;

You will notice that virtually only 2 things have changed:

  1. The import

    We use the lazy api in order to code split <MyComponent />. Its code will not be included in the main bundle and it will be automatically requested once the component is rendered.

  2. <Suspense /> component

    <Suspense /> is a new component also introduced on the 16.6.0 release. It basically "suspends" the rendering of a component until it is ready.

    In this case, it will display the fallback 'loading MyComponent' until it finishes fetching the bundle for <MyComponent />.


React.lazy and <Suspense /> are great tools to help you have easy performance gains.

It should be fairly easy to determine what is needed to be loaded as part of the main bundle and what can wait.

It is very common for apps to load a lot of code in the main bundle that is never ran. This can now be easily mitigated with React.lazy.

Make sure to check out the docs.