listview

Documentation

Overview

Package listview provides virtual scrolling components for Bubble Tea TUI applications.

This package implements efficient rendering for large lists (10,000+ items) by only rendering visible rows within the viewport. Key features:

• Virtual scrolling with O(viewport_height) render complexity
• Keyboard navigation (up/down, pgup/pgdn, home/end)
• Integration with Bubble Tea's viewport and lipgloss styling
• Smooth scrolling with <100ms latency target

Virtual scrolling enables responsive TUI experiences even with massive datasets, ensuring the application starts immediately without pre-rendering all rows.

Index

• type RenderFunc
• type VirtualListModel
  • func NewVirtualListModel[T any](items []T, height, width int, renderFunc RenderFunc[T]) *VirtualListModel[T]
  • func (m *VirtualListModel[T]) GetSelectedItem() *T
  • func (m *VirtualListModel[T]) Height() int
  • func (m *VirtualListModel[T]) Init() tea.Cmd
  • func (m *VirtualListModel[T]) ItemCount() int
  • func (m *VirtualListModel[T]) Selected() int
  • func (m *VirtualListModel[T]) SetSelected(index int)
  • func (m *VirtualListModel[T]) Update(msg tea.Msg) (tea.Model, tea.Cmd)
  • func (m *VirtualListModel[T]) View() tea.View
  • func (m *VirtualListModel[T]) VisibleFrom() int
  • func (m *VirtualListModel[T]) VisibleTo() int
  • func (m *VirtualListModel[T]) Width() int

Types

type RenderFunc

type RenderFunc[T any] func(item T, selected bool) string

RenderFunc is a function that renders an item at a given index. The selected parameter indicates whether this item is currently selected.

type VirtualListModel

type VirtualListModel[T any] struct {
	// contains filtered or unexported fields
}

VirtualListModel implements virtual scrolling for large lists. It renders only the visible portion of the list plus a small buffer, allowing smooth scrolling with 10,000+ items without performance degradation.

func NewVirtualListModel

func NewVirtualListModel[T any](items []T, height, width int, renderFunc RenderFunc[T]) *VirtualListModel[T]

NewVirtualListModel creates a new virtual list model. items: the complete list of items to display. height: viewport height in rows. width: viewport width in columns. renderFunc: function to render each item.

func (*VirtualListModel[T]) GetSelectedItem

func (m *VirtualListModel[T]) GetSelectedItem() *T

GetSelectedItem returns the currently selected item. Returns nil if list is empty.

func (*VirtualListModel[T]) Height

func (m *VirtualListModel[T]) Height() int

Height returns the viewport height.

func (*VirtualListModel[T]) Init

func (m *VirtualListModel[T]) Init() tea.Cmd

Init initializes the model (required for tea.Model interface).

func (*VirtualListModel[T]) ItemCount

func (m *VirtualListModel[T]) ItemCount() int

ItemCount returns the total number of items in the list.

func (*VirtualListModel[T]) Selected

func (m *VirtualListModel[T]) Selected() int

Selected returns the currently selected item index.

func (*VirtualListModel[T]) SetSelected

func (m *VirtualListModel[T]) SetSelected(index int)

SetSelected sets the selected item index, capping to valid bounds.

func (*VirtualListModel[T]) Update

func (m *VirtualListModel[T]) Update(msg tea.Msg) (tea.Model, tea.Cmd)

Update handles keyboard and resize messages.

func (*VirtualListModel[T]) View

func (m *VirtualListModel[T]) View() tea.View

View renders the visible portion of the list with buffer.

func (*VirtualListModel[T]) VisibleFrom

func (m *VirtualListModel[T]) VisibleFrom() int

VisibleFrom returns the first visible item index (inclusive).

func (*VirtualListModel[T]) VisibleTo

func (m *VirtualListModel[T]) VisibleTo() int

VisibleTo returns the last visible item index (exclusive).

func (*VirtualListModel[T]) Width

func (m *VirtualListModel[T]) Width() int

Width returns the viewport width.