DataGrid

Navigation (normal mode)

Key	Action
↑ / k	Move up one row
↓ / j	Move down one row
← / h	Move left one column
→ / l	Move right one column
Home	Jump to first row
End	Jump to last row
0	Jump to first column
$	Jump to last column
gg	Jump to first row (double-tap g)
G	Jump to last row
Ctrl+D / PgDn	Half-page down
Ctrl+U / PgUp	Half-page up

Editing

Key	Action
i	Enter edit mode (cursor at end)
c	Enter edit mode and clear the cell
e	Open modal edit (for long values)
u	Revert current cell to original value
U / Ctrl+Z	Revert all changes

In edit mode: Enter or Esc commits; Tab commits and moves to the next cell.

Selection and actions

Key	Action
Space	Toggle row selection
V	Clear all row selections
Ctrl+A	Select all rows
y	Copy cell value (fires onCopy)
/	Trigger search (fires onSearch)
Ctrl+S	Submit changeset (fires onSubmit if changes exist)
Enter	Select cell (fires onCellSelect)
Esc / q	Go back (fires onBack)

Changeset tracking

Every edit is recorded in a Changeset. Pass onSubmit to receive the full changeset when the user presses Ctrl+S:

grid.SetOnSubmit(func(cs components.Changeset) {
    for _, change := range cs.Changes() {
        fmt.Printf("row %d col %s: %q → %q\n",
            change.Row, change.Column, change.OldValue, change.NewValue)
    }
})

Changed cells are visually marked; Changeset.HasChanges() returns true when there are pending edits.

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

DataGrid is an advanced virtualized table component with cell-level navigation, inline editing, and changeset tracking. Built on tview.Box with custom rendering, following the same approach as VirtualList.

Constructor func NewDataGrid() *DataGrid

Usage

source := components.NewSliceSource(
  []components.GridColumn{
    {Name: "Name", MinWidth: 10},
    {Name: "Status", Width: 12},
    {Name: "Age", Align: components.AlignRight},
  },
  [][]components.GridCell{
    {{Value: "Alice"}, {Value: "Active"}, {Value: "32"}},
    {{Value: "Bob"}, {Value: "Inactive"}, {Value: "29"}},
  },
)

grid := components.NewDataGrid().
  SetSource(source).
  SetShowRowNumbers(true).
  SetShowHeader(true)
grid.SetOnSubmit(func(cs *components.Changeset) {
  fmt.Println("pending changes:", cs.HasChanges())
})

fmt.Println(grid != nil)

Methods

Method	Signature	Description
ClearRowSelection	func (dg *DataGrid) ClearRowSelection()	ClearRowSelection clears all row selections.
GetCellValue	func (dg *DataGrid) GetCellValue(pos CellPosition) string	GetCellValue returns the display value for a cell, reading through the changeset overlay. If the cell is dirty, returns the modified value; otherwise returns the source value.
GetChangeset	func (dg *DataGrid) GetChangeset() *Changeset	GetChangeset returns the changeset for external inspection.
GetCursor	func (dg *DataGrid) GetCursor() CellPosition	GetCursor returns the current cursor position.
GetCursorRow	func (dg *DataGrid) GetCursorRow() map[string]string	GetCursorRow returns the cursor row as a map of column name to display value (with changeset overlay).
GetCursorRowIndex	func (dg *DataGrid) GetCursorRowIndex() int	GetCursorRowIndex returns the current cursor row index.
GetCursorRowRaw	func (dg *DataGrid) GetCursorRowRaw() map[string]any	GetCursorRowRaw returns the cursor row as a map of column name to RawValue.
GetMode	func (dg *DataGrid) GetMode() GridMode	GetMode returns the current grid mode.
GetSelectedRowIndices	func (dg *DataGrid) GetSelectedRowIndices() []int	GetSelectedRowIndices returns all selected row indices sorted ascending.
GetSelectedRows	func (dg *DataGrid) GetSelectedRows() []map[string]string	GetSelectedRows returns all selected rows as column name to value maps.
GetSelectedRowsRaw	func (dg *DataGrid) GetSelectedRowsRaw() []map[string]any	GetSelectedRowsRaw returns all selected rows as column name to RawValue maps.
Hints	func (dg *DataGrid) Hints() []KeyHint	Hints returns mode-appropriate key hints.
IsRowSelected	func (dg *DataGrid) IsRowSelected(row int) bool	IsRowSelected returns whether the given row is selected.
SelectAllRows	func (dg *DataGrid) SelectAllRows()	SelectAllRows selects all rows.
SetOnBack	func (dg *DataGrid) SetOnBack(fn func()) *DataGrid	SetOnBack sets the callback for the back/escape action.
SetOnCellEdit	func (dg *DataGrid) SetOnCellEdit(fn func(pos CellPosition, oldValue, newValue string)) *DataGrid	SetOnCellEdit sets the callback for when a cell edit is committed.
SetOnCellSelect	func (dg *DataGrid) SetOnCellSelect(fn func(pos CellPosition, cell GridCell)) *DataGrid	SetOnCellSelect sets the callback for when Enter is pressed on a cell.
SetOnChangesetUpdate	func (dg *DataGrid) SetOnChangesetUpdate(fn func(changeset *Changeset)) *DataGrid	SetOnChangesetUpdate sets the callback for changeset modifications.
SetOnCopy	func (dg *DataGrid) SetOnCopy(fn func(value string)) *DataGrid	SetOnCopy sets the callback for copying a cell value (y key).
SetOnCursorMove	func (dg *DataGrid) SetOnCursorMove(fn func(pos CellPosition)) *DataGrid	SetOnCursorMove sets the callback for cursor position changes.
SetOnModalEdit	func (dg *DataGrid) SetOnModalEdit(fn func(pos CellPosition, currentValue string, commit func(string))) *DataGrid	SetOnModalEdit sets the callback for triggering modal (multi-line) editing. The consumer creates a Modal with TextArea and calls commit(newValue) when done.
SetOnModeChange	func (dg *DataGrid) SetOnModeChange(fn func(mode GridMode)) *DataGrid	SetOnModeChange sets the callback for mode transitions.
SetOnRowSelect	func (dg *DataGrid) SetOnRowSelect(fn func(row int, data map[string]string)) *DataGrid	SetOnRowSelect sets the callback that fires when the cursor moves to a new row. Useful for updating preview panels with the current row data.
SetOnSearch	func (dg *DataGrid) SetOnSearch(fn func()) *DataGrid	SetOnSearch sets the callback for the search trigger (/ key).
SetOnSelectionChange	func (dg *DataGrid) SetOnSelectionChange(fn func(rows []int)) *DataGrid	SetOnSelectionChange sets the callback that fires when multi-select changes.
SetOnSubmit	func (dg *DataGrid) SetOnSubmit(fn func(changeset *Changeset)) *DataGrid	SetOnSubmit sets the callback for submitting pending changes. The callback receives the current changeset. After a successful apply, the consumer should call changeset.Clear() to reset dirty state.
SetOverscan	func (dg *DataGrid) SetOverscan(count int) *DataGrid	SetOverscan sets how many rows to pre-fetch outside the visible area.
SetSeparator	func (dg *DataGrid) SetSeparator(sep rune) *DataGrid	SetSeparator sets the column separator character.
SetShowHeader	func (dg *DataGrid) SetShowHeader(show bool) *DataGrid	SetShowHeader enables or disables the column header row.
SetShowRowNumbers	func (dg *DataGrid) SetShowRowNumbers(show bool) *DataGrid	SetShowRowNumbers enables or disables the row number gutter.
SetSource	func (dg *DataGrid) SetSource(source DataGridSource) *DataGrid	SetSource sets the data source for the grid.
Submit	func (dg *DataGrid) Submit()	Submit triggers the submit callback if there are pending changes. Safe to call from external keybindings or buttons.
ToggleRowSelection	func (dg *DataGrid) ToggleRowSelection()	ToggleRowSelection toggles selection of the current cursor row. Safe to call from outside; also callable internally (caller must hold mu).

Types

type CellPosition struct CellPosition identifies a cell in the grid by row and column index.

Field	Type	Description
Row	int
Col	int

type Changeset Changeset tracks all pending cell modifications in a DataGrid. It maintains insertion order for review and supports overlay reads.

type DataGridSource DataGridSource provides data to a DataGrid. Implementations must be safe for concurrent access from Draw() and input handlers.

type GridCell struct GridCell represents a single cell value in the grid.

Field	Type	Description
Value	string	Display string
RawValue	any	Underlying typed value
Status	*theme.Status	Optional status coloring (takes precedence)
ReadOnly	bool	Prevents editing

type GridMode GridMode represents the current interaction mode of the DataGrid.

Constant	Description
GridModeNormal
GridModeEdit

type KeyHint struct KeyHint represents a single key binding hint.

Field	Type	Description
Key	string	e.g., "Enter", "Esc", "Space", "j/k"
Description	string	e.g., "Select", "Close", "Toggle"