0
# React Infinite Scroller
1

2
React Infinite Scroller is a lightweight React component that provides infinite scrolling functionality for both window and element-based scroll detection. It supports customizable thresholds, reverse scrolling for chat-like interfaces, and passive event listeners for optimal performance.
3

4
## Package Information
5

6
- **Package Name**: react-infinite-scroller
7
- **Package Type**: npm
8
- **Language**: JavaScript (React component)
9
- **Installation**: `npm install react-infinite-scroller`
10

11
## Core Imports
12

13
```javascript
14
import InfiniteScroll from 'react-infinite-scroller';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const InfiniteScroll = require('react-infinite-scroller');
21
```
22

23
## Basic Usage
24

25
```javascript
26
import React, { useState } from 'react';
27
import InfiniteScroll from 'react-infinite-scroller';
28

29
function MyComponent() {
30
  const [items, setItems] = useState([]);
31
  const [hasMore, setHasMore] = useState(true);
32

33
  const loadMore = async (page) => {
34
    try {
35
      // Note: page starts from pageStart + 1 (so if pageStart=0, first call gets page=1)
36
      const response = await fetch(`/api/items?page=${page}`);
37
      const newItems = await response.json();
38
      
39
      if (newItems.length === 0) {
40
        setHasMore(false);
41
      } else {
42
        setItems(prevItems => [...prevItems, ...newItems]);
43
      }
44
    } catch (error) {
45
      console.error('Failed to load items:', error);
46
    }
47
  };
48

49
  return (
50
    <InfiniteScroll
51
      pageStart={0}
52
      loadMore={loadMore}
53
      hasMore={hasMore}
54
      loader={<div className="loader" key={0}>Loading...</div>}
55
    >
56
      <div>
57
        {items.map((item, index) => (
58
          <div key={index}>{item.name}</div>
59
        ))}
60
      </div>
61
    </InfiniteScroll>
62
  );
63
}
64
```
65

66
## Capabilities
67

68
### InfiniteScroll Component
69

70
Core React component that handles infinite scroll functionality with comprehensive configuration options.
71

72
```javascript { .api }
73
/**
74
 * React component for infinite scrolling functionality
75
 * @component
76
 */
77
function InfiniteScroll(props: InfiniteScrollProps): React.ReactElement;
78

79
interface InfiniteScrollProps {
80
  /** Content to be rendered inside the scroll container (required) */
81
  children: React.ReactNode;
82
  
83
  /** Callback function triggered when more content needs to be loaded (required)
84
   * @param page - Page number starting from pageStart + 1 */
85
  loadMore: (page: number) => void;
86
  
87
  /** HTML element type to render as container */
88
  element?: string | React.ComponentType;
89
  
90
  /** Whether more items are available to load
91
   * When false, all scroll event listeners are automatically removed */
92
  hasMore?: boolean;
93
  
94
  /** Whether to trigger loadMore on component mount */
95
  initialLoad?: boolean;
96
  
97
  /** Whether to load content when scrolling to top (chat-like behavior) */
98
  isReverse?: boolean;
99
  
100
  /** React element to display while loading */
101
  loader?: React.ReactNode;
102
  
103
  /** Starting page number for loadMore callback */
104
  pageStart?: number;
105
  
106
  /** Ref callback to access the scroll container element
107
   * Note: Called after internal ref processing for scroll detection */
108
  ref?: (node: HTMLElement | null) => void;
109
  
110
  /** Function to override default scroll parent detection */
111
  getScrollParent?: () => HTMLElement;
112
  
113
  /** Distance in pixels from scroll end to trigger loadMore */
114
  threshold?: number;
115
  
116
  /** Event listener capture option */
117
  useCapture?: boolean;
118
  
119
  /** Whether to use window scroll events or parent element events */
120
  useWindow?: boolean;
121
}
122
```
123

124
**Default Props:**
125
- `element`: `'div'`
126
- `hasMore`: `false`
127
- `initialLoad`: `true`
128
- `pageStart`: `0`
129
- `ref`: `null`
130
- `threshold`: `250`
131
- `useWindow`: `true`
132
- `isReverse`: `false`
133
- `useCapture`: `false`
134
- `loader`: `null`
135
- `getScrollParent`: `null`
136

137
### Window Scroll Mode
138

139
Default behavior using window scroll events for infinite scrolling.
140

141
```javascript
142
<InfiniteScroll
143
  pageStart={0}
144
  loadMore={loadFunc}
145
  hasMore={true}
146
  loader={<div className="loader" key={0}>Loading...</div>}
147
>
148
  {items}
149
</InfiniteScroll>
150
```
151

152
### Element Scroll Mode
153

154
Infinite scrolling within a specific scrollable container element.
155

156
```javascript
157
<div style={{height: '400px', overflow: 'auto'}}>
158
  <InfiniteScroll
159
    pageStart={0}
160
    loadMore={loadFunc}
161
    hasMore={true}
162
    loader={<div className="loader" key={0}>Loading...</div>}
163
    useWindow={false}
164
  >
165
    {items}
166
  </InfiniteScroll>
167
</div>
168
```
169

170
### Custom Parent Element
171

172
Using a custom parent element for scroll calculations with getScrollParent.
173

174
```javascript
175
function MyComponent() {
176
  const scrollParentRef = useRef(null);
177

178
  return (
179
    <div 
180
      style={{height: '400px', overflow: 'auto'}} 
181
      ref={scrollParentRef}
182
    >
183
      <div>
184
        <InfiniteScroll
185
          pageStart={0}
186
          loadMore={loadFunc}
187
          hasMore={true}
188
          loader={<div className="loader" key={0}>Loading...</div>}
189
          useWindow={false}
190
          getScrollParent={() => scrollParentRef.current}
191
        >
192
          {items}
193
        </InfiniteScroll>
194
      </div>
195
    </div>
196
  );
197
}
198
```
199

200
### Reverse Scrolling (Chat Mode)
201

202
Loading content when scrolling to the top, useful for chat interfaces.
203

204
```javascript
205
<InfiniteScroll
206
  pageStart={0}
207
  loadMore={loadFunc}
208
  hasMore={true}
209
  loader={<div className="loader" key={0}>Loading...</div>}
210
  isReverse={true}
211
>
212
  {messages}
213
</InfiniteScroll>
214
```
215

216
### Instance Methods
217

218
#### setDefaultLoader
219

220
Sets a default loader component for all InfiniteScroll instances.
221

222
```javascript { .api }
223
/**
224
 * Set a default loader for all InfiniteScroll components
225
 * @param loader - React element to use as default loader
226
 */
227
setDefaultLoader(loader: React.ReactNode): void;
228
```
229

230
**Usage:**
231
```javascript
232
const infiniteScrollRef = useRef(null);
233

234
// Set default loader on component instance
235
useEffect(() => {
236
  if (infiniteScrollRef.current) {
237
    infiniteScrollRef.current.setDefaultLoader(
238
      <div className="default-loader">Loading more items...</div>
239
    );
240
  }
241
}, []);
242

243
return (
244
  <InfiniteScroll
245
    ref={infiniteScrollRef}
246
    pageStart={0}
247
    loadMore={loadFunc}
248
    hasMore={true}
249
  >
250
    {items}
251
  </InfiniteScroll>
252
);
253
```
254

255
## Event Handling and Performance
256

257
The component automatically handles:
258
- **Passive event listeners**: Uses passive listeners when supported for better performance
259
- **Event cleanup**: Removes all event listeners on component unmount and when `hasMore` becomes false
260
- **Chrome optimization**: Prevents Chrome hangups with specific mousewheel handling
261
- **Scroll position management**: Maintains scroll position in reverse mode after new content loads
262
- **Page numbering**: The `loadMore` callback receives page numbers starting from `pageStart + 1`
263

264
## Common Patterns
265

266
### Loading State Management
267

268
```javascript
269
function InfiniteList() {
270
  const [items, setItems] = useState([]);
271
  const [hasMore, setHasMore] = useState(true);
272
  const [isLoading, setIsLoading] = useState(false);
273

274
  const loadMore = async (page) => {
275
    if (isLoading) return; // Prevent overlapping requests
276
    
277
    setIsLoading(true);
278
    try {
279
      const newItems = await fetchItems(page);
280
      if (newItems.length === 0) {
281
        setHasMore(false);
282
      } else {
283
        setItems(prev => [...prev, ...newItems]);
284
      }
285
    } finally {
286
      setIsLoading(false);
287
    }
288
  };
289

290
  return (
291
    <InfiniteScroll
292
      pageStart={0}
293
      loadMore={loadMore}
294
      hasMore={hasMore && !isLoading}
295
      loader={<div>Loading...</div>}
296
    >
297
      <div>
298
        {items.map((item, index) => (
299
          <div key={item.id || index}>{item.content}</div>
300
        ))}
301
      </div>
302
    </InfiniteScroll>
303
  );
304
}
305
```
306

307
### Custom Threshold
308

309
```javascript
310
<InfiniteScroll
311
  pageStart={0}
312
  loadMore={loadFunc}
313
  hasMore={true}
314
  threshold={100} // Trigger load when 100px from bottom
315
  loader={<div>Loading...</div>}
316
>
317
  {items}
318
</InfiniteScroll>
319
```
320

321
### Error Handling
322

323
```javascript
324
const loadMore = async (page) => {
325
  try {
326
    const newItems = await fetchItems(page);
327
    setItems(prev => [...prev, ...newItems]);
328
    setHasMore(newItems.length > 0);
329
  } catch (error) {
330
    console.error('Failed to load items:', error);
331
    setHasMore(false); // Stop further loading attempts
332
  }
333
};
334
```