Table¶

pkg/table is a cursor-driven table of records inside a pane: a pinned header, sortable columns, fixed / content-sized / flex widths, a filter with column-scoped and regex terms, multi-select, row activity, and remote paging where scrolling is the pagination.

┌ Cities ────────────────────────────────────────┐
│/                                               │
│─────────────────────────────────────────────── │
│City ▲               │ Region     │  Population │
│─────────────────────────────────────────────── │
│Lima                 │ Americas   │       10.0M │
│London               │ Europe     │        8.9M │
│Madrid               │ Europe     │        3.3M │
│Nairobi              │ Africa     │        4.4M │
│Tokyo                │ Asia       │       13.9M │
│                                                │
└ 5 / 5 ────────────────────────────────── 1 / 5 ┘

Usage¶

opts := t.Table()
opts.Title = "Cities"
opts.Filterable = true
opts.Columns = []table.Column{
    {Title: "City", Flex: 1, Sortable: true},
    {Title: "Region", Width: 10, Sortable: true},
    {Title: "Population", Width: 11, Align: lipgloss.Right, Sortable: true, Less: popLess},
}
opts.Rows = []table.Row{{"London", "Europe", "8.9M"}, {"Tokyo", "Asia", "13.9M"}}
s.table = table.New(opts)

if s.table.IsActivate(msg) {
    if row, ok := s.table.Selected(); ok {
        return s, screen.Push(newCityDetail(row[0], s.t))
    }
}

Options¶

Columns¶

When the table is narrower than the base widths, flex columns don't grow and the overflow goes to horizontal scroll. Widths recompute on row, column and size changes.

Borders¶

Borders{Vertical, HeaderRule} are pre-styled glyph strings. Vertical replaces the column gap with " <glyph> "; HeaderRule repeats its glyph under the header. Style them with ansi.CellColor (foreground-only) so the selected row's background passes through. Empty strings disable them.

Colored cells¶

Color cell text with ansi.CellColor(n, text), not lipgloss.Render: a full \x1b[0m reset inside a cell breaks the selected row's background. ansi.Hyperlink(url, label) makes a cell open a URL on shift/cmd-click even when truncated. See pkg/ansi.

Keys¶

Mouse: click a row to select, double-click to activate, click a header to sort by it, wheel to move, click the ✓ gutter to toggle a mark, shift+click for a range.

Filter syntax¶

The filter splits on whitespace into AND-ed terms:

An ambiguous or unknown key is treated as literal text, as is a regex that doesn't compile, so the filter never refuses input. While typing a key:value term, the filter's bottom-left slot lists that column's matching values and tab completes to their longest common prefix. The grammar lives in pkg/query.

Data and selection¶

KeyedRow is {Key string; Cells []string; Data any}.

Remote data¶

table.Answer{Raw, Sort, Desc} names the query a set of rows answers. Prefer pkg/remote, which does all of this for you.

Messages¶

Filters are reported on commit (enter, esc or blur), never per keystroke.

Multi-select and activity¶

Same surface as List: Selection(), SelectionLabel(), Marks(), SetMarks, ToggleMark, MarkRange, ToggleMarkAll, ClearMarks, MarkCount; and Dispatch, DispatchEach, Done, BeginRead, ApplyRead, ReadsFailing. Marking needs SetKeyedRows and is inert under SetWindow.

State¶

State() / Restore(st) carry rows (a window, a span or the whole set), cursor, scroll, filter, sort (committed and staged), marks, activity, the answered query, failure, completion values and loading.

See examples/components/table, examples/patterns/remote, examples/patterns/multiselect and examples/components/metrics.