Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/researchgate/react-intersection-list
React infinite scroll using the Intersection <Observer /> API
https://github.com/researchgate/react-intersection-list
infinite-scroll intersection-observer list react
Last synced: 3 days ago
JSON representation
React infinite scroll using the Intersection <Observer /> API
- Host: GitHub
- URL: https://github.com/researchgate/react-intersection-list
- Owner: researchgate
- License: mit
- Created: 2017-09-07T15:22:53.000Z (about 7 years ago)
- Default Branch: main
- Last Pushed: 2023-07-18T20:15:50.000Z (over 1 year ago)
- Last Synced: 2024-05-20T10:31:41.012Z (6 months ago)
- Topics: infinite-scroll, intersection-observer, list, react
- Language: JavaScript
- Homepage: https://researchgate.github.io/react-intersection-list/
- Size: 8.22 MB
- Stars: 140
- Watchers: 10
- Forks: 13
- Open Issues: 24
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Authors: AUTHORS
Awesome Lists containing this project
README
⚠️ This repository is not as actively maintained as we wish it to be. Feel free to fork this project and fix any outstanding issues you might have, and we'll try to merge relevant changes eventually. We apologize for the inconvenience.
> **Agent Smith:** ...we have no choice but to continue as planned. Deploy the
> sentinels. Immediately.
**React Intersection List** builds on top of
**[React Intersection Observer](https://github.com/researchgate/react-intersection-observer)**,
using a [sentinel](https://en.wikipedia.org/wiki/Sentinel_value) in the DOM to
deliver a high-performance and smooth scrolling experience, even on low-end
devices.
Table of Contents
- [Getting Started](#getting-started)
- [Why React Intersection List?](#why-react-intersection-list)
- [Documentation](#documentation)
- [How to](#how-to)
- [FAQ](#faq)
- [Props](#props)
- [Examples](#examples)
- [Contributing](#contributing)
## Getting Started
```
$ npm install --save @researchgate/react-intersection-list
```
And optionally the
[polyfill](https://github.com/w3c/IntersectionObserver/tree/gh-pages/polyfill):
```
$ npm install --save intersection-observer
```
Next create a `` and two instance methods as props `children` and
`itemRenderer`:
```jsx
import React, { Component } from 'react';
import List from '@researchgate/react-intersection-list';
export default class InfiniteList extends Component {
itemsRenderer = (items, ref) => (
{items}
);
itemRenderer = (index, key) =>
render() {
return (
);
}
}
```
Note that `` is a `PureComponent` so it can keep itself from re-rendering.
It's highly recommended to avoid creating new functions for `renderItem` and
`itemsRenderer` so that it can successfully shallow compare props on re-render.
## Why React Intersection List?
The approach to infinite scrolling was commonly done by devs implementing
throttled `scroll` event callbacks. This keeps the main thread unnecessarily
busy... No more! `IntersectionObservers` invoke callbacks in a **low-priority
and asynchronous** way by design.
> **Agent Smith:** Never send a human to do a machine's job.
The implementation follows these steps:
1. Add a sentinel close to the last item in the list
2. Update the list moving the internal cursor
3. Trigger a callback when the sentinel comes into view
4. Reposition the recycled sentinel at the end
5. Repeat (∞) ?
## Documentation
### How to
Provided an `itemsRenderer` prop you must attach the `ref` argument to your
scrollable DOM element:
```jsx
```
This element specifies `overflow: auto|scroll` and it'll become the
`IntersectionObserver root`. If the `overflow` property isn't found, then
`window` will be used as the `root` instead.
The `sentinel` element is by default detached from the list when the current
size reaches the available length, unless you're using `awaitMore`. In case your
list is in memory and you rely on the list for incremental rendering only, the
default detaching behavior suffices. If you're loading more items in an
asynchoronous way, make sure you switch `awaitMore` once you reach the total
length (bottom of the list).
The prop `itemCount` must be used if the prop `items` is not provided, and
viceversa. Calculating the list size is done by adding the current size and the
page size until the items' length is reached.
### FAQ
Why am I receiving too many `onIntersection` callbacks
We extend `PureComponent`. That means, if the parent component re-renders and the _props_ passed to your `` don't
hold the same reference anymore, the list re-renders and we accidentally restart the `IntersectionObserver` of the `Sentinel`.
Do I always need to assign the `ref`?
Yes, the ref callback will be used as the `root` and is forwarded to the `IntersectionObserver` within the `Sentinel`.
What's the `threshold` value, and why does it need a *unit*?
The `threshold` value is the amount of space needed before the `sentinel` intersects with the root. The prop is
transformed into a valid `rootMargin` property for the `IntersectionObserver`, depending on the `axis` you select. As a
sidenote, we believe that a percentage unit works best for responsive layouts.
I am getting a console warning when I first load the list
The sentinel detected a viewport with a bigger size than the size of its items...
The prop `pageSize` is `10` by default, so make sure you're not falling short on items when you first render the
component. The idea of an infinite scrolling list is that items overflow the viewport, so that users have the impression that there're always more items available.
Why doesn't the list render my updated list element(s)?
The list renders items based on its props. An update somewhere else in your app (or within your list item) might update
your list element(s), but if your list's `currentLength` prop for instance, remains unchanged, the list prevents a
re-render. Updating the entire infinite list when one of its items has changed is far from optimal. Instead, update each item individually with some form of `connect()` function or observables.
Are you planning to implement a "virtual list mode" like react-virtualized?
Yes, there's already an [open issue](https://github.com/researchgate/react-intersection-list/issues/2) to implement a
mode using occlusion culling. It will be implemented in a future release. If you can't wait, you could help us out by opening a Pull Request :)
### Props
| property | type | default | description |
| --------------------- | ------------------------------------------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `renderItem/children` | `(index: number, key: number) => React.Element` | `(index, key) =>
gets call once for each item. |
| `itemsRenderer` | `(items: Array(React.Element), ref: HTMLElement) => React.Element` | `(items, ref) =>
root element, often returning a scrollable element. |
| `itemCount/items` | `number/Array (or Iterable Object)` | `0` | item count to render. |
| `awaitMore` | `boolean` | | if true keeps the sentinel from detaching. |
| `onIntersection` | `(size: number, pageSize: number) => void` | | invoked when the sentinel comes into view. |
| `threshold` | `string` | `100px` | value in absolute `px` or `%`
as spacing before the sentinel hits the edge of the list's viewport. |
| `axis` | `string` | `y` | scroll direction: `y` == vertical and `x` == horizontal |
| `pageSize` | `number` | `10` | number of items to render each hit. |
| `initialIndex` | `number` | `0` | start position of iterator of items. |
### Examples
Find multiple examples under:
[https://researchgate.github.io/react-intersection-list/](https://researchgate.github.io/react-intersection-list/)
## Contributing
We'd love your help on creating React Intersection List!
Before you do, please read our [Code of Conduct](.github/CODE_OF_CONDUCT.md) so
you know what we expect when you contribute to our projects.
Our [Contributing Guide](.github/CONTRIBUTING.md) tells you about our
development process and what we're looking for, gives you instructions on how to
issue bugs and suggest features, and explains how you can build and test your
changes.
**Haven't contributed to an open source project before?** No problem!
[Contributing Guide](.github/CONTRIBUTING.md) has you covered as well.