TermUI.Widgets.Table (TermUI v1.0.0)

View Source

Table widget for displaying tabular data.

Table provides efficient display of large datasets with virtual scrolling, column sorting, row selection, and flexible column layout.

Usage

Table.new(
  columns: [
    Column.new(:name, "Name"),
    Column.new(:age, "Age", width: Constraint.length(10), align: :right)
  ],
  data: [
    %{name: "Alice", age: 30},
    %{name: "Bob", age: 25}
  ],
  on_select: fn selected -> IO.inspect(selected) end
)

Features

  • Virtual Scrolling: Efficiently handles 10,000+ rows
  • Column Layout: Fixed, proportional, and percentage widths
  • Selection: Single or multi-selection with keyboard/mouse
  • Sorting: Click headers to sort ascending/descending
  • Custom Rendering: Format cells with render functions

Selection Modes

  • :none - No selection allowed
  • :single - One row at a time
  • :multi - Multiple rows with Ctrl/Shift+click

Keyboard Navigation

  • Arrow keys: Move selection
  • Page Up/Down: Scroll by page
  • Home/End: Jump to first/last row
  • Enter: Confirm selection
  • Space: Toggle selection (multi mode)

Summary

Types

selection_mode()
sort_direction()

Functions

clear_selection(state)

Clears the current selection.

get_selected(state)

Backwards-compatible alias for get_selection/1.

get_selection(state)

Gets the current selection.

new(opts)

Creates a new Table widget.

scroll_to(state, index)

Scrolls to a specific row index.

set_data(state, data)

Replaces the table data and preserves table state as much as possible.

set_selection(state, indices)

Sets the selection programmatically.

sort_by(state, column_key, direction)

Sorts table by a column.

toggle_sort(state, column_key)

Toggles sort on a column.

total_count(state)

Gets the total row count.

visible_count(state)

Gets the visible row count.

Types

selection_mode()

@type selection_mode() :: :none | :single | :multi

sort_direction()

@type sort_direction() :: :asc | :desc | nil

Functions

clear_selection(state)

@spec clear_selection(map()) :: map()

Clears the current selection.

get_selected(state)

@spec get_selected(map()) :: [map()]

Backwards-compatible alias for get_selection/1.

get_selection(state)

@spec get_selection(map()) :: [map()]

Gets the current selection.

Returns

List of selected row data.

new(opts)

@spec new(keyword()) :: map()

Creates a new Table widget.

Options

  • :columns - List of Column specs (required)
  • :data - List of row maps (required)
  • :selection_mode - :none, :single, or :multi (default: :single)
  • :sortable - Enable sorting (default: true)
  • :on_select - Callback when selection changes
  • :on_sort - Callback when sort changes
  • :header_style - Style for header row
  • :row_style - Style for data rows
  • :selected_style - Style for selected rows
  • :alternating - Alternating row backgrounds (default: false)

scroll_to(state, index)

@spec scroll_to(map(), non_neg_integer()) :: map()

Scrolls to a specific row index.

set_data(state, data)

@spec set_data(map(), [map()]) :: map()

Replaces the table data and preserves table state as much as possible.

The cursor, selection, and scroll offset are clamped to the new row count, and the current sort is re-applied.

set_selection(state, indices)

@spec set_selection(map(), [non_neg_integer()]) :: map()

Sets the selection programmatically.

Parameters

  • state - Current table state
  • indices - List of row indices to select

Returns

Updated state with new selection.

sort_by(state, column_key, direction)

@spec sort_by(map(), atom(), sort_direction()) :: map()

Sorts table by a column.

Parameters

  • state - Current table state
  • column_key - Column key to sort by
  • direction - :asc, :desc, or nil to clear

Returns

Updated state with sorted data.

toggle_sort(state, column_key)

@spec toggle_sort(map(), atom()) :: map()

Toggles sort on a column.

Cycles through: nil -> :asc -> :desc -> nil

total_count(state)

@spec total_count(map()) :: non_neg_integer()

Gets the total row count.

visible_count(state)

@spec visible_count(map()) :: non_neg_integer()

Gets the visible row count.