list

Documentation

Overview

Package list provides a cursor-driven, optionally filterable list inside a bordered pane. It bundles item storage, cursor tracking, viewport auto- scroll, and a filter.Model together so parents can drop it in with one New + Update + View.

Items are plain []string — callers format their data before passing it in. For filtering, the match is a case-insensitive substring across the item text. Anything richer (fuzzy match, per-field search, struct items) is out of scope and should be composed via pane + filter directly.

Index

• type KeyedItem
• type Model
  • func New(opts Options) Model
  • func (m Model) Cursor() int
  • func (m Model) Filtering() bool
  • func (m Model) Help() []key.Binding
  • func (m Model) Init() tea.Cmd
  • func (m Model) Items() []string
  • func (m Model) Loading() bool
  • func (m Model) Selected() (string, bool)
  • func (m Model) SelectedIndex() (int, bool)
  • func (m Model) SelectedKey() (string, bool)
  • func (m *Model) SetActiveColor(c lipgloss.TerminalColor)
  • func (m *Model) SetCursor(n int)
  • func (m *Model) SetDimensions(w, h int)
  • func (m *Model) SetFocused(b bool)
  • func (m *Model) SetInactiveColor(c lipgloss.TerminalColor)
  • func (m *Model) SetItems(items []string)
  • func (m *Model) SetKeyedItems(items []KeyedItem)
  • func (m *Model) SetLoading(b bool) tea.Cmd
  • func (m *Model) SetLoadingLabel(s string)
  • func (m *Model) SetSelectedColor(c lipgloss.TerminalColor)
  • func (m *Model) SetSpinnerStyle(s lipgloss.Style)
  • func (m *Model) SetTitle(s string)
  • func (m *Model) SetValue(s string)
  • func (m Model) Update(msg tea.Msg) (Model, tea.Cmd)
  • func (m Model) Value() string
  • func (m Model) View() string
  • func (m Model) Visible() []string
• type Options

Types

type KeyedItem

type KeyedItem struct {
	Key     string
	Display string
}

KeyedItem is a list entry with a stable identity. Pass to SetKeyedItems to preserve the cursor across data swaps even when items are reordered or partially replaced — e.g. polled refreshes of a live data set.

type Model

type Model struct {
	// contains filtered or unexported fields
}

Model is the list widget. Embed as a value; mutate via the setters.

func New

func New(opts Options) Model

New constructs a list. Call Update/View from the parent model.

func (Model) Cursor

func (m Model) Cursor() int

Cursor returns the current cursor index into the visible (post-filter) set.

func (Model) Filtering

func (m Model) Filtering() bool

Filtering reports whether the embedded filter currently has focus — callers use this to decide whether to intercept global keys like "q".

func (Model) Help

func (m Model) Help() []key.Binding

Help returns the keys this list responds to. While the embedded filter is focused it returns the filter's keys; otherwise ↑↓ (always) plus "/" when filterable.

func (Model) Init

func (m Model) Init() tea.Cmd

Init satisfies tea.Model — nothing to kick off.

func (Model) Items

func (m Model) Items() []string

Items returns the full unfiltered item set.

func (Model) Loading

func (m Model) Loading() bool

Loading reports whether the list is currently in its loading state.

func (Model) Selected

func (m Model) Selected() (string, bool)

Selected returns the currently highlighted item. ok is false when the visible set (post-filter) is empty.

func (Model) SelectedIndex

func (m Model) SelectedIndex() (int, bool)

SelectedIndex returns the highlighted row's index into the original (pre-filter) Items() slice. ok is false when the visible set is empty.

Use this when list items are formatted display strings rendered from a richer source slice — SelectedIndex identifies which source row is selected, regardless of whether a filter is currently applied. For the row's text, use Selected; for the cursor's position within the filtered view, use Cursor.

func (Model) SelectedKey

func (m Model) SelectedKey() (string, bool)

SelectedKey returns the Key of the currently highlighted item when the list was populated via SetKeyedItems. ok is false when the visible set is empty or when items are anonymous (no keys set).

func (*Model) SetActiveColor

func (m *Model) SetActiveColor(c lipgloss.TerminalColor)

SetActiveColor updates the body pane's active border color. Useful when reacting to a theme swap without rebuilding the model.

func (*Model) SetCursor

func (m *Model) SetCursor(n int)

SetCursor moves the cursor (clamped to the visible range) and scrolls to keep it on screen.

func (*Model) SetDimensions

func (m *Model) SetDimensions(w, h int)

SetDimensions resizes the list in place. When filterable, the internal filter pane consumes 3 rows at the top and the body pane gets the rest; otherwise the body pane takes the full height.

func (*Model) SetFocused

func (m *Model) SetFocused(b bool)

SetFocused sets the body pane's focus state so its border reads as active or inactive. Useful when embedding a list inside a parent that owns focus (e.g. a form field that gates input).

func (*Model) SetInactiveColor

func (m *Model) SetInactiveColor(c lipgloss.TerminalColor)

SetInactiveColor updates the body pane's inactive border color.

func (*Model) SetItems

func (m *Model) SetItems(items []string)

SetItems replaces the item set, re-applies the current filter, and redraws. Clears any per-item keys previously set via SetKeyedItems.

func (*Model) SetKeyedItems

func (m *Model) SetKeyedItems(items []KeyedItem)

SetKeyedItems replaces the item set with keyed entries and snaps the cursor to the previously-selected Key after the swap (falling back to the clamped previous cursor index when the key is gone). Use this for polled refreshes of a live data set so the user's selection survives reordering or partial replacement.

func (*Model) SetLoading

func (m *Model) SetLoading(b bool) tea.Cmd

SetLoading toggles the loading state. When entering, returns the spinner's initial Tick command — propagate it back from your screen's Update so the spinner animates. The list's Update already forwards every msg to the body pane, so subsequent ticks chain automatically.

func (*Model) SetLoadingLabel

func (m *Model) SetLoadingLabel(s string)

SetLoadingLabel updates the text rendered next to the spinner while loading.

func (*Model) SetSelectedColor

func (m *Model) SetSelectedColor(c lipgloss.TerminalColor)

SetSelectedColor updates the foreground color of the highlighted row.

func (*Model) SetSpinnerStyle

func (m *Model) SetSpinnerStyle(s lipgloss.Style)

SetSpinnerStyle updates the lipgloss style applied to the spinner glyph.

func (*Model) SetTitle

func (m *Model) SetTitle(s string)

SetTitle updates the title rendered on the body pane's top border. Useful when the list represents a slice that can change identity at runtime (e.g. "detail · <selection>").

func (*Model) SetValue

func (m *Model) SetValue(s string)

SetValue overwrites the filter text (no-op when not filterable). Useful when rebuilding the list on theme swap / resize — carry the old Value().

func (Model) Update

func (m Model) Update(msg tea.Msg) (Model, tea.Cmd)

Update consumes up/down/j/k and "/" (when filterable); while the filter is focused, every key is forwarded to it. Non-key messages are forwarded to the body pane so spinner ticks reach the loading-state animation.

func (Model) Value

func (m Model) Value() string

Value returns the current filter text ("" when not filterable or empty).

func (Model) View

func (m Model) View() string

View stacks filter (if filterable) and the body pane.

func (Model) Visible

func (m Model) Visible() []string

Visible returns the post-filter items, in display order.

type Options

type Options struct {
	Width, Height int
	// Title sits on the pane's top-left border slot. Defaults to "List".
	Title string
	// Items is the full item set. The list copies this slice so the caller
	// can mutate their source independently.
	Items []string
	// Filterable embeds a filter.Model above the body pane (three rows). If
	// false, "/" is ignored and the full height is used for items.
	Filterable bool

	// Pane pass-throughs. See pkg/pane.Options for defaults.
	ActiveColor    lipgloss.TerminalColor
	InactiveColor  lipgloss.TerminalColor
	ActiveBorder   lipgloss.Border
	InactiveBorder lipgloss.Border
	SlotBrackets   pane.SlotBracketStyle

	// HScrollbar reserves a row at the bottom of the list pane for a
	// horizontal scrollbar and lets ←/h and →/l scroll long rows
	// horizontally. theme.List() enables this by default — disable when
	// items are guaranteed short and the extra row is unwanted.
	HScrollbar bool

	// SelectedColor foregrounds the highlighted row (bold).
	SelectedColor lipgloss.TerminalColor

	// SpinnerStyle is applied to the spinner glyph rendered while the list
	// is in its loading state (see SetLoading). Pass via theme.List() for
	// a sensible default.
	SpinnerStyle lipgloss.Style
	// LoadingLabel is rendered next to the spinner while loading — e.g.
	// "loading cities…".
	LoadingLabel string

	// Filter configures the embedded filter. Ignored when Filterable=false.
	Filter filter.Options
}

Options configures a new list. Zero-value fields fall back to sane defaults where that's meaningful; otherwise the pane/filter defaults apply.