Documentation
¶
Overview ¶
Package list is a scrollable, single-selection list of pre-rendered rows. Its defining property is that the selected item (cursor) is tracked independently of the scroll offset: moving the cursor adjusts the offset only enough to keep the selection visible, and a resize never loses the selection. Rows are opaque strings, so the component is decoupled from how a caller styles them - it owns only the selection/scroll math and an optional scrollbar.
WithSearch adds a type-to-filter line above the rows: typing narrows the list fzf-style (every printable key feeds the filter, arrows navigate), and the caller reads Model.Selected on its own submit key - the list never consumes enter or esc. Matching is a case-insensitive substring test against each row's visible (ANSI-stripped) text, and selection reports the original row index, so the caller keeps its own parallel value slice.
Index ¶
- type Model
- func (m *Model) Bottom()
- func (m *Model) Cursor() int
- func (m *Model) CursorLine() int
- func (m *Model) Len() int
- func (m *Model) MoveDown(n int)
- func (m *Model) MoveUp(n int)
- func (m *Model) PageDown()
- func (m *Model) PageUp()
- func (m *Model) Selected() (int, bool)
- func (m *Model) SetCursor(i int)
- func (m *Model) SetRows(rows []string)
- func (m *Model) SetSize(width, height int)
- func (m *Model) Top()
- func (m *Model) Update(msg tea.Msg) tea.Cmd
- func (m *Model) View() string
- func (m *Model) VisibleRange() (int, int)
- type Option
- type Styles
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Model ¶
type Model struct {
// Styles style the cursor row and placeholders.
Styles Styles
// Scrollbar draws a proportional scrollbar column when the list overflows.
Scrollbar bool
// contains filtered or unexported fields
}
Model is a list viewport over caller-rendered rows.
func New ¶
New returns a list with a sensible default cursor highlight. It returns a pointer because every mutating method has a pointer receiver.
func (*Model) Cursor ¶
Cursor returns the original index of the selected row, or -1 when nothing is selectable (the list is empty, or a search filter matches nothing).
func (*Model) CursorLine ¶
CursorLine returns the cursor row's line offset within View - the filter line, when showing, counts as a line above it - or -1 when nothing is selectable. It is the region a dialog scroll hint reports so an outer viewport keeps the selection visible when a taller-than-the-box list scrolls inside it.
func (*Model) PageDown ¶
func (m *Model) PageDown()
PageDown moves the cursor down by a viewport height.
func (*Model) Selected ¶
Selected returns the original index of the row under the cursor; ok is false when nothing is selectable.
func (*Model) SetCursor ¶
SetCursor selects visible position i (equal to the row index when no filter is active), clamping to range and scrolling it into view.
func (*Model) SetRows ¶
SetRows replaces the rows, refilters when searching, and clamps the cursor/offset to the new length so the selection stays valid (and visible) when the data shrinks.
func (*Model) SetSize ¶
SetSize sets the viewport dimensions and reclamps so the cursor stays visible. height is the total view height: when the filter line is showing, one row of it goes to the filter.
func (*Model) Update ¶
Update routes messages when searching: up/down move the cursor and everything else (typing, paste, cursor movement inside the filter) goes to the filter input. Arrow keys match on Code, not String(), so modified arrows keep working; every printable key belongs to the filter (fzf semantics), so letter aliases like j/k are deliberately not navigation here. Enter and esc are deliberately not handled - submit/cancel belong to the caller. Without search, Update is a no-op: the caller drives the cursor through the Move methods.
func (*Model) View ¶
View renders the filter line (once the user typed something) and the visible rows, highlighting the cursor row and appending a scrollbar column when the list overflows and Scrollbar is enabled. Rows are padded/truncated to the content width (viewport width minus the scrollbar column) so the cursor highlight spans the full row and the output never exceeds the declared width.
func (*Model) VisibleRange ¶
VisibleRange returns the [start, end) visible-list positions currently on screen.
Source Files