Documentation

Infinite Scroll

StackBlitz

SimpleTable provides built-in infinite scroll functionality that automatically loads more data as users scroll near the bottom of the table. This feature is perfect for handling large datasets without overwhelming the user or degrading performance.

Basic Usage

To enable infinite scroll in your table, follow these steps:

  1. Set a fixed height - Use the height prop to create a scrollable container
  2. Implement the callback - Create an onLoadMore function that fetches additional data
  3. Update state - Append new data to your existing rows array

Infinite Scroll Configuration

PropertyRequiredDescriptionExample
onLoadMore
() => void
Optional
Callback function triggered when user scrolls near the bottom of the table to load more data. Useful for implementing infinite scrolling or paginated data loading.
height
string
Optional
Height of the table container. Use this OR scrollParent to enable scroll detection. With a fixed height the table's own body scrolls; without height the table grows to fit and scrollParent drives the scroll.
infiniteScrollThreshold
number
Optional
Pixel distance from the bottom at which onLoadMore fires. Defaults to 200. Increase for earlier pre-fetching.

How It Works

SimpleTable's infinite scroll implementation:

  • Scroll Detection - Monitors scroll position within the table container
  • Threshold Triggering - Calls onLoadMore when user scrolls within infiniteScrollThreshold pixels of the bottom (default 200px)
  • Debouncing - Prevents multiple simultaneous requests by debouncing the scroll event
  • Smooth Integration - New data is seamlessly appended to the existing table

Window / External Scroll Mode

Want the table to behave like a regular page section — growing to its natural height while the page (or a parent container) scrolls? Drop height / maxHeight and pass scrollParent. The table will:

  • Virtualize against the parent - Only the rows visible inside the parent's viewport are rendered, even with tens of thousands of rows.
  • Fire onLoadMore from the parent's scroll - The threshold check uses the parent's position relative to the table, not the table's own (non-existent) inner scroll.
  • Pin the header automatically - The header sticks to the top of the parent's scroll viewport via CSS position: sticky so it stays visible as users scroll through the rows.
  • Suppress overscroll bounce - Sets overscroll-behavior-y: none on the scroll parent so the rubber-band effect doesn't visually shift the sticky header off the viewport. Restored on unmount.

Window / External Scroll Props

PropertyRequiredDescriptionExample
scrollParent
HTMLElement | "window" | (() => HTMLElement | null)
Optional
Opts the table into window / external scroll mode. When set and neither height nor maxHeight is provided, the table grows to its natural size inside the parent and that parent's scroll position drives both row virtualization and onLoadMore. Accepts an element, the string "window", or a getter (useful for refs that resolve after first render). The header automatically pins to the top of the parent's scroll viewport.

Precedence rules

  • height or maxHeight always win. If either is set, scrollParent is ignored and the table uses its own inner scroll.
  • Without scrollParent and without height, all rows render (no virtualization, no infinite scroll).
  • enableStickyParents (for grouped row parents) works in external scroll mode too — pinned parent rows stay just under the sticky header as you scroll past their children.

Padding on the scroll parent

If your scroll parent has padding-top, the table reads it and offsets the sticky header so it pins flush to the parent's outer top edge instead of sitting beneath the padding. No extra config required.