0
# React Lazy Load
1

2
React Lazy Load is a React component for lazy loading content using the modern Intersection Observer API. It allows developers to defer loading of images and other content until they are about to become visible in the viewport, improving page performance and user experience. The component supports configurable offset margins, visibility thresholds, and custom styling through CSS classes.
3

4
## Package Information
5

6
- **Package Name**: react-lazy-load
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-lazy-load`
10

11
## Core Imports
12

13
```typescript
14
import LazyLoad from "react-lazy-load";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const LazyLoad = require("react-lazy-load");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import React from 'react';
27
import LazyLoad from 'react-lazy-load';
28

29
const MyComponent = () => (
30
  <div>
31
    <LazyLoad height={762}>
32
      <img src='https://example.com/image.jpg' alt="Lazy loaded image" />
33
    </LazyLoad>
34
  </div>
35
);
36
```
37

38
## Architecture
39

40
React Lazy Load is built around the Intersection Observer API and consists of:
41

42
- **LazyLoad Component**: A class-based React component that wraps content to be lazy loaded
43
- **Intersection Observer**: Modern browser API for efficient viewport intersection detection
44
- **Scroll Parent Detection**: Utility function to find the nearest scrollable container
45
- **CSS Classes**: Applied dynamically to enable custom styling and transitions
46

47
## Capabilities
48

49
### LazyLoad Component
50

51
A React class component that wraps content and defers its rendering until it becomes visible in the viewport.
52

53
```typescript { .api }
54
/**
55
 * React component for lazy loading content using Intersection Observer API
56
 * @param props - Component properties defining behavior and styling
57
 */
58
declare class LazyLoad extends React.Component<Props, State> {
59
  static defaultProps: {
60
    elementType: string;
61
    className: string;
62
    offset: number;
63
    threshold: number;
64
    width: null;
65
    onContentVisible: null;
66
    height: null;
67
  };
68
  
69
  /** Intersection observer instance used for detecting visibility */
70
  elementObserver: IntersectionObserver | null;
71
  /** React ref to the wrapper element */
72
  wrapper: React.RefObject<React.Component> | null;
73
  
74
  constructor(props: Props);
75
  componentDidMount(): void;
76
  shouldComponentUpdate(_: Props, nextState: State): boolean;
77
  componentWillUnmount(): void;
78
  getEventNode(): Window | HTMLElement;
79
  lazyLoadHandler: (entries: IntersectionObserverEntry[]) => void;
80
  render(): React.ReactElement;
81
}
82

83
interface Props {
84
  /** Content to be lazy loaded (required) */
85
  children: React.ReactNode;
86
  /** Additional CSS class names to apply to the wrapper element */
87
  className?: string;
88
  /** HTML element type to render as wrapper (default: 'div') */
89
  elementType?: string;
90
  /** Height of the placeholder element before content loads */
91
  height?: string | number;
92
  /** Viewport offset for triggering load - can be number (pixels) or string (CSS margin format) */
93
  offset?: string | number;
94
  /** Visibility threshold (0-1) - fraction of element that must be visible to trigger loading */
95
  threshold?: number;
96
  /** Width of the placeholder element before content loads */
97
  width?: number | string;
98
  /** Callback function executed when content becomes visible */
99
  onContentVisible?: () => void;
100
}
101

102
interface State {
103
  /** Whether content is visible and should be rendered */
104
  visible: boolean;
105
}
106
```
107

108
### Public Instance Methods
109

110
Public methods available on LazyLoad component instances.
111

112
```typescript { .api }
113
/**
114
 * Gets the scroll parent element for the LazyLoad wrapper
115
 * @returns The nearest scrollable ancestor element or window if none found
116
 */
117
getEventNode(): Window | HTMLElement;
118

119
/**
120
 * Intersection Observer callback handler for visibility detection
121
 * @param entries - Array of intersection observer entries from the browser API
122
 */
123
lazyLoadHandler: (entries: IntersectionObserverEntry[]) => void;
124
```
125

126
**Method Usage Examples:**
127

128
```typescript
129
import React, { useRef } from 'react';
130
import LazyLoad from 'react-lazy-load';
131

132
const ExampleWithRef = () => {
133
  const lazyLoadRef = useRef<LazyLoad>(null);
134

135
  const handleClick = () => {
136
    // Access public methods via component ref
137
    if (lazyLoadRef.current) {
138
      const scrollParent = lazyLoadRef.current.getEventNode();
139
      console.log('Scroll parent:', scrollParent);
140
    }
141
  };
142

143
  return (
144
    <div>
145
      <button onClick={handleClick}>Get Scroll Parent</button>
146
      <LazyLoad ref={lazyLoadRef} height={400}>
147
        <img src="https://example.com/image.jpg" alt="Example" />
148
      </LazyLoad>
149
    </div>
150
  );
151
};
152
```
153

154
**Component Usage Examples:**
155

156
```typescript
157
import React from 'react';
158
import LazyLoad from 'react-lazy-load';
159

160
// Basic image lazy loading
161
const BasicExample = () => (
162
  <LazyLoad height={400}>
163
    <img src="https://example.com/large-image.jpg" alt="Description" />
164
  </LazyLoad>
165
);
166

167
// Load with 300px offset before visible
168
const OffsetExample = () => (
169
  <LazyLoad height={400} offset={300}>
170
    <img src="https://example.com/image.jpg" alt="Description" />
171
  </LazyLoad>
172
);
173

174
// Load only when 95% visible with callback
175
const ThresholdExample = () => (
176
  <LazyLoad 
177
    height={400} 
178
    width={600} 
179
    threshold={0.95}
180
    onContentVisible={() => console.log('Image loaded!')}
181
  >
182
    <img src="https://example.com/image.jpg" alt="Description" />
183
  </LazyLoad>
184
);
185

186
// Custom wrapper element and styling
187
const CustomWrapperExample = () => (
188
  <LazyLoad 
189
    elementType="section"
190
    className="custom-lazy-wrapper"
191
    height={300}
192
  >
193
    <div>
194
      <h3>Lazy loaded content</h3>
195
      <p>This content loads when it becomes visible.</p>
196
    </div>
197
  </LazyLoad>
198
);
199
```
200

201
### CSS Classes
202

203
The component applies CSS classes automatically for styling and transitions.
204

205
```css { .api }
206
/* Base class applied to all LazyLoad wrapper elements */
207
.LazyLoad {
208
  /* Custom styles here */
209
}
210

211
/* Added when content becomes visible */
212
.LazyLoad.is-visible {
213
  /* Visible state styles here */
214
}
215

216
/* Example transition effect */
217
.LazyLoad {
218
  opacity: 0;
219
  transition: all 1s ease-in-out;
220
}
221

222
.LazyLoad.is-visible {
223
  opacity: 1;
224
}
225
```
226

227
## Configuration Options
228

229
### Offset Configuration
230

231
The `offset` prop controls when loading is triggered relative to the viewport:
232

233
```typescript
234
// Number: pixels offset in all directions
235
<LazyLoad offset={100}>Content</LazyLoad>
236

237
// String: CSS margin format (top right bottom left)
238
<LazyLoad offset="100px 0px 200px 50px">Content</LazyLoad>
239

240
// String: Single value for all sides
241
<LazyLoad offset="150px">Content</LazyLoad>
242
```
243

244
### Threshold Configuration
245

246
The `threshold` prop controls how much of the element must be visible:
247

248
```typescript
249
// 0: Load as soon as any part is visible (default)
250
<LazyLoad threshold={0}>Content</LazyLoad>
251

252
// 0.5: Load when 50% is visible
253
<LazyLoad threshold={0.5}>Content</LazyLoad>
254

255
// 1.0: Load only when completely visible
256
<LazyLoad threshold={1.0}>Content</LazyLoad>
257
```
258

259
**Note**: When using threshold values > 0, you must specify both `width` and `height` props for the browser to calculate the viewable area correctly.
260

261
### Element Type Configuration
262

263
Customize the wrapper HTML element:
264

265
```typescript
266
// Default div wrapper
267
<LazyLoad>Content</LazyLoad>
268

269
// Custom element types
270
<LazyLoad elementType="section">Content</LazyLoad>
271
<LazyLoad elementType="article">Content</LazyLoad>
272
<LazyLoad elementType="span">Content</LazyLoad>
273
```
274

275
## Error Handling
276

277
The component gracefully handles various scenarios:
278

279
- **Missing Intersection Observer**: Falls back to immediate loading on older browsers
280
- **Invalid threshold values**: Clamps to 0-1 range
281
- **Missing width/height with threshold**: Uses element's natural dimensions when possible
282
- **Component unmounting**: Automatically cleans up observers to prevent memory leaks
283

284
## Performance Considerations
285

286
- **One-time loading**: Content is loaded only once and observers are cleaned up immediately
287
- **Automatic cleanup**: Intersection observers are properly disposed when components unmount
288
- **Minimal re-renders**: Component only re-renders when visibility state changes from false to true
289
- **Native efficiency**: Uses browser-native Intersection Observer for optimal performance