class RatatuiRuby::Widgets::Table

Displays structured data in rows and columns.

Data is often multidimensional. You need to show relationships between fields (Name, Age, ID). Aligning columns manually in a monospaced environment is painful and error-prone.

This widget creates a grid. It enforces column widths using constraints. It renders headers, rows, and footers aligned perfectly.

Use it to display database records, logs, or file lists.

Example

Run the interactive demo from the terminal:

ruby examples/widget_table/app.rb

Constants

FLEX_CENTER: Flex: center columns.
FLEX_END: Flex: align columns to end.
FLEX_LEGACY: Flex: use legacy column sizing.
FLEX_SPACE_AROUND: Flex: space around columns.
FLEX_SPACE_BETWEEN: Flex: space between columns.
FLEX_SPACE_EVENLY: Flex: space evenly between columns.
FLEX_START: Flex: align columns to start.
HIGHLIGHT_ALWAYS: Highlight spacing: always show the spacing column.
HIGHLIGHT_NEVER: Highlight spacing: never show the spacing column.
HIGHLIGHT_WHEN_SELECTED: Highlight spacing: show spacing only when a row is selected (default).

Attributes

block [R]

Optional wrapping block.

cell_highlight_style [R]

Style for the selected cell (intersection of row and column).

column_highlight_style [R]

Style for the selected column.

column_spacing [R]

Spacing between columns (Integer, default 1).

flex [R]

Flex mode for column distribution.

header [R]

Header row content (Array of Strings, Text::Spans, Text::Lines, or Paragraphs).

highlight_spacing [R]

When to show the highlight symbol column (:always, :when_selected, :never).

highlight_symbol [R]

Symbol for the selected row.

offset [R]

Scroll offset (Integer or nil).

Controls the viewport’s starting row position in the table.

When nil (default), Ratatui auto-scrolls to keep the selection visible (“natural scrolling”).

When set, forces the viewport to start at this row index. Use this for:

**Passive scrolling**: Scroll through a log table without selecting rows.
**Click-to-select math**: Calculate which row index corresponds to a click coordinate.

Important: When both offset and selected_row are set, Ratatui may still adjust the viewport during rendering to ensure the selection stays visible. Set selected_row to nil for fully manual scroll control.

row_highlight_style [R]

Style for the selected row.

rows [R]

Data rows (Array of Arrays). Each cell can be String, Text::Span, Text::Line, Paragraph, or Cell.

selected_column [R]

Index of the selected column (Integer or nil).

selected_row [R]

Index of the selected row (Integer or nil).

style [R]

Base style for the entire table.

widths [R]

Column width constraints (Array of Constraint or Integer). Integers are automatically coerced to Constraint.length.

Public Class Methods

new (header: nil, rows: [], widths: [], row_highlight_style: nil, highlight_symbol: "> ", highlight_spacing: :when_selected, column_highlight_style: nil, cell_highlight_style: nil, selected_row: nil, selected_column: nil, offset: nil, block: nil, footer: nil, flex: :legacy, style: nil, column_spacing: 1)

Source

# File lib/ratatui_ruby/widgets/table.rb, line 156
def initialize(header: nil, rows: [], widths: [], row_highlight_style: nil, highlight_symbol: "> ", highlight_spacing: :when_selected, column_highlight_style: nil, cell_highlight_style: nil, selected_row: nil, selected_column: nil, offset: nil, block: nil, footer: nil, flex: :legacy, style: nil, column_spacing: 1)
  coerced_widths = widths.map do |w|
    w.is_a?(Integer) ? Layout::Constraint.length(w) : w
  end

  super(
    header:,
    rows:,
    widths: coerced_widths,
    row_highlight_style:,
    highlight_symbol:,
    highlight_spacing:,
    column_highlight_style:,
    cell_highlight_style:,
    selected_row: selected_row.nil? ? nil : Integer(selected_row),
    selected_column: selected_column.nil? ? nil : Integer(selected_column),
    offset: offset.nil? ? nil : Integer(offset),
    block:,
    footer:,
    flex:,
    style:,
    column_spacing: Integer(column_spacing)
  )
end

Creates a new Table.

header: Array of strings, Text::Spans, Text::Lines, or paragraphs.
rows: 2D Array where each cell is String, Text::Span, Text::Line, Paragraph, or Cell.
widths: Array of Constraints or Integers (integers coerce to Constraint.length).
row_highlight_style: Style object.
highlight_symbol: String.
highlight_spacing: Symbol (optional, default: :when_selected).
column_highlight_style: Style object.
cell_highlight_style: Style object.
selected_row: Integer (nullable).
selected_column: Integer (nullable).
offset: Numeric (nullable, coerced to Integer). Forces scroll position when set.
block: Block (optional).
footer: Array of strings/paragraphs (optional).
flex: Symbol (optional, default: :legacy).
style: Style object or Hash (optional).
column_spacing: Integer (optional, default: 1).

Calls superclass method

Public Instance Methods

cell_selected? ()

Source

# File lib/ratatui_ruby/widgets/table.rb, line 198
def cell_selected?
  row_selected? && column_selected?
end

Returns true if both a row and column are selected (a cell is selected).

@return [Boolean]

column_selected? ()

Source

# File lib/ratatui_ruby/widgets/table.rb, line 191
def column_selected?
  !selected_column.nil?
end

Returns true if a column is selected.

@return [Boolean]

empty? ()

Source

# File lib/ratatui_ruby/widgets/table.rb, line 205
def empty?
  rows.empty?
end

Returns true if the table has no rows.

@return [Boolean]

row_selected? ()

Source

# File lib/ratatui_ruby/widgets/table.rb, line 184
def row_selected?
  !selected_row.nil?
end

Returns true if a row is selected.

@return [Boolean]