class RatatuiRuby::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_flex/app.rb

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).

highlight_spacing [R]

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

highlight_style [R]

Style for the selected row.

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.

rows [R]

Data rows (Array of Arrays of Strings).

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).

Public Class Methods

new (header: nil, rows: [], widths: [], 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/schema/table.rb, line 118
def initialize(header: nil, rows: [], widths: [], 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)
  super(
    header:,
    rows:,
    widths:,
    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/paragraphs.
rows: 2D Array of strings/paragraphs.
widths: Array of Constraints.
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