0
# React Loadable
1

2
React Loadable is a higher-order component library for React that enables dynamic code splitting and lazy loading of components using dynamic imports. It provides a declarative API for loading components asynchronously with customizable loading states, error handling, and server-side rendering support.
3

4
The library helps reduce initial bundle sizes by splitting code at the component level, allowing applications to load only the necessary components when they are needed. It includes utilities for Babel and Webpack integration, supports timeout handling for slow network connections, and provides preloading capabilities for improved user experience.
5

6
## Package Information
7

8
- **Package Name**: react-loadable
9
- **Package Type**: npm
10
- **Language**: JavaScript
11
- **Installation**: `npm install react-loadable`
12
- **Peer Dependencies**: `react`
13

14
## Core Imports
15

16
```javascript
17
import Loadable from 'react-loadable';
18
```
19

20
For CommonJS:
21

22
```javascript
23
const Loadable = require('react-loadable');
24
```
25

26
## Basic Usage
27

28
```javascript
29
import React from 'react';
30
import Loadable from 'react-loadable';
31

32
// Loading component
33
function Loading(props) {
34
  if (props.error) {
35
    return <div>Error! <button onClick={props.retry}>Retry</button></div>;
36
  } else if (props.pastDelay) {
37
    return <div>Loading...</div>;
38
  } else {
39
    return null;
40
  }
41
}
42

43
// Create loadable component
44
const LoadableComponent = Loadable({
45
  loader: () => import('./MyComponent'),
46
  loading: Loading,
47
  delay: 200,
48
  timeout: 10000,
49
});
50

51
// Use in render
52
function App() {
53
  return (
54
    <div>
55
      <h1>My App</h1>
56
      <LoadableComponent />
57
    </div>
58
  );
59
}
60
```
61

62
## Architecture
63

64
React Loadable is built around several key components:
65

66
- **Higher-Order Components**: `Loadable` and `Loadable.Map` create component wrappers that handle dynamic loading
67
- **Loading States**: Comprehensive state management for loading, error, delay, and timeout conditions
68
- **Server-Side Rendering**: Built-in SSR support with module tracking and preloading utilities
69
- **Build Tool Integration**: Babel plugin for automatic module resolution and Webpack plugin for bundle mapping
70
- **Preloading System**: Static preload methods and global preloading utilities for performance optimization
71

72
## Capabilities
73

74
### Dynamic Component Loading
75

76
Core functionality for creating loadable components that split code at the component level. Perfect for reducing initial bundle sizes and implementing lazy loading.
77

78
```javascript { .api }
79
function Loadable(options: LoadableOptions): LoadableComponent;
80

81
interface LoadableOptions {
82
  loader: () => Promise<any>;
83
  loading: LoadingComponent;
84
  delay?: number;
85
  timeout?: number;
86
  render?: (loaded: any, props: any) => React.ReactElement;
87
  webpack?: () => number[];
88
  modules?: string[];
89
}
90
```
91

92
[Dynamic Loading](./dynamic-loading.md)
93

94
### Multi-Resource Loading
95

96
Load multiple resources in parallel with `Loadable.Map`, enabling complex loading scenarios where components depend on multiple modules or data sources.
97

98
```javascript { .api }
99
function LoadableMap(options: LoadableMapOptions): LoadableComponent;
100

101
interface LoadableMapOptions {
102
  loader: { [key: string]: () => Promise<any> };
103
  loading: LoadingComponent;
104
  render: (loaded: { [key: string]: any }, props: any) => React.ReactElement;
105
  delay?: number;
106
  timeout?: number;
107
  webpack?: () => number[];
108
  modules?: string[];
109
}
110
```
111

112
[Multi-Resource Loading](./multi-resource-loading.md)
113

114
### Server-Side Rendering
115

116
Comprehensive SSR support including module capture, preloading utilities, and bundle mapping for seamless server-client hydration.
117

118
```javascript { .api }
119
class Capture extends React.Component {
120
  static propTypes: {
121
    report: (moduleName: string) => void;
122
    children: React.ReactNode;
123
  };
124
}
125

126
function preloadAll(): Promise<void>;
127
function preloadReady(): Promise<void>;
128
```
129

130
[Server-Side Rendering](./server-side-rendering.md)
131

132
### Build Tool Integration
133

134
Babel plugin for automatic module resolution and Webpack plugin for generating bundle manifests, simplifying the setup for server-side rendering.
135

136
```javascript { .api }
137
// Babel plugin: react-loadable/babel
138
// Webpack plugin
139
class ReactLoadablePlugin {
140
  constructor(options: { filename: string });
141
}
142

143
function getBundles(stats: any, modules: string[]): Bundle[];
144
```
145

146
[Build Integration](./build-integration.md)
147

148
## Types
149

150
```javascript { .api }
151
interface LoadingComponentProps {
152
  isLoading: boolean;
153
  pastDelay: boolean;
154
  timedOut: boolean;
155
  error: Error | null;
156
  retry: () => void;
157
}
158

159
interface LoadableComponent extends React.Component {
160
  static preload(): Promise<any>;
161
}
162

163
interface Bundle {
164
  id: number | string;
165
  name: string;
166
  file: string;
167
  publicPath: string;
168
}
169
```