Vesture
Get Started

Data

VirtualListNew in 0.8.0

A windowed list for huge or endlessly loading data. Rows can be a fixed height, individually known, or measured after render.

VirtualList

Preview

Item 1
Item 2
Item 3
Item 4
Item 5
Item 6
Item 7
Item 8
Item 9
Item 10
Item 11
Item 12
Item 13
Item 14

Only the rows near the viewport are mounted.

Usage

tsx
import { VirtualList } from "@vesture/react";

<VirtualList
  items={rows}
  height={360}
  itemHeight={36}
  getKey={(r) => r.id}
  renderItem={(r) => <div>{r.text}</div>}
  onEndReached={loadMore}
  loading={isLoading}
/>

Behavior

  • Only the rows in (and just around) the viewport are mounted, so 100,000 items stay cheap.
  • Omit itemHeight to measure rows with ResizeObserver, starting from estimateItemHeight — ideal for wrapping text.
  • onEndReached fires once near the bottom and re-arms when items grows. It is suppressed while loading is true.
  • Attach a ref for scrollToIndex(index, align) and scrollToTop().

Props

PropTypeDefaultDescription
items / renderItemT[] / (item, index) => ReactNode—Required.
heightnumber—Required. Viewport height in px.
itemHeightnumber | (item, index) => number—Fixed or known heights. Omit to measure.
estimateItemHeight / gap / overscannumber44 / 0 / 4Layout tuning.
getKey(item, index) => string | number—Stable keys (also used to cache measured heights).
onEndReached / endReachedThreshold() => void / number– / 200Infinite-scroll hook.
loading / loadingIndicator / emptyStateboolean / ReactNode—Status rows.