List

Key bindings

List uses the underlying tview.List bindings:

Key	Action
↑ / ↓	Move selection
Home / End	First / last item
PgUp / PgDn	Page scroll
Enter	Activate item

For large datasets (thousands of items) or when item height varies, use VirtualList instead — it virtualizes rendering so only visible rows are drawn.

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

List is a simple list component with selection support. It wraps tview.List with themed defaults and a cleaner API.

Constructor func NewList() *List

Usage

list := components.NewList().
  AddItem("First").
  AddItemWithSecondary("Second", "with detail").
  AddItems("Third", "Fourth").
  SetShowSecondary(true).
  SetWrapAround(true).
  SetHighlightFullLine(true)
list.SetOnSelect(func(index int, item components.ListItem) {
  fmt.Println("selected:", item.Text)
})

fmt.Println(list != nil)

Methods

Method	Signature	Description
AddItem	func (l *List) AddItem(text string) *List	AddItem adds an item to the list.
AddItemWithRef	func (l *List) AddItemWithRef(text string, ref any) *List	AddItemWithRef adds an item with a reference object.
AddItemWithSecondary	func (l *List) AddItemWithSecondary(text, secondary string) *List	AddItemWithSecondary adds an item with secondary text.
AddItems	func (l *List) AddItems(texts ...string) *List	AddItems adds multiple items at once.
Clear	func (l *List) Clear() *List	Clear removes all items.
GetItem	func (l *List) GetItem(index int) (ListItem, bool)	GetItem returns the item at the given index.
GetItemCount	func (l *List) GetItemCount() int	GetItemCount returns the number of items.
GetItems	func (l *List) GetItems() []ListItem	GetItems returns all items.
GetSelected	func (l *List) GetSelected() (int, ListItem, bool)	GetSelected returns the currently selected item.
MoveDown	func (l *List) MoveDown()	MoveDown moves the selection down.
MoveToBottom	func (l *List) MoveToBottom()	MoveToBottom moves the selection to the last item.
MoveToTop	func (l *List) MoveToTop()	MoveToTop moves the selection to the first item.
MoveUp	func (l *List) MoveUp()	MoveUp moves the selection up.
Primitive	func (l *List) Primitive() *tview.List	Primitive returns the underlying tview.List for advanced usage.
SetHighlightFullLine	func (l *List) SetHighlightFullLine(full bool) *List	SetHighlightFullLine enables or disables full-line highlighting.
SetItems	func (l *List) SetItems(items []ListItem) *List	SetItems replaces all items.
SetOnChange	func (l *List) SetOnChange(handler func(index int, item ListItem)) *List	SetOnChange sets the handler called when the selection changes (navigation).
SetOnSelect	func (l *List) SetOnSelect(handler func(index int, item ListItem)) *List	SetOnSelect sets the handler called when an item is selected (Enter pressed).
SetSelected	func (l *List) SetSelected(index int) *List	SetSelected sets the selected item by index.
SetShowSecondary	func (l *List) SetShowSecondary(show bool) *List	SetShowSecondary enables or disables secondary text display.
SetWrapAround	func (l *List) SetWrapAround(wrap bool) *List	SetWrapAround enables or disables wrap-around navigation.

Types

type ListItem struct ListItem represents an item in a List.

Field	Type	Description
Text	string
Secondary	string	Optional secondary text
Reference	any	Optional reference data