VirtualizedList Stable WINMACLNX

A high-performance list that only renders the rows visible on screen (plus a configurable overscan buffer). For lists of 100+ items where ScrollView becomes sluggish.

Import

import { VirtualizedList } from 'veloxkit'

Basic usage

import { VirtualizedList, View, Text } from 'veloxkit'
 
const ITEM_HEIGHT = 56
 
function ContactList({ contacts }: { contacts: Contact[] }) {
  return (
    <VirtualizedList
      data={contacts}
      itemHeight={ITEM_HEIGHT}
      height={600}
      width={400}
      keyExtractor={(item) => String(item.id)}
      renderItem={({ item }) => (
        <View style={{ height: ITEM_HEIGHT, paddingHorizontal: 16, justifyContent: 'center' }}>
          <Text style={{ fontSize: 15 }}>{item.name}</Text>
          <Text style={{ fontSize: 12, color: '#888' }}>{item.email}</Text>
        </View>
      )}
    />
  )
}

itemHeight must be a fixed number — all rows must be the same height. Variable-height lists are not yet supported.

Props

Prop	Type	Default	Description
`data`	`T[]`	—	Array of items to render
`renderItem`	`({ item: T, index: number }) => ReactNode`	—	Called for each visible item
`itemHeight`	`number`	—	Required. Fixed height of each row in pixels
`height`	`number`	—	Required. Visible height of the list container
`width`	`number`	—	Width of the container and each row
`keyExtractor`	`(item: T, index: number) => string`	`String(index)`	Unique key for each row
`overscan`	`number`	`5`	Extra rows to render above and below the visible window
`showScrollbar`	`boolean`	`true`	Show the scroll indicator
`scrollbarWidth`	`number`	`8`	Width of the scrollbar in pixels
`scrollbarColor`	`string`	`'#8c8caa99'`	Scrollbar color (hex or rgba string)
`style`	`ViewStyle`	—	Additional styles for the container

Scrolling to a row

Use a ref to scroll programmatically:

import { VirtualizedList, VirtualizedListRef } from 'veloxkit'
import { useRef } from 'react'
 
function MyList({ items }) {
  const listRef = useRef<VirtualizedListRef>(null)
 
  function scrollToBottom() {
    listRef.current?.scrollToIndex(items.length - 1)
  }
 
  return (
    <VirtualizedList
      ref={listRef}
      data={items}
      itemHeight={48}
      height={400}
      width={320}
      renderItem={({ item }) => <Row item={item} />}
    />
  )
}

When to use VirtualizedList vs ScrollView

	`ScrollView`	`VirtualizedList`
Renders all children at once	Yes	No — only visible rows
Suitable for 100+ items	No	Yes
Variable-height children	Yes	No
Programmatic scroll	`scrollTo`	`scrollToIndex`

Use ScrollView for content with mixed sizes (paragraphs, cards, images). Use VirtualizedList for long uniform lists (contacts, messages, log entries, table rows).

Performance notes

Keep renderItem fast — it's called on every frame during scroll for newly-visible rows.
itemHeight must match the actual rendered height. A mismatch causes items to overlap or leave gaps.
Increase overscan if you see brief blank rows during fast flings (at the cost of slightly more renders).

RepaintBoundary Checkbox