Skip to content

DataTable

A table widget optimized for displaying a lot of data.

  • Focusable
  • Container

Example

The example below populates a table with CSV data.

TableApp  lane  swimmer               country        time    4     Joseph Schooling      Singapore      50.39   2     Michael Phelps        United States  51.14   5     Chad le Clos          South Africa   51.14   6     László Cseh           Hungary        51.14   3     Li Zhuhao             China          51.26   8     Mehdy Metella         France         51.58   7     Tom Shields           United States  51.73   1     Aleksandr Sadovnikov  Russia         51.84   10    Darren Burns          Scotland       51.84 

from textual.app import App, ComposeResult
from textual.widgets import DataTable

ROWS = [
    ("lane", "swimmer", "country", "time"),
    (4, "Joseph Schooling", "Singapore", 50.39),
    (2, "Michael Phelps", "United States", 51.14),
    (5, "Chad le Clos", "South Africa", 51.14),
    (6, "László Cseh", "Hungary", 51.14),
    (3, "Li Zhuhao", "China", 51.26),
    (8, "Mehdy Metella", "France", 51.58),
    (7, "Tom Shields", "United States", 51.73),
    (1, "Aleksandr Sadovnikov", "Russia", 51.84),
    (10, "Darren Burns", "Scotland", 51.84),
]


class TableApp(App):
    def compose(self) -> ComposeResult:
        yield DataTable()

    def on_mount(self) -> None:
        table = self.query_one(DataTable)
        rows = iter(ROWS)
        table.add_columns(*next(rows))
        table.add_rows(rows)


app = TableApp()
if __name__ == "__main__":
    app.run()

Reactive Attributes

Name Type Default Description
show_header bool True Show the table header
fixed_rows int 0 Number of fixed rows (rows which do not scroll)
fixed_columns int 0 Number of fixed columns (columns which do not scroll)
zebra_stripes bool False Display alternating colors on rows
header_height int 1 Height of header row
show_cursor bool True Show the cursor
cursor_type str "cell" One of "cell", "row", "column", or "none"
cursor_coordinate Coordinate Coordinate(0, 0) The current coordinate of the cursor
hover_coordinate Coordinate Coordinate(0, 0) The coordinate the mouse cursor is above

Messages

CellHighlighted

Bases: Message

Posted when the cursor moves to highlight a new cell.

This is only relevant when the cursor_type is "cell". It's also posted when the cell cursor is re-enabled (by setting show_cursor=True), and when the cursor type is changed to "cell". Can be handled using on_data_table_cell_highlighted in a subclass of DataTable or in a parent widget in the DOM.

cell_key: CellKey instance-attribute

The key for the highlighted cell.

control: DataTable property

Alias for the data table.

coordinate: Coordinate instance-attribute

The coordinate of the highlighted cell.

data_table instance-attribute

The data table.

value: CellType instance-attribute

The value in the highlighted cell.

CellSelected

Bases: Message

Posted by the DataTable widget when a cell is selected.

This is only relevant when the cursor_type is "cell". Can be handled using on_data_table_cell_selected in a subclass of DataTable or in a parent widget in the DOM.

cell_key: CellKey instance-attribute

The key for the selected cell.

control: DataTable property

Alias for the data table.

coordinate: Coordinate instance-attribute

The coordinate of the cell that was selected.

data_table instance-attribute

The data table.

value: CellType instance-attribute

The value in the cell that was selected.

RowHighlighted

Bases: Message

Posted when a row is highlighted.

This message is only posted when the cursor_type is set to "row". Can be handled using on_data_table_row_highlighted in a subclass of DataTable or in a parent widget in the DOM.

control: DataTable property

Alias for the data table.

cursor_row: int instance-attribute

The y-coordinate of the cursor that highlighted the row.

data_table instance-attribute

The data table.

row_key: RowKey instance-attribute

The key of the row that was highlighted.

RowSelected

Bases: Message

Posted when a row is selected.

This message is only posted when the cursor_type is set to "row". Can be handled using on_data_table_row_selected in a subclass of DataTable or in a parent widget in the DOM.

control: DataTable property

Alias for the data table.

cursor_row: int instance-attribute

The y-coordinate of the cursor that made the selection.

data_table instance-attribute

The data table.

row_key: RowKey instance-attribute

The key of the row that was selected.

ColumnHighlighted

Bases: Message

Posted when a column is highlighted.

This message is only posted when the cursor_type is set to "column". Can be handled using on_data_table_column_highlighted in a subclass of DataTable or in a parent widget in the DOM.

column_key instance-attribute

The key of the column that was highlighted.

control: DataTable property

Alias for the data table.

cursor_column: int instance-attribute

The x-coordinate of the column that was highlighted.

data_table instance-attribute

The data table.

ColumnSelected

Bases: Message

Posted when a column is selected.

This message is only posted when the cursor_type is set to "column". Can be handled using on_data_table_column_selected in a subclass of DataTable or in a parent widget in the DOM.

column_key instance-attribute

The key of the column that was selected.

control: DataTable property

Alias for the data table.

cursor_column: int instance-attribute

The x-coordinate of the column that was selected.

data_table instance-attribute

The data table.

HeaderSelected

Bases: Message

Posted when a column header/label is clicked.

column_index instance-attribute

The index for the column.

column_key instance-attribute

The key for the column.

control: DataTable property

Alias for the data table.

data_table instance-attribute

The data table.

label instance-attribute

The text of the label.

Bindings

The data table widget defines the following bindings:

Key(s) Description
enter Select cells under the cursor.
up Move the cursor up.
down Move the cursor down.
right Move the cursor right.
left Move the cursor left.

Component Classes

The data table widget provides the following component classes:

Class Description
datatable--cursor Target the cursor.
datatable--hover Target the cells under the hover cursor.
datatable--fixed Target fixed columns and fixed rows.
datatable--fixed-cursor Target highlighted and fixed columns or header.
datatable--header Target the header of the data table.
datatable--header-cursor Target cells highlighted by the cursor.
datatable--header-hover Target hovered header or row label cells.
datatable--even-row Target even rows (row indices start at 0).
datatable--odd-row Target odd rows (row indices start at 0).

See Also