OOmniGrid

API / Plugins / Pro / Infinite Scroll

InfiniteScrollPlugin

The InfiniteScrollPlugin from @omnigrid/infinite-scroll-plugin is a Pro plugin that loads data on demand as the user scrolls near the edges of the active row window. It fetches pages via the host-provided fetchPage callback, maintains a bounded dataset with an LRU or FIFO page cache, mounts a loading spinner into the bodyBottom slot while non-initial pages load, and keeps scroll position stable as rows are appended or prepended.

Live demo|NPM

Constructor

new InfiniteScrollPlugin<T>(options: InfiniteScrollPluginOptions<T>)

Options

Properties accepted by InfiniteScrollPluginOptions<T>.

PropertyDescription

pageSize

numberdefault: 50

Number of rows to request per fetch page.

threshold

numberdefault: 5

Number of visible rows from the active window edges at which to pre-emptively trigger a page fetch.

autoLoad

booleandefault: true

Whether to automatically fetch the first page when the grid starts with no data.

loadingAriaLabel

stringdefault: "Loading more results…"

Accessible label for the loading spinner.

cache

InfiniteScrollCacheOptions

Optional page cache configuration for fetched chunks.

Callbacks

fetchPage: (cursor: number, pageSize: number) => Promise<T[]>

Called when the next page of data needs to be loaded. The cursor is the absolute row offset of the requested page (0 for the first page). Scrolling upward may request a previous cursor. The host resolves with that batch of rows — returning fewer rows than pageSize signals the end of the dataset in the requested direction.

loadingRenderer: (context: SlotRenderContext<T>) => SlotContent

Custom renderer for the loading spinner mounted in the bodyBottom slot. If omitted, a built-in spinner is used.

onDataLoaded: (rows: T[]) => void

Called with the rows returned by each successful fetch.

onError: (error: unknown) => void

Called when a fetch fails.

Instance methods

onRegister(api): () => void

Registers the plugin after license validation (see `BaseProPlugin`), mounts its loading-content provider, subscribes to viewport / data events, and runs the initial auto-load when the grid starts with no data. Adapters decide whether the slot is visible based on whether its providers return content.

getState(): InfiniteScrollState

Returns a snapshot of the plugin state.

loadMore(): void

Imperatively loads the next page, bypassing the scroll threshold. No-op while a fetch is in flight, when no more data is expected, or when the plugin is not registered.

reset(clearData?): void

Resets the plugin to its initial state: invalidates in-flight fetch continuations, clears the page cache, and re-syncs the cursor with the grid data. When `clearData` is true the grid dataset is cleared as well and, if `autoLoad` is enabled, the first page is fetched again.

Types and Interfaces

InfiniteScrollCacheEviction

Eviction policy for the internal page cache.

type InfiniteScrollCacheEviction = "lru" | "fifo";
InfiniteScrollCacheOptions

Cache configuration for fetched pages.

interface InfiniteScrollCacheOptions {
    /** Maximum pages in the active grid window and response cache. 0 disables response caching and leaves rows unbounded. */
    maxPages?: number;
    /** Eviction policy when cache exceeds maxPages. */
    evictionPolicy?: InfiniteScrollCacheEviction;
}
InfiniteScrollState

State of the InfiniteScrollPlugin at any point in time.

interface InfiniteScrollState {
    /** Highest absolute row offset reached by successful page loads. */
    loadedRows: number;
    /** Whether a page fetch is currently in flight. */
    isFetching: boolean;
    /** Whether more data may be available after the active row window. */
    hasMore: boolean;
}