VirtualList

virtual-list

Renders only visible rows from large lists while preserving scroll position.

Usage

Set the height to 10,000 lines

itemHeight passes the number (fixed height), and only renders the + overscan line in the viewport to support the total height.

Data row 1#0

Data row 2#1

Data row 3#2

Data row 4#3

Data row 5#4

Data row 6#5

Data row 7#6

Data row 8#7

Data row 9#8

Data row 10#9

Data row 11#10

Data row 12#11

Data row 13#12

tsx

<VirtualList
  items={rows}
  itemHeight={44}
  height={320}
  getKey={(r) => r.id}
  renderItem={(r) => <Row data={r} />}
/>

Increased estimate

itemHeight passes (index) => px to make estimates and automatically correct the actual measurements.

Data row 1#0

Data row 2#1

Data row 3#2

Data row 4#3

Data row 5#4

Data row 6#5

Data row 7#6

Data row 8#7

Data row 9#8

Data row 10#9

Data row 11#10

tsx

<VirtualList
  items={rows}
  itemHeight={(i) => (i % 3 === 0 ? 72 : 44)}
  height={320}
  getKey={(r) => r.id}
  renderItem={(r) => <Row data={r} />}
/>

When to use

Use VirtualList when thousands of rows make full DOM rendering slow; it keeps only the visible region and its overscan mounted. Use onReachEnd for pagination. For moderate lists that only need bottom-triggered loading, use InfiniteScroll.

Import

import { VirtualList } from "@hulianui/ui"

Props

Name	Type	Default	Description
items*	`T[]`	—	Generic data array.
itemHeight*	`number\|((index: number) => number)`	—	Fixed height in pixels or an estimated-height function for measured variable rows.
height	`number\|string`	`360`	Viewport height in pixels or as a CSS length.
overscan	`number`	`5`	Number of off-screen rows to pre-render.
getKey	`(item: T, index: number) => string\|number`	Array index	Extracts a stable row key.
className	`string`	—	Custom class name.

Events

Event	Type	Description
onReachEnd	`() => void`	Fires when the last row enters the viewport.

Slots

Slot	Type	Description
renderItem*	`(item: T, index: number) => ReactNode`	Renders a row.

Pitfalls

When itemHeight is a function, its result is an estimate corrected by measureElement; better estimates reduce initial layout movement. Keep getKey stable when variable-height content changes so measurement caches remain aligned.

Table · Book3D · ProTable · PricingTable · JsonViewer · EditableTable

Usage

Set the height to 10,000 lines

itemHeight passes the number (fixed height), and only renders the + overscan line in the viewport to support the total height.

Data row 1#0

Data row 2#1

Data row 3#2

Data row 4#3

Data row 5#4

Data row 6#5

Data row 7#6

Data row 8#7

Data row 9#8

Data row 10#9

Data row 11#10

Data row 12#11

Data row 13#12

tsx

<VirtualList
  items={rows}
  itemHeight={44}
  height={320}
  getKey={(r) => r.id}
  renderItem={(r) => <Row data={r} />}
/>

Increased estimate

itemHeight passes (index) => px to make estimates and automatically correct the actual measurements.

Data row 1#0

Data row 2#1

Data row 3#2

Data row 4#3

Data row 5#4

Data row 6#5

Data row 7#6

Data row 8#7

Data row 9#8

Data row 10#9

Data row 11#10

tsx

<VirtualList
  items={rows}
  itemHeight={(i) => (i % 3 === 0 ? 72 : 44)}
  height={320}
  getKey={(r) => r.id}
  renderItem={(r) => <Row data={r} />}
/>

Props

Name	Type	Default	Description
items*	`T[]`	—	Generic data array.
itemHeight*	`number\|((index: number) => number)`	—	Fixed height in pixels or an estimated-height function for measured variable rows.
height	`number\|string`	`360`	Viewport height in pixels or as a CSS length.
overscan	`number`	`5`	Number of off-screen rows to pre-render.
getKey	`(item: T, index: number) => string\|number`	Array index	Extracts a stable row key.
className	`string`	—	Custom class name.

Event

Type

Description

onReachEnd

() => void

Fires when the last row enters the viewport.

Slot

Type

Description

renderItem*

(item: T, index: number) => ReactNode

Renders a row.

VirtualList

Usage

Set the height to 10,000 lines

Increased estimate

When to use

Import

Props

Events

Slots

Pitfalls

Related

VirtualList

Usage

Set the height to 10,000 lines

Increased estimate

When to use

Import

Props

Events

Slots

Pitfalls

Related