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 '@glyx-dev/react'

Basic usage

import { VirtualizedList, View, Text } from '@glyx-dev/react'
 
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

⚠️

There's no ref/imperative API — VirtualizedList isn't wrapped in forwardRef and has no scrollToIndex or any other programmatic-scroll method. Neither does ScrollView. Scroll position is driven entirely by user input (wheel/drag/scrollbar); there's currently no way to scroll to a row or offset from JS.

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	Not supported	Not supported

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 Popover