@scrollstackjs/react

React adapter for ScrollStack — a headless useInfiniteScroll hook. You bring the markup; the engine owns the behavior. 0.32 KB gzipped, bound with useSyncExternalStore (concurrent- and SSR-safe).

📖 Docs · API reference · Live demo · Tutorial

npm i @scrollstackjs/react

Requires React >= 18. Pulls in @scrollstackjs/core automatically.

Quick start

import { useInfiniteScroll } from '@scrollstackjs/react';

function Feed() {
  const { pages, ref, hasNextPage, isFetchingNextPage } = useInfiniteScroll({
    initialPageParam: 0,
    fetchPage: async ({ pageParam, signal }) =>
      (await fetch(`/api/items?cursor=${pageParam}`, { signal })).json(),
    getNextPageParam: (last) => last.nextCursor, // null = no more pages
  });

  return (
    <>
      {pages
        .flatMap((p) => p.items)
        .map((item) => (
          <Row key={item.id} {...item} />
        ))}
      {hasNextPage && <div ref={ref}>{isFetchingNextPage ? 'Loading…' : ''}</div>}
    </>
  );
}

The ref sentinel loads the next page when it scrolls into view. The hook returns the full core snapshot plus ref, loadNextPage, retry, reset and engine.

Handling errors

A failed load-more keeps the pages you already have — status stays 'success' while error is set, so you can offer a retry without blanking the list:

function Feed() {
  const { pages, error, isFetching, retry } = useInfiniteScroll(options);

  return (
    <>
      {/* …rows… */}
      {error && pages.length > 0 && !isFetching && <button onClick={retry}>Retry</button>}
    </>
  );
}

v0 note: options are read once on mount. If the data source changes, call reset() or remount via a key. Reactive options are on the roadmap.

Learn more

| | | | ------------------------------------------------------------------- | ------------------------------------------- | | Getting started | Install and first feed | | Core concepts | The snapshot and the two-axis state machine | | Pagination | Cursor, offset and page-number recipes | | Errors & retry | Backoff, manual retry, load-more failures | | Server rendering | What runs where | | Devtools | Inspect the engine while you build |

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md.

MIT © devgauravjatt