{"id":13630282,"url":"https://github.com/researchgate/react-intersection-list","last_synced_at":"2025-04-06T22:07:28.345Z","repository":{"id":24915372,"uuid":"102753476","full_name":"researchgate/react-intersection-list","owner":"researchgate","description":"React infinite scroll using the Intersection \u003cObserver /\u003e API","archived":false,"fork":false,"pushed_at":"2023-07-18T20:15:50.000Z","size":8621,"stargazers_count":140,"open_issues_count":24,"forks_count":13,"subscribers_count":10,"default_branch":"main","last_synced_at":"2024-05-20T10:31:41.012Z","etag":null,"topics":["infinite-scroll","intersection-observer","list","react"],"latest_commit_sha":null,"homepage":"https://researchgate.github.io/react-intersection-list/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/researchgate.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS"}},"created_at":"2017-09-07T15:22:53.000Z","updated_at":"2023-11-19T05:21:32.000Z","dependencies_parsed_at":"2024-01-12T10:25:55.537Z","dependency_job_id":"f9e79cd9-c639-4e16-99d9-94fb9ba2ccb6","html_url":"https://github.com/researchgate/react-intersection-list","commit_stats":{"total_commits":403,"total_committers":13,"mean_commits":31.0,"dds":"0.46401985111662536","last_synced_commit":"e873ee45e215656f700f0f02c340ffa3eb06bb65"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/researchgate%2Freact-intersection-list","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/researchgate%2Freact-intersection-list/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/researchgate%2Freact-intersection-list/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/researchgate%2Freact-intersection-list/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/researchgate","download_url":"https://codeload.github.com/researchgate/react-intersection-list/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247557767,"owners_count":20958047,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["infinite-scroll","intersection-observer","list","react"],"created_at":"2024-08-01T22:01:37.153Z","updated_at":"2025-04-06T22:07:28.329Z","avatar_url":"https://github.com/researchgate.png","language":"JavaScript","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.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"React Intersection List\" src=\".github/logo.svg\" width=\"888\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://travis-ci.com/researchgate/react-intersection-list\"\u003e\u003cimg alt=\"Build Status\" src=\"https://travis-ci.com/researchgate/react-intersection-list.svg?branch=master\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/researchgate/react-intersection-list\"\u003e\u003cimg alt=\"Codecov\" src=\"https://img.shields.io/codecov/c/github/researchgate/react-intersection-list.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@researchgate/react-intersection-list\"\u003e\u003cimg alt=\"NPM version\" src=\"https://img.shields.io/npm/v/@researchgate/react-intersection-list.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/prettier/prettier\"\u003e\u003cimg alt=\"styled with prettier\" src=\"https://img.shields.io/badge/styled_with-prettier-ff69b4.svg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\n\u003e **Agent Smith:** ...we have no choice but to continue as planned. Deploy the\n\u003e sentinels. Immediately.\n\n**React Intersection List** builds on top of\n**[React Intersection Observer](https://github.com/researchgate/react-intersection-observer)**,\nusing a [sentinel](https://en.wikipedia.org/wiki/Sentinel_value) in the DOM to\ndeliver a high-performance and smooth scrolling experience, even on low-end\ndevices.\n\n\u003cbr\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTable of Contents\u003c/strong\u003e\u003c/summary\u003e\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [Getting Started](#getting-started)\n- [Why React Intersection List?](#why-react-intersection-list)\n- [Documentation](#documentation)\n  - [How to](#how-to)\n  - [FAQ](#faq)\n  - [Props](#props)\n  - [Examples](#examples)\n- [Contributing](#contributing)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c/details\u003e\n\n## Getting Started\n\n```\n$ npm install --save @researchgate/react-intersection-list\n```\n\nAnd optionally the\n[polyfill](https://github.com/w3c/IntersectionObserver/tree/gh-pages/polyfill):\n\n```\n$ npm install --save intersection-observer\n```\n\nNext create a `\u003cList\u003e` and two instance methods as props `children` and\n`itemRenderer`:\n\n```jsx\nimport React, { Component } from 'react';\nimport List from '@researchgate/react-intersection-list';\n\nexport default class InfiniteList extends Component {\n  itemsRenderer = (items, ref) =\u003e (\n    \u003cul className=\"list\" ref={ref}\u003e\n      {items}\n    \u003c/ul\u003e\n  );\n\n  itemRenderer = (index, key) =\u003e \u003cli key={key}\u003e{index}\u003c/li\u003e;\n\n  render() {\n    return (\n      \u003cList\n        itemCount={1000}\n        itemsRenderer={this.itemsRenderer}\n        renderItem={this.itemRenderer}\n      /\u003e\n    );\n  }\n}\n```\n\nNote that `\u003cList\u003e` is a `PureComponent` so it can keep itself from re-rendering.\nIt's highly recommended to avoid creating new functions for `renderItem` and\n`itemsRenderer` so that it can successfully shallow compare props on re-render.\n\n## Why React Intersection List?\n\nThe approach to infinite scrolling was commonly done by devs implementing\nthrottled `scroll` event callbacks. This keeps the main thread unnecessarily\nbusy... No more! `IntersectionObservers` invoke callbacks in a **low-priority\nand asynchronous** way by design.\n\n\u003e **Agent Smith:** Never send a human to do a machine's job.\n\nThe implementation follows these steps:\n\n1. Add a sentinel close to the last item in the list\n2. Update the list moving the internal cursor\n3. Trigger a callback when the sentinel comes into view\n4. Reposition the recycled sentinel at the end\n5. Repeat (∞) ?\n\n## Documentation\n\n### How to\n\nProvided an `itemsRenderer` prop you must attach the `ref` argument to your\nscrollable DOM element:\n\n```jsx\n\u003cdiv ref={ref}\u003e{items}\u003c/div\u003e\n```\n\nThis element specifies `overflow: auto|scroll` and it'll become the\n`IntersectionObserver root`. If the `overflow` property isn't found, then\n`window` will be used as the `root` instead.\n\nThe `sentinel` element is by default detached from the list when the current\nsize reaches the available length, unless you're using `awaitMore`. In case your\nlist is in memory and you rely on the list for incremental rendering only, the\ndefault detaching behavior suffices. If you're loading more items in an\nasynchoronous way, make sure you switch `awaitMore` once you reach the total\nlength (bottom of the list).\n\nThe prop `itemCount` must be used if the prop `items` is not provided, and\nviceversa. Calculating the list size is done by adding the current size and the\npage size until the items' length is reached.\n\n### FAQ\n\n\u003cdetails\u003e\n  \u003csummary\u003eWhy am I receiving too many `onIntersection` callbacks\u003c/summary\u003e\n  We extend `PureComponent`. That means, if the parent component re-renders and the _props_ passed to your `\u003cList /\u003e` don't\nhold the same reference anymore, the list re-renders and we accidentally restart the `IntersectionObserver` of the `Sentinel`.\n\u003c/details\u003e\n\u003cbr /\u003e\n\u003cdetails\u003e\n  \u003csummary\u003eDo I always need to assign the `ref`?\u003c/summary\u003e\n  Yes, the ref callback will be used as the `root` and is forwarded to the `IntersectionObserver` within the `Sentinel`.\n\u003c/details\u003e\n\u003cbr /\u003e\n\u003cdetails\u003e\n  \u003csummary\u003eWhat's the `threshold` value, and why does it need a *unit*?\u003c/summary\u003e\n  The `threshold` value is the amount of space needed before the `sentinel` intersects with the root. The prop is\ntransformed into a valid `rootMargin` property for the `IntersectionObserver`, depending on the `axis` you select. As a\nsidenote, we believe that a percentage unit works best for responsive layouts.\n\u003c/details\u003e\n\u003cbr /\u003e\n\u003cdetails\u003e\n  \u003csummary\u003eI am getting a console warning when I first load the list\u003c/summary\u003e\n  \u003cblockquote\u003eThe sentinel detected a viewport with a bigger size than the size of its items...\u003c/blockquote\u003e\nThe prop `pageSize` is `10` by default, so make sure you're not falling short on items when you first render the\ncomponent. 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.\n\u003c/details\u003e\n\u003cbr /\u003e\n\u003cdetails\u003e\n  \u003csummary\u003eWhy doesn't the list render my updated list element(s)?\u003c/summary\u003e\n  The list renders items based on its props. An update somewhere else in your app (or within your list item) might update\nyour list element(s), but if your list's `currentLength` prop for instance, remains unchanged, the list prevents a\nre-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.\n\u003c/details\u003e\n\u003cbr /\u003e\n\u003cdetails\u003e\n  \u003csummary\u003eAre you planning to implement a \"virtual list mode\" like react-virtualized?\u003c/summary\u003e\n  Yes, there's already an [open issue](https://github.com/researchgate/react-intersection-list/issues/2) to implement a\nmode 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 :)\n\u003c/details\u003e\n\n### Props\n\n| property              | type                                                               | default                                        | description                                                                                             |\n| --------------------- | ------------------------------------------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| `renderItem/children` | `(index: number, key: number) =\u003e React.Element`                    | `(index, key) =\u003e \u003cdiv key={key}\u003e{index}\u003c/div\u003e` | render function as children or render props;\u003cbr /\u003egets call once for each item.                         |\n| `itemsRenderer`       | `(items: Array(React.Element), ref: HTMLElement) =\u003e React.Element` | `(items, ref) =\u003e \u003cdiv ref={ref}\u003e{items}\u003c/div\u003e` | render function for the list's\u003cbr /\u003eroot element, often returning a scrollable element.                 |\n| `itemCount/items`     | `number/Array (or Iterable Object)`                                | `0`                                            | item count to render.                                                                                   |\n| `awaitMore`           | `boolean`                                                          |                                                | if true keeps the sentinel from detaching.                                                              |\n| `onIntersection`      | `(size: number, pageSize: number) =\u003e void`                         |                                                | invoked when the sentinel comes into view.                                                              |\n| `threshold`           | `string`                                                           | `100px`                                        | value in absolute `px` or `%`\u003cbr /\u003eas spacing before the sentinel hits the edge of the list's viewport. |\n| `axis`                | `string`                                                           | `y`                                            | scroll direction: `y` == vertical and `x` == horizontal                                                 |\n| `pageSize`            | `number`                                                           | `10`                                           | number of items to render each hit.                                                                     |\n| `initialIndex`        | `number`                                                           | `0`                                            | start position of iterator of items.                                                                    |\n\n### Examples\n\nFind multiple examples under:\n[https://researchgate.github.io/react-intersection-list/](https://researchgate.github.io/react-intersection-list/)\n\n## Contributing\n\nWe'd love your help on creating React Intersection List!\n\nBefore you do, please read our [Code of Conduct](.github/CODE_OF_CONDUCT.md) so\nyou know what we expect when you contribute to our projects.\n\nOur [Contributing Guide](.github/CONTRIBUTING.md) tells you about our\ndevelopment process and what we're looking for, gives you instructions on how to\nissue bugs and suggest features, and explains how you can build and test your\nchanges.\n\n**Haven't contributed to an open source project before?** No problem!\n[Contributing Guide](.github/CONTRIBUTING.md) has you covered as well.\n","funding_links":[],"categories":["JavaScript","Uncategorized"],"sub_categories":["Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fresearchgate%2Freact-intersection-list","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fresearchgate%2Freact-intersection-list","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fresearchgate%2Freact-intersection-list/lists"}