useInfiniteSentinel
Attach the callback ref to a measurable HTML element at the end of a list. Unlike one-time lazy loading, this hook can request another page while the sentinel remains visible.
import { useInfiniteSentinel } from '@ilokesto/utilinent/hooks';
function PageSentinel({ fetchNextPage, hasNextPage, isFetchingNextPage }) {
const { ref, isLoading, isError, retry } = useInfiniteSentinel({
onLoadMore: fetchNextPage,
hasMore: hasNextPage,
busy: isFetchingNextPage,
rootMargin: '200px',
});
return (
<div ref={ref} style={{ minHeight: 1 }}>
{isLoading ? 'Loading...' : null}
{isError ? <button type="button" onClick={retry}>Retry</button> : null}
</div>
);
}Options
| Option | Type | Default / responsibility |
|---|---|---|
onLoadMore | () => void | Promise<unknown> | Required. Starts consumer-owned work; return its promise to retain the internal lock until settlement. |
hasMore | boolean | Required. Set to false when there are no more pages. |
busy | boolean | false. The consumer's loading state. A committed true to false transition re-arms a visible sentinel. |
disabled | boolean | false. Pauses automatic loading and manual retry. |
onError | (error: unknown) => void | Optional notification for a thrown or rejected load; should not throw. |
root | Element | null | null (viewport). Pass a scrolling container for nested scrolling. |
rootMargin | string | "0%". Positive margins can prefetch before the sentinel enters view. |
threshold | number | number[] | 0. Thresholds are normalized by value; equal option sets share native observers. |
Return value
| Field | Meaning |
|---|---|
ref | Stable callback ref accepting HTMLElement | null. |
isIntersecting | Whether the current target satisfies intersection and threshold conditions. Initially false. |
isLoading | Controlled busy or an internally pending callback result. |
isError | Boolean failure flag, independent of the reason. Initially false; set to true on failure and reset to false when another eligible attempt starts. |
error | Original unknown failure reason, including undefined; cleared to undefined when another eligible attempt starts. Use isError, not this value's truthiness, to detect failure. |
retry() | Stable manual attempt, including when outside the viewport or IntersectionObserver is unavailable. Still obeys busy, disabled, hasMore, the mounted target, and the in-flight lock. |
Ownership and repeated loading
The consumer owns pages, cache, cancellation, busy, and hasMore. The hook owns observation, an in-flight lock, and failure state. It never cancels a promise supplied by the consumer.
An eligible entry requests once. Repeated intersecting records do not request again. A committed busy: true to false cycle re-arms loading without requiring a leave/enter event. Re-enabling disabled or changing hasMore back to true also re-arms loading. No automatic request runs while hidden, busy, disabled, failed, or exhausted. An attempt re-armed during a pending promise waits for settlement; multiple signals coalesce into one pending opportunity.
Promise fulfillment alone does not request the next page. This prevents immediately resolved or synchronous callbacks from creating a loop. To fill a scroll container continuously, expose your data loader's committed busy cycle. A synchronous callback must set controlled busy while its external work runs; otherwise only the hook's callback turn is locked.
Changing callback identity alone neither re-arms nor restarts observation. The next attempt and error notification use the latest committed callbacks. A replaced target starts with unknown visibility and must receive a new observation.
Failure and cleanup
A synchronous throw or returned promise rejection sets isError to true, preserves the original reason in error, invokes onError with that same reason, and pauses automatic requests. This includes undefined, null, "", false, and 0: error alone cannot identify failure.
Neither repeated visible records nor a busy cycle retries a failure. Call retry(), or let the sentinel leave and re-enter, to try again. A fresh observation after target or observer-option changes also permits a new entry. Only an eligible new attempt resets isError to false and error to undefined; leaving the viewport, changing observation options, or a blocked retry does not clear them. They remain reset after success. Returning a promise is necessary for the hook to see an asynchronous failure; callbacks that catch their own errors must manage retry policy themselves.
On unmount, observation is released and late settlements cannot invoke onError or launch another load. StrictMode effect replay does not start a load by itself. On the server and in browsers without IntersectionObserver, no automatic load starts; provide a manual retry button if loading must remain available.
The hook does not add element sizing. Give its target a measurable box, or use LoadMore, which supplies a minimum box by default.