react-infinite-scroll-hook

The hook works by using an IntersectionObserver to monitor a "sentry" component. When this sentry component becomes visible (or approaches visibility based on rootMargin), the onLoadMore callback is triggered.

Key Concepts:

• Sentry Component: A component (like a loading indicator, an empty div, or the last item in a list) that must remain mounted as long as you want the observer to stay active. To prevent flickering and maintain layout consistency, it is recommended to keep the sentry mounted even if your loading state is false, provided there is still a next page to load.
• Scrolling Direction: You can place the sentry at the bottom for vertical scrolling, at the top for chat-like interfaces, or use it for horizontal scrolling.
• Browser Compatibility: The hook relies on IntersectionObserver. For older browsers, you may need to provide a polyfill.

Depending on your React version, choose the appropriate package version:

• React v19: Use versions after v6, as they utilize cleanup functions for refs.
• React < v19: You can use v5 until you migrate to React 19.

Install the package using npm to start using the infinite scroll hook in your React project.

npm install react-infinite-scroll-hook

If you want to use a specific element as the scrollable container instead of the document, use the rootRef returned by the hook and attach it to your container element.

import useInfiniteScroll from 'react-infinite-scroll-hook';

function VerticalElementScrollPage() {
  const { loading, items, hasNextPage, error, loadMore } = useLoadItems();

  const [infiniteRef, { rootRef }] = useInfiniteScroll({
    loading,
    hasNextPage,
    onLoadMore: loadMore,
    disabled: Boolean(error),
    rootMargin: '0px 0px 400px 0px',
  });

  return (
    <Scrollable ref={rootRef}>
      <List>
        {items.map((item) => (
          <ListItem key={item.key}>{item.value}</ListItem>
        ))}
      </List>
      {hasNextPage && <Loading ref={infiniteRef} />}
    </Scrollable>
  );
}

To implement infinite scrolling on the main window/document, use the useInfiniteScroll hook and attach the returned infiniteRef to your sentry component.

import useInfiniteScroll from 'react-infinite-scroll-hook';

function WindowScroll() {
  const { loading, items, hasNextPage, error, loadMore } = useLoadItems();

  const [infiniteRef] = useInfiniteScroll({
    loading,
    hasNextPage,
    onLoadMore: loadMore,
    // It can be reactivated by setting "error" state as undefined.
    disabled: Boolean(error),
    // rootMargin is passed to 'IntersectionObserver'.
    rootMargin: '0px 0px 400px 0px',
  });

  return (
    <div>
      <List>
        {items.map((item) => (
          <ListItem key={item.key}>{item.value}</ListItem>
        ))}
      </List>
      {hasNextPage && <Loading ref={infiniteRef} />}
    </div>
  );
}

The useInfiniteScroll hook accepts the following configuration options:

The useInfiniteScroll hook returns a tuple of type UseInfiniteScrollHookResult containing:

1. UseInfiniteScrollHookRefCallback: A ref that should be attached to the element acting as the 'sentinel' (the element that triggers the load when it enters the viewport).
2. An object containing { rootRef: UseInfiniteScrollHookRootRefCallback }: A rootRef that should be attached to the scrollable container element.

The useInfiniteScroll hook (exported as default) is the primary API for implementing infinite scrolling in React applications. It provides a way to detect when a user has scrolled to the bottom of a container and triggers a callback to load more content.

To use it, you will typically need to interact with the following types:

• UseInfiniteScrollHookResult: The object returned by the hook containing the scroll state and refs.
• UseInfiniteScrollHookArgs: The configuration object passed to the hook.
• UseInfiniteScrollHookRootRefCallback: A ref callback used to attach to the scrollable container element.

The following types are exported from the package to support TypeScript implementations of the infinite scroll logic:

type UseInfiniteScrollHookArgs = ...;
type UseInfiniteScrollHookRefCallback = ...;
type UseInfiniteScrollHookResult = ...;
type UseInfiniteScrollHookRootRefCallback = ...;