easy-pagination

React IntersectionObserver-based infinite scroll hook and component. Zero dependencies.

Install

npm install easy-pagination

Usage

Hook — Standalone Mode

import { useInfiniteScroll } from 'easy-pagination';

function ItemList() {
  const { ref, data, isLoading, error, hasMore } = useInfiniteScroll({
    fetchFn: async (page) => {
      const res = await fetch(`/api/items?page=${page}`);
      const json = await res.json();
      return { data: json.items, hasMore: json.hasMore };
    },
  });

  return (
    <div>
      {data.map((item) => (
        <div key={item.id}>{item.name}</div>
      ))}
      {isLoading && <p>Loading...</p>}
      {error && <p>Error: {error.message}</p>}
      {!hasMore && <p>No more items</p>}
      <div ref={ref} />
    </div>
  );
}

Hook — Callback Mode (with TanStack Query)

import { useInfiniteScroll } from 'easy-pagination';
import { useInfiniteQuery } from '@tanstack/react-query';

function ItemList() {
  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
    useInfiniteQuery({ /* ... */ });

  const { ref } = useInfiniteScroll({
    onLoadMore: () => fetchNextPage(),
    hasMore: hasNextPage ?? false,
    isLoading: isFetchingNextPage,
  });

  return (
    <div>
      {data?.pages.map((page) =>
        page.items.map((item) => <div key={item.id}>{item.name}</div>),
      )}
      <div ref={ref} />
    </div>
  );
}

Component

import { InfiniteScroll } from 'easy-pagination';

// Standalone
<InfiniteScroll
  fetchFn={fetchItems}
  loader={<p>Loading...</p>}
  endMessage={<p>No more items</p>}
>
  {(data) => data.map((item) => <div key={item.id}>{item.name}</div>)}
</InfiniteScroll>

// Callback
<InfiniteScroll
  onLoadMore={fetchNextPage}
  hasMore={hasNextPage}
  isLoading={isFetchingNextPage}
  loader={<p>Loading...</p>}
>
  <ItemList />
</InfiniteScroll>

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | fetchFn | (page: number) => Promise<{ data: T[]; hasMore: boolean }> | — | Standalone mode fetch function | | onLoadMore | () => void | — | Callback mode load trigger | | hasMore | boolean | true (standalone) | Whether more items exist | | isLoading | boolean | false | Prevents duplicate calls when true | | initialPage | number | 1 | Starting page (standalone only) | | threshold | number | 0 | IntersectionObserver threshold | | rootMargin | string | '0px 0px 200px 0px' | IntersectionObserver rootMargin | | enabled | boolean | true | Enable/disable observation |

License

MIT