Guide · Open source
How to use react-loadable: lazy-load React components
Updated · written with AI from the project's own documentation and checked against our catalogue data
react-loadable is a small higher-order component for React that loads a component only when it is needed, using a loader built on dynamic import(). This guide shows what it does, how to install it, how to wrap a component and show a loading state, and when it is a good fit. After reading, you will be able to split a component out of your main bundle with react-loadable.
react-loadablejamiebuilds/react-loadable · ★ 16.5k · MIT Install options & downloads Quick start
- 1Install the package. Run yarn add react-loadable in your project. Make sure your bundler supports import(), such as Webpack 2+.
- 2Pick a component to split. Choose a component the user may not need straight away, such as a modal, a tab or a heavy widget.
- 3Write a loader. Create a loader that returns import() of that component's file.
- 4Add a loading component. Create a small component that renders while the code loads, and handle error and timeout states.
- 5Wrap and render. Call Loadable with loader and loading, then render the returned component where the original one was used.
- 6Check the result. Compare your bundle size and load time before and after the change to confirm the split helps.
What react-loadable does and when to use it
Code-splitting breaks one large JavaScript bundle into smaller bundles that contain separate parts of an app. The README says react-loadable is designed to make component-level splitting simple, so a component such as a modal, a tab, or a heavy widget is loaded only when it is rendered.
The library is built around React components and a bundler that supports import(), such as Webpack 2+. The README notes that with Webpack 2+ and import(), code is split automatically with no additional configuration.
- Good fit: large main bundles, Webpack apps, lazy-loading modals, tabs or heavy widgets, and server-side rendering with code splitting.
- Poor fit: non-React projects, projects without a bundler that supports import(), and teams needing a clearly maintained option (the README does not state a current maintenance status).
Install react-loadable
Install the package with Yarn. The README's install command is shown below. Prerequisites listed for this library are Node.js, Yarn or npm, React, and a bundler that supports import() such as Webpack 2+.
yarn add react-loadableWrap a component with Loadable
Import Loadable and call it with an object that has a loader and a loading component. The loader uses dynamic import() to fetch the component module. The loading component is shown while the code arrives. The result is a component you render like any other.
- loader: a function returning import('./my-component').
- loading: a component to render while the module loads.
import Loadable from 'react-loadable';
import Loading from './my-loading-component';
const LoadableComponent = Loadable({
loader: () => import('./my-component'),
loading: Loading,
});
export default class App extends React.Component {
render() {
return <LoadableComponent/>;
}
}Write a useful loading component
A static 'Loading...' message does not tell the user much. The README says to think about error states, timeouts, and making the loading experience pleasant. The loading component receives the loader's state, so it can handle a failed load as well as the pending state.
The README example below shows a loading component wired to a loader that is expected to fail, which is useful for testing your error handling.
function Loading() {
return <div>Loading...</div>;
}
Loadable({
loader: () => import('./WillFailToLoad'), // oh no!
loading: Loading,
});Choose what to split
The README argues for splitting by component rather than only by route. Modals, tabs and UI components that hide content until a user acts are good candidates. Content that is not needed at first paint, such as a map inside a tab, can be deferred.
Because introducing a split point is a matter of changing a few lines, you can switch a component to import() and Loadable, measure the result, and keep what performs best for your app.
- Example from the README: a map inside a tab component, which many users may never open.
- Also possible: deferring a component at the bottom of the page until higher-priority content has loaded.
What people use it for
- Lazy-loading a modal that most users never open.
- Deferring a map library that sits inside a tab component.
- Splitting a heavy widget out of the main bundle so the initial page loads faster.
- Combining code splitting with server-side rendering, as described in the README's use notes.
Frequently asked questions
How do I install react-loadable?
The README's install command is yarn add react-loadable. Its listed prerequisites are Node.js, Yarn or npm, React, and a bundler that supports import() such as Webpack 2+.
Is react-loadable free to use?
The licence is MIT, as listed for this project. Check the LICENSE file in the repository before using it in a commercial product.
Does react-loadable require Webpack?
The README ties automatic code splitting to Webpack 2+ and import(). The project needs a bundler that supports dynamic import(), and Webpack is the bundler the README names.
Does react-loadable work with server-side rendering?
The README lists server-side rendering with code splitting as a use case, and the library's guide says handling SSR is one of the problems it abstracts away. A related add-on, react-loadable-ssr-addon, is listed in the README for loading split chunks during SSR.
Is react-loadable still maintained?
The README does not state a current maintenance status. The repository's last push date is 2024-07-10, so check recent activity and open issues before depending on it for a new project.
What are alternatives to react-loadable?
The project lists React.lazy and Suspense, loadable-components, react-lazily and react-loadable-visibility as comparable projects. react-loadable-visibility keeps the same API and loads content only when it is visible on screen.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
react-loadable suits React developers using Webpack who want simple component-level code splitting with a loading state, including for server-side rendering. Teams that want an actively maintained option, or that use a non-React stack, should compare it with React.lazy and Suspense or loadable-components before choosing.
Install options & downloads