VirtualList

Key bindings

Key	Action
↑ / k	Move up one item
↓ / j	Move down one item
Home / g	Jump to first item
End / G	Jump to last item
PgUp	Page up
PgDn	Page down
Ctrl+U	Half-page up
Ctrl+D	Half-page down
Enter	Select item (fires onSelect)

When to use

Use VirtualList when your list can have thousands of rows or when items are loaded lazily. For small, static lists with no dynamic loading, the simpler List component is sufficient.

Data model

Provide a total count and an item-fetch function — VirtualList calls the function only for rows in the visible viewport:

vl := components.NewVirtualList()
vl.SetTotalCount(len(items))
vl.SetItemFunc(func(index int) *components.VirtualItem {
    return &components.VirtualItem{Label: items[index].Name}
})

catppuccin-frappecatppuccin-lattecatppuccin-macchiatocatppuccin-mochadraculadracula-lighteverforest-darkeverforest-lightgithub-darkgithub-lightgruvbox-darkgruvbox-lightkanagawamonokainordonedarkonelightrosepinerosepine-dawnrosepine-moonsolarized-darksolarized-lighttokyonight-daytokyonight-moontokyonight-nighttokyonight-storm

VirtualList renders large lists efficiently by drawing only the rows in the visible viewport. Supply items up-front via SetItems or on-demand via SetFetchFunc for paginated or lazy-loaded data.

Constructor func NewVirtualList() *VirtualList

Usage

items := make([]string, 10000)
for i := range items {
  items[i] = fmt.Sprintf("row %d", i)
}

vl := components.NewVirtualList().
  SetTotalCount(len(items)).
  SetShowScrollbar(true).
  SetShowIndex(true).
  SetOverscan(4)

vl.SetRenderFunc(func(index int, item components.VirtualListItem, width int, selected bool) string {
  return items[index]
})

fmt.Println(vl != nil)

Methods

Method	Signature	Description
Clear	func (v *VirtualList) Clear()	Clear removes all items
GetItem	func (v *VirtualList) GetItem(index int) *VirtualListItem	GetItem returns item at index (may trigger fetch)
GetSelectedIndex	func (v *VirtualList) GetSelectedIndex() int	GetSelectedIndex returns the currently selected index
GetSelectedItem	func (v *VirtualList) GetSelectedItem() *VirtualListItem	GetSelectedItem returns the currently selected item
GetTotalCount	func (v *VirtualList) GetTotalCount() int	GetTotalCount returns total number of items
GetVisibleRange	func (v *VirtualList) GetVisibleRange() (start, end int)	GetVisibleRange returns currently visible index range
Refresh	func (v *VirtualList) Refresh()	Refresh re-fetches visible items and redraws
ScrollTo	func (v *VirtualList) ScrollTo(index int)	ScrollTo scrolls to show a specific index
ScrollToBottom	func (v *VirtualList) ScrollToBottom()	ScrollToBottom scrolls to the last item
ScrollToTop	func (v *VirtualList) ScrollToTop()	ScrollToTop scrolls to the first item
SetDefaultItemHeight	func (v *VirtualList) SetDefaultItemHeight(height int) *VirtualList	SetDefaultItemHeight sets height for items (default 1)
SetFetchFunc	func (v *VirtualList) SetFetchFunc(fn FetchFunc) *VirtualList	SetFetchFunc sets the lazy loading function
SetItems	func (v *VirtualList) SetItems(items []VirtualListItem) *VirtualList	SetItems sets all items directly (for smaller lists)
SetOnChange	func (v *VirtualList) SetOnChange(fn func(index int, item VirtualListItem)) *VirtualList	SetOnChange is called when selection changes
SetOnScrollEnd	func (v *VirtualList) SetOnScrollEnd(fn func()) *VirtualList	SetOnScrollEnd is called when scrolled to the end
SetOnSelect	func (v *VirtualList) SetOnSelect(fn func(index int, item VirtualListItem)) *VirtualList	SetOnSelect is called when Enter is pressed on an item
SetOverscan	func (v *VirtualList) SetOverscan(count int) *VirtualList	SetOverscan sets how many items to render outside visible area
SetPageSize	func (v *VirtualList) SetPageSize(size int) *VirtualList	SetPageSize sets items per page for PgUp/PgDn
SetRenderFunc	func (v *VirtualList) SetRenderFunc(fn RenderFunc) *VirtualList	SetRenderFunc sets the custom render function
SetSelectedID	func (v *VirtualList) SetSelectedID(id string) *VirtualList	SetSelectedID sets selection by item ID
SetSelectedIndex	func (v *VirtualList) SetSelectedIndex(index int) *VirtualList	SetSelectedIndex sets selection by index
SetShowIndex	func (v *VirtualList) SetShowIndex(show bool) *VirtualList	SetShowIndex shows item index/number
SetShowScrollbar	func (v *VirtualList) SetShowScrollbar(show bool) *VirtualList	SetShowScrollbar enables/disables scrollbar
SetTotalCount	func (v *VirtualList) SetTotalCount(count int) *VirtualList	SetTotalCount sets the total number of items (for lazy loading)

Types

type FetchFunc FetchFunc loads items on demand - start: index of first item to load - count: number of items to load Returns the items and total count

type RenderFunc RenderFunc renders a single item - index: item index in the list - item: the item data - width: available width - selected: whether this item is selected Returns the string to display

type VirtualListItem struct VirtualListItem is a single row in a VirtualList. Height > 1 lets an item span multiple terminal rows; the RenderFunc receives the same width for all rows.

Field	Type	Description
ID	string	Unique identifier
Data	any	User data
Height	int	Item height in rows (default 1)