useInfiniteScroll

Triggers a load callback whenever the scroll position reaches a boundary of a scrollable element, enabling infinite scroll for lists and feeds. Supports all four scroll directions, pre-load distance, manual control, async callbacks, and a canLoadMore gate function to control when loading stops.

Demo

useInfiniteScroll

Idle

Scroll to the bottom of the list to load more items.

Items

10

Max

50

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

Item 7

Item 8

Item 9

Item 10

Reset

Usage

Basic

Call useInfiniteScroll with a ref to the scrollable element and an async onLoadMore callback. The callback fires automatically when the user scrolls to the bottom (default direction).

Hook

import { useRef$ } from "@usels/core";
import { useInfiniteScroll } from "@usels/web";

function Component() {
  const el$ = useRef$<HTMLDivElement>();

  const { isLoading$ } = useInfiniteScroll(el$, async () => {
    const newItems = await fetchNextPage();
    items.push(...newItems);
  });

  return (
    <div ref={el$} style={{ height: 300, overflowY: "auto" }}>
      {/* list items */}
      {isLoading$.get() && <div>Loading…</div>}
    </div>
  );
}

Scope

import { createRef$ } from "@usels/core";
import { createInfiniteScroll } from "@usels/web";

function Component() {
  "use scope";
  const el$ = createRef$<HTMLDivElement>();

  const { isLoading$ } = createInfiniteScroll(el$, async () => {
    const newItems = await fetchNextPage();
    items.push(...newItems);
  });

  return (
    <div ref={el$} style={{ height: 300, overflowY: "auto" }}>
      {/* list items */}
      {isLoading$.get() && <div>Loading…</div>}
    </div>
  );
}

Direction

Use the direction option to trigger loading from any edge. Certain directions require specific CSS on the scrollable container so that new content prepends in the correct visual position.

Direction	Required CSS
bottom (default)	No special settings required
top	display: flex; flex-direction: column-reverse;
left	display: flex; flex-direction: row-reverse;
right	display: flex;

useInfiniteScroll(
  el$,
  async () => {
    /* load older messages */
  },
  { direction: "top" }
);

With distance

Set distance (in px) to start loading before the user actually reaches the boundary — useful for pre-fetching the next page early.

useInfiniteScroll(el$, onLoadMore, {
  distance: 200, // trigger 200px before the bottom edge
});

canLoadMore

Pass a canLoadMore function to control whether loading should trigger. When it returns false, the scroll listener is skipped entirely. Use this to stop loading once all pages have been fetched.

useInfiniteScroll(
  el$,
  async () => {
    const page = await fetchNextPage();
    if (!page.hasMore) setHasMore(false);
  },
  {
    canLoadMore: () => hasMore,
  }
);

Minimum load interval

Use the interval option to set a minimum number of milliseconds between consecutive load triggers.

useInfiniteScroll(el$, onLoadMore, {
  interval: 200, // minimum 200ms between consecutive loads (default: 100)
});

Manual load & reset

load triggers a load imperatively; reset re-checks the current scroll position and triggers a load if the boundary condition is met.

const { load, reset, isLoading$ } = useInfiniteScroll(el$, async () => {
  await fetchNextPage();
});

Type

Parameters

Parameter	Type	Description
element	MaybeEventTarget<Element | Document | Window>	-
onLoadMore	(direction: UseInfiniteScrollDirection) => Awaitable<void>	-
options	UseInfiniteScrollOptions (optional)	-

UseInfiniteScrollOptions

Option	Type	Default	Description
direction	UseInfiniteScrollDirection	-	Load trigger direction. Default: “bottom”
distance	number	-	arrivedState offset in px. Default: 0
immediate	boolean	-	Whether to auto-load on mount if content is already at boundary. Default: true
interval	number	-	Minimum ms between consecutive load triggers. Default: 100
canLoadMore	((el: HTMLElement) => boolean)	-	Gate function — return false to block loading. Evaluated before each load.
scrollOptions	UseScrollOptions	-	Additional options passed to useScroll
window	WindowSource	-	-

Returns

UseInfiniteScrollReturn

Name	Type	Description
isLoading$	ReadonlyObservable<boolean>	Currently loading
load	() => Promise<void>	Manually trigger a load
reset	() => void	Re-check scroll position and trigger load if needed

Source

View on GitHub