Struct Table

pub struct Table<'a> { /* private fields */ }

A widget to display data in formatted columns.

A Table is a collection of Rows, each composed of Cells:

You can construct a Table using either Table::new or Table::default and then chain builder style methods to set the desired properties.

Table cells can be aligned, for more details see Cell.

Make sure to call the Table::widths method, otherwise the columns will all have a width of 0 and thus not be visible.

Table implements Widget and so it can be drawn using Frame::render_widget.

Table is also a StatefulWidget, which means you can use it with TableState to allow the user to scroll through the rows and select one of them. When rendering a Table with a TableState, the selected row, column and cell will be highlighted. If the selected row is not visible (based on the offset), the table will be scrolled to make the selected row visible.

Note: if the widths field is empty, the table will be rendered with equal widths. Note: Highlight styles are applied in the following order: Row, Column, Cell.

See the table example and the recipe and traceroute tabs in the demo2 example in the Examples directory for a more in depth example of the various configuration options and for how to handle state.

Constructor methods

• Table::new creates a new Table with the given rows.
• Table::default creates an empty Table. You can then add rows using Table::rows.

Setter methods

These methods are fluent setters. They return a new Table with the specified property set.

• Table::rows sets the rows of the Table.
• Table::header sets the header row of the Table.
• Table::footer sets the footer row of the Table.
• Table::widths sets the width constraints of each column.
• Table::column_spacing sets the spacing between each column.
• Table::block wraps the table in a Block widget.
• Table::style sets the base style of the widget.
• Table::row_highlight_style sets the style of the selected row.
• Table::column_highlight_style sets the style of the selected column.
• Table::cell_highlight_style sets the style of the selected cell.
• Table::highlight_symbol sets the symbol to be displayed in front of the selected row.
• Table::highlight_spacing sets when to show the highlight spacing.

Example

use ratatui::{
    layout::Constraint,
    style::{Style, Stylize},
    widgets::{Block, Row, Table},
};

let rows = [Row::new(vec!["Cell1", "Cell2", "Cell3"])];
// Columns widths are constrained in the same way as Layout...
let widths = [
    Constraint::Length(5),
    Constraint::Length(5),
    Constraint::Length(10),
];
let table = Table::new(rows, widths)
    // ...and they can be separated by a fixed spacing.
    .column_spacing(1)
    // You can set the style of the entire Table.
    .style(Style::new().blue())
    // It has an optional header, which is simply a Row always visible at the top.
    .header(
        Row::new(vec!["Col1", "Col2", "Col3"])
            .style(Style::new().bold())
            // To add space between the header and the rest of the rows, specify the margin
            .bottom_margin(1),
    )
    // It has an optional footer, which is simply a Row always visible at the bottom.
    .footer(Row::new(vec!["Updated on Dec 28"]))
    // As any other widget, a Table can be wrapped in a Block.
    .block(Block::new().title("Table"))
    // The selected row, column, cell and its content can also be styled.
    .row_highlight_style(Style::new().reversed())
    .column_highlight_style(Style::new().red())
    .cell_highlight_style(Style::new().blue())
    // ...and potentially show a symbol in front of the selection.
    .highlight_symbol(">>");

Rows can be created from an iterator of Cells. Each row can have an associated height, bottom margin, and style. See Row for more details.

use ratatui::{
    style::{Style, Stylize},
    text::{Line, Span},
    widgets::{Cell, Row, Table},
};

// a Row can be created from simple strings.
let row = Row::new(vec!["Row11", "Row12", "Row13"]);

// You can style the entire row.
let row = Row::new(vec!["Row21", "Row22", "Row23"]).style(Style::new().red());

// If you need more control over the styling, create Cells directly
let row = Row::new(vec![
    Cell::from("Row31"),
    Cell::from("Row32").style(Style::new().yellow()),
    Cell::from(Line::from(vec![Span::raw("Row"), Span::from("33").green()])),
]);

// If a Row need to display some content over multiple lines, specify the height.
let row = Row::new(vec![
    Cell::from("Row\n41"),
    Cell::from("Row\n42"),
    Cell::from("Row\n43"),
])
.height(2);

Cells can be created from anything that can be converted to Text. See Cell for more details.

use ratatui::{
    style::{Style, Stylize},
    text::{Line, Span, Text},
    widgets::Cell,
};

Cell::from("simple string");
Cell::from("simple styled span".red());
Cell::from(Span::raw("raw span"));
Cell::from(Span::styled("styled span", Style::new().red()));
Cell::from(Line::from(vec![
    Span::raw("a vec of "),
    Span::from("spans").bold(),
]));
Cell::from(Text::from("text"));

Just as rows can be collected from iterators of Cells, tables can be collected from iterators of Rows. This will create a table with column widths evenly dividing the space available. These default columns widths can be overridden using the Table::widths method.

use ratatui::{
    layout::Constraint,
    widgets::{Row, Table},
};

let text = "Mary had a\nlittle lamb.";

let table = text
    .split("\n")
    .map(|line: &str| -> Row { line.split_ascii_whitespace().collect() })
    .collect::<Table>()
    .widths([Constraint::Length(10); 3]);

Table also implements the Styled trait, which means you can use style shorthands from the Stylize trait to set the style of the widget more concisely.

use ratatui::{
    layout::Constraint,
    style::Stylize,
    widgets::{Row, Table},
};

let rows = [Row::new(vec!["Cell1", "Cell2", "Cell3"])];
let widths = [
    Constraint::Length(5),
    Constraint::Length(5),
    Constraint::Length(10),
];
let table = Table::new(rows, widths).red().italic();

Stateful example

Table is a StatefulWidget, which means you can use it with TableState to allow the user to scroll through the rows and select one of them.

use ratatui::{
    layout::{Constraint, Rect},
    style::{Style, Stylize},
    widgets::{Block, Row, Table, TableState},
    Frame,
};

// Note: TableState should be stored in your application state (not constructed in your render
// method) so that the selected row is preserved across renders
let mut table_state = TableState::default();
let rows = [
    Row::new(vec!["Row11", "Row12", "Row13"]),
    Row::new(vec!["Row21", "Row22", "Row23"]),
    Row::new(vec!["Row31", "Row32", "Row33"]),
];
let widths = [
    Constraint::Length(5),
    Constraint::Length(5),
    Constraint::Length(10),
];
let table = Table::new(rows, widths)
    .block(Block::new().title("Table"))
    .row_highlight_style(Style::new().reversed())
    .highlight_symbol(">>");

frame.render_stateful_widget(table, area, &mut table_state);

Implementations

impl<'a> Table<'a>

pub fn new<R, C>(rows: R, widths: C) -> Self

where R: IntoIterator, R::Item: Into<Row<'a>>, C: IntoIterator, C::Item: Into<Constraint>,

Creates a new Table widget with the given rows.

The rows parameter accepts any value that can be converted into an iterator of Rows. This includes arrays, slices, and Vecs.

The widths parameter accepts any type that implements IntoIterator<Item = Into<Constraint>>. This includes arrays, slices, vectors, iterators. Into<Constraint> is implemented on u16, so you can pass an array, vec, etc. of u16 to this function to create a table with fixed width columns.

Examples

use ratatui::{
    layout::Constraint,
    widgets::{Row, Table},
};

let rows = [
    Row::new(vec!["Cell1", "Cell2"]),
    Row::new(vec!["Cell3", "Cell4"]),
];
let widths = [Constraint::Length(5), Constraint::Length(5)];
let table = Table::new(rows, widths);

Examples found in repository

examples/demo2/tabs/recipe.rs (line 164)

fn render_ingredients(selected_row: usize, area: Rect, buf: &mut Buffer) {
    let mut state = TableState::default().with_selected(Some(selected_row));
    let rows = INGREDIENTS.iter().copied();
    let theme = THEME.recipe;
    StatefulWidget::render(
        Table::new(rows, [Constraint::Length(7), Constraint::Length(30)])
            .block(Block::new().style(theme.ingredients))
            .header(Row::new(vec!["Qty", "Ingredient"]).style(theme.ingredients_header))
            .row_highlight_style(Style::new().light_yellow()),
        area,
        buf,
        &mut state,
    );
}

examples/async.rs (line 243)

    fn render(self, area: Rect, buf: &mut Buffer) {
        let mut state = self.state.write().unwrap();

        // a block with a right aligned title with the loading state on the right
        let loading_state = Line::from(format!("{:?}", state.loading_state)).right_aligned();
        let block = Block::bordered()
            .title("Pull Requests")
            .title(loading_state)
            .title_bottom("j/k to scroll, q to quit");

        // a table with the list of pull requests
        let rows = state.pull_requests.iter();
        let widths = [
            Constraint::Length(5),
            Constraint::Fill(1),
            Constraint::Max(49),
        ];
        let table = Table::new(rows, widths)
            .block(block)
            .highlight_spacing(HighlightSpacing::Always)
            .highlight_symbol(">>")
            .row_highlight_style(Style::new().on_blue());

        StatefulWidget::render(table, area, buf, &mut state.table_state);
    }

examples/demo2/tabs/traceroute.rs (line 61)

fn render_hops(selected_row: usize, area: Rect, buf: &mut Buffer) {
    let mut state = TableState::default().with_selected(Some(selected_row));
    let rows = HOPS.iter().map(|hop| Row::new(vec![hop.host, hop.address]));
    let block = Block::new()
        .padding(Padding::new(1, 1, 1, 1))
        .title_alignment(Alignment::Center)
        .title("Traceroute bad.horse".bold().white());
    StatefulWidget::render(
        Table::new(rows, [Constraint::Max(100), Constraint::Length(15)])
            .header(Row::new(vec!["Host", "Address"]).set_style(THEME.traceroute.header))
            .row_highlight_style(THEME.traceroute.selected)
            .block(block),
        area,
        buf,
        &mut state,
    );
    let mut scrollbar_state = ScrollbarState::default()
        .content_length(HOPS.len())
        .position(selected_row);
    let area = Rect {
        width: area.width + 1,
        y: area.y + 3,
        height: area.height - 4,
        ..area
    };
    Scrollbar::default()
        .orientation(ScrollbarOrientation::VerticalLeft)
        .begin_symbol(None)
        .end_symbol(None)
        .track_symbol(None)
        .thumb_symbol("▌")
        .render(area, buf, &mut scrollbar_state);
}

examples/table.rs (lines 245-253)

    fn render_table(&mut self, frame: &mut Frame, area: Rect) {
        let header_style = Style::default()
            .fg(self.colors.header_fg)
            .bg(self.colors.header_bg);
        let selected_row_style = Style::default()
            .add_modifier(Modifier::REVERSED)
            .fg(self.colors.selected_row_style_fg);
        let selected_col_style = Style::default().fg(self.colors.selected_column_style_fg);
        let selected_cell_style = Style::default()
            .add_modifier(Modifier::REVERSED)
            .fg(self.colors.selected_cell_style_fg);

        let header = ["Name", "Address", "Email"]
            .into_iter()
            .map(Cell::from)
            .collect::<Row>()
            .style(header_style)
            .height(1);
        let rows = self.items.iter().enumerate().map(|(i, data)| {
            let color = match i % 2 {
                0 => self.colors.normal_row_color,
                _ => self.colors.alt_row_color,
            };
            let item = data.ref_array();
            item.into_iter()
                .map(|content| Cell::from(Text::from(format!("\n{content}\n"))))
                .collect::<Row>()
                .style(Style::new().fg(self.colors.row_fg).bg(color))
                .height(4)
        });
        let bar = " █ ";
        let t = Table::new(
            rows,
            [
                // + 1 is for padding.
                Constraint::Length(self.longest_item_lens.0 + 1),
                Constraint::Min(self.longest_item_lens.1 + 1),
                Constraint::Min(self.longest_item_lens.2),
            ],
        )
        .header(header)
        .row_highlight_style(selected_row_style)
        .column_highlight_style(selected_col_style)
        .cell_highlight_style(selected_cell_style)
        .highlight_symbol(Text::from(vec![
            "".into(),
            bar.into(),
            bar.into(),
            "".into(),
        ]))
        .bg(self.colors.buffer_bg)
        .highlight_spacing(HighlightSpacing::Always);
        frame.render_stateful_widget(t, area, &mut self.state);
    }

pub fn rows<T>(self, rows: T) -> Self

where T: IntoIterator<Item = Row<'a>>,

Set the rows

The rows parameter accepts any value that can be converted into an iterator of Rows. This includes arrays, slices, and Vecs.

Warning

This method does not currently set the column widths. You will need to set them manually by calling Table::widths.

This is a fluent setter method which must be chained or used as it consumes self

Examples

use ratatui::widgets::{Row, Table};

let rows = [
    Row::new(vec!["Cell1", "Cell2"]),
    Row::new(vec!["Cell3", "Cell4"]),
];
let table = Table::default().rows(rows);

pub fn header(self, header: Row<'a>) -> Self

Sets the header row

The header parameter is a Row which will be displayed at the top of the Table

This is a fluent setter method which must be chained or used as it consumes self

Examples

use ratatui::widgets::{Cell, Row, Table};

let header = Row::new(vec![
    Cell::from("Header Cell 1"),
    Cell::from("Header Cell 2"),
]);
let table = Table::default().header(header);

Examples found in repository

examples/demo2/tabs/recipe.rs (line 166)

fn render_ingredients(selected_row: usize, area: Rect, buf: &mut Buffer) {
    let mut state = TableState::default().with_selected(Some(selected_row));
    let rows = INGREDIENTS.iter().copied();
    let theme = THEME.recipe;
    StatefulWidget::render(
        Table::new(rows, [Constraint::Length(7), Constraint::Length(30)])
            .block(Block::new().style(theme.ingredients))
            .header(Row::new(vec!["Qty", "Ingredient"]).style(theme.ingredients_header))
            .row_highlight_style(Style::new().light_yellow()),
        area,
        buf,
        &mut state,
    );
}

examples/demo2/tabs/traceroute.rs (line 62)

fn render_hops(selected_row: usize, area: Rect, buf: &mut Buffer) {
    let mut state = TableState::default().with_selected(Some(selected_row));
    let rows = HOPS.iter().map(|hop| Row::new(vec![hop.host, hop.address]));
    let block = Block::new()
        .padding(Padding::new(1, 1, 1, 1))
        .title_alignment(Alignment::Center)
        .title("Traceroute bad.horse".bold().white());
    StatefulWidget::render(
        Table::new(rows, [Constraint::Max(100), Constraint::Length(15)])
            .header(Row::new(vec!["Host", "Address"]).set_style(THEME.traceroute.header))
            .row_highlight_style(THEME.traceroute.selected)
            .block(block),
        area,
        buf,
        &mut state,
    );
    let mut scrollbar_state = ScrollbarState::default()
        .content_length(HOPS.len())
        .position(selected_row);
    let area = Rect {
        width: area.width + 1,
        y: area.y + 3,
        height: area.height - 4,
        ..area
    };
    Scrollbar::default()
        .orientation(ScrollbarOrientation::VerticalLeft)
        .begin_symbol(None)
        .end_symbol(None)
        .track_symbol(None)
        .thumb_symbol("▌")
        .render(area, buf, &mut scrollbar_state);
}

examples/table.rs (line 254)

    fn render_table(&mut self, frame: &mut Frame, area: Rect) {
        let header_style = Style::default()
            .fg(self.colors.header_fg)
            .bg(self.colors.header_bg);
        let selected_row_style = Style::default()
            .add_modifier(Modifier::REVERSED)
            .fg(self.colors.selected_row_style_fg);
        let selected_col_style = Style::default().fg(self.colors.selected_column_style_fg);
        let selected_cell_style = Style::default()
            .add_modifier(Modifier::REVERSED)
            .fg(self.colors.selected_cell_style_fg);

        let header = ["Name", "Address", "Email"]
            .into_iter()
            .map(Cell::from)
            .collect::<Row>()
            .style(header_style)
            .height(1);
        let rows = self.items.iter().enumerate().map(|(i, data)| {
            let color = match i % 2 {
                0 => self.colors.normal_row_color,
                _ => self.colors.alt_row_color,
            };
            let item = data.ref_array();
            item.into_iter()
                .map(|content| Cell::from(Text::from(format!("\n{content}\n"))))
                .collect::<Row>()
                .style(Style::new().fg(self.colors.row_fg).bg(color))
                .height(4)
        });
        let bar = " █ ";
        let t = Table::new(
            rows,
            [
                // + 1 is for padding.
                Constraint::Length(self.longest_item_lens.0 + 1),
                Constraint::Min(self.longest_item_lens.1 + 1),
                Constraint::Min(self.longest_item_lens.2),
            ],
        )
        .header(header)
        .row_highlight_style(selected_row_style)
        .column_highlight_style(selected_col_style)
        .cell_highlight_style(selected_cell_style)
        .highlight_symbol(Text::from(vec![
            "".into(),
            bar.into(),
            bar.into(),
            "".into(),
        ]))
        .bg(self.colors.buffer_bg)
        .highlight_spacing(HighlightSpacing::Always);
        frame.render_stateful_widget(t, area, &mut self.state);
    }

pub fn footer(self, footer: Row<'a>) -> Self

Sets the footer row

The footer parameter is a Row which will be displayed at the bottom of the Table

This is a fluent setter method which must be chained or used as it consumes self

Examples

use ratatui::widgets::{Cell, Row, Table};

let footer = Row::new(vec![
    Cell::from("Footer Cell 1"),
    Cell::from("Footer Cell 2"),
]);
let table = Table::default().footer(footer);

pub fn widths<I>(self, widths: I) -> Self

where I: IntoIterator, I::Item: Into<Constraint>,

Set the widths of the columns.

The widths parameter accepts any type that implements IntoIterator<Item = Into<Constraint>>. This includes arrays, slices, vectors, iterators. Into<Constraint> is implemented on u16, so you can pass an array, vec, etc. of u16 to this function to create a table with fixed width columns.

If the widths are empty, the table will be rendered with equal widths.

This is a fluent setter method which must be chained or used as it consumes self

Examples

use ratatui::{
    layout::Constraint,
    widgets::{Cell, Row, Table},
};

let table = Table::default().widths([Constraint::Length(5), Constraint::Length(5)]);
let table = Table::default().widths(vec![Constraint::Length(5); 2]);

// widths could also be computed at runtime
let widths = [10, 10, 20].into_iter().map(|c| Constraint::Length(c));
let table = Table::default().widths(widths);

pub const fn column_spacing(self, spacing: u16) -> Self

Set the spacing between columns

This is a fluent setter method which must be chained or used as it consumes self

Examples

use ratatui::{
    layout::Constraint,
    widgets::{Row, Table},
};

let rows = [Row::new(vec!["Cell1", "Cell2"])];
let widths = [Constraint::Length(5), Constraint::Length(5)];
let table = Table::new(rows, widths).column_spacing(1);

pub fn block(self, block: Block<'a>) -> Self

Wraps the table with a custom Block widget.

The block parameter is of type Block. This holds the specified block to be created around the Table

This is a fluent setter method which must be chained or used as it consumes self

Examples

use ratatui::{
    layout::Constraint,
    widgets::{Block, Cell, Row, Table},
};

let rows = [Row::new(vec!["Cell1", "Cell2"])];
let widths = [Constraint::Length(5), Constraint::Length(5)];
let block = Block::bordered().title("Table");
let table = Table::new(rows, widths).block(block);

Examples found in repository

examples/demo2/tabs/recipe.rs (line 165)

fn render_ingredients(selected_row: usize, area: Rect, buf: &mut Buffer) {
    let mut state = TableState::default().with_selected(Some(selected_row));
    let rows = INGREDIENTS.iter().copied();
    let theme = THEME.recipe;
    StatefulWidget::render(
        Table::new(rows, [Constraint::Length(7), Constraint::Length(30)])
            .block(Block::new().style(theme.ingredients))
            .header(Row::new(vec!["Qty", "Ingredient"]).style(theme.ingredients_header))
            .row_highlight_style(Style::new().light_yellow()),
        area,
        buf,
        &mut state,
    );
}

examples/async.rs (line 244)

    fn render(self, area: Rect, buf: &mut Buffer) {
        let mut state = self.state.write().unwrap();

        // a block with a right aligned title with the loading state on the right
        let loading_state = Line::from(format!("{:?}", state.loading_state)).right_aligned();
        let block = Block::bordered()
            .title("Pull Requests")
            .title(loading_state)
            .title_bottom("j/k to scroll, q to quit");

        // a table with the list of pull requests
        let rows = state.pull_requests.iter();
        let widths = [
            Constraint::Length(5),
            Constraint::Fill(1),
            Constraint::Max(49),
        ];
        let table = Table::new(rows, widths)
            .block(block)
            .highlight_spacing(HighlightSpacing::Always)
            .highlight_symbol(">>")
            .row_highlight_style(Style::new().on_blue());

        StatefulWidget::render(table, area, buf, &mut state.table_state);
    }

examples/demo2/tabs/traceroute.rs (line 64)

fn render_hops(selected_row: usize, area: Rect, buf: &mut Buffer) {
    let mut state = TableState::default().with_selected(Some(selected_row));
    let rows = HOPS.iter().map(|hop| Row::new(vec![hop.host, hop.address]));
    let block = Block::new()
        .padding(Padding::new(1, 1, 1, 1))
        .title_alignment(Alignment::Center)
        .title("Traceroute bad.horse".bold().white());
    StatefulWidget::render(
        Table::new(rows, [Constraint::Max(100), Constraint::Length(15)])
            .header(Row::new(vec!["Host", "Address"]).set_style(THEME.traceroute.header))
            .row_highlight_style(THEME.traceroute.selected)
            .block(block),
        area,
        buf,
        &mut state,
    );
    let mut scrollbar_state = ScrollbarState::default()
        .content_length(HOPS.len())
        .position(selected_row);
    let area = Rect {
        width: area.width + 1,
        y: area.y + 3,
        height: area.height - 4,
        ..area
    };
    Scrollbar::default()
        .orientation(ScrollbarOrientation::VerticalLeft)
        .begin_symbol(None)
        .end_symbol(None)
        .track_symbol(None)
        .thumb_symbol("▌")
        .render(area, buf, &mut scrollbar_state);
}

pub fn style<S: Into<Style>>(self, style: S) -> Self

Sets the base style of the widget

style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

All text rendered by the widget will use this style, unless overridden by Block::style, Row::style, Cell::style, or the styles of cell’s content.

This is a fluent setter method which must be chained or used as it consumes self

Examples

use ratatui::{
    layout::Constraint,
    style::{Style, Stylize},
    widgets::{Row, Table},
};

let table = Table::new(rows, widths).style(Style::new().red().italic());

Table also implements the Styled trait, which means you can use style shorthands from the Stylize trait to set the style of the widget more concisely.

use ratatui::{
    layout::Constraint,
    style::Stylize,
    widgets::{Cell, Row, Table},
};

let table = Table::new(rows, widths).red().italic();

pub fn highlight_style<S: Into<Style>>(self, highlight_style: S) -> Self

👎Deprecated: use Table::row_highlight_style instead

Set the style of the selected row

style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

This style will be applied to the entire row, including the selection symbol if it is displayed, and will override any style set on the row or on the individual cells.

This is a fluent setter method which must be chained or used as it consumes self

Examples

use ratatui::{
    layout::Constraint,
    style::{Style, Stylize},
    widgets::{Cell, Row, Table},
};

let rows = [Row::new(vec!["Cell1", "Cell2"])];
let widths = [Constraint::Length(5), Constraint::Length(5)];
let table = Table::new(rows, widths).highlight_style(Style::new().red().italic());

pub fn row_highlight_style<S: Into<Style>>(self, highlight_style: S) -> Self

Set the style of the selected row

style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

This style will be applied to the entire row, including the selection symbol if it is displayed, and will override any style set on the row or on the individual cells.

This is a fluent setter method which must be chained or used as it consumes self

Examples

let table = Table::new(rows, widths).row_highlight_style(Style::new().red().italic());

Examples found in repository

examples/demo2/tabs/recipe.rs (line 167)

fn render_ingredients(selected_row: usize, area: Rect, buf: &mut Buffer) {
    let mut state = TableState::default().with_selected(Some(selected_row));
    let rows = INGREDIENTS.iter().copied();
    let theme = THEME.recipe;
    StatefulWidget::render(
        Table::new(rows, [Constraint::Length(7), Constraint::Length(30)])
            .block(Block::new().style(theme.ingredients))
            .header(Row::new(vec!["Qty", "Ingredient"]).style(theme.ingredients_header))
            .row_highlight_style(Style::new().light_yellow()),
        area,
        buf,
        &mut state,
    );
}

examples/async.rs (line 247)

    fn render(self, area: Rect, buf: &mut Buffer) {
        let mut state = self.state.write().unwrap();

        // a block with a right aligned title with the loading state on the right
        let loading_state = Line::from(format!("{:?}", state.loading_state)).right_aligned();
        let block = Block::bordered()
            .title("Pull Requests")
            .title(loading_state)
            .title_bottom("j/k to scroll, q to quit");

        // a table with the list of pull requests
        let rows = state.pull_requests.iter();
        let widths = [
            Constraint::Length(5),
            Constraint::Fill(1),
            Constraint::Max(49),
        ];
        let table = Table::new(rows, widths)
            .block(block)
            .highlight_spacing(HighlightSpacing::Always)
            .highlight_symbol(">>")
            .row_highlight_style(Style::new().on_blue());

        StatefulWidget::render(table, area, buf, &mut state.table_state);
    }

examples/demo2/tabs/traceroute.rs (line 63)

fn render_hops(selected_row: usize, area: Rect, buf: &mut Buffer) {
    let mut state = TableState::default().with_selected(Some(selected_row));
    let rows = HOPS.iter().map(|hop| Row::new(vec![hop.host, hop.address]));
    let block = Block::new()
        .padding(Padding::new(1, 1, 1, 1))
        .title_alignment(Alignment::Center)
        .title("Traceroute bad.horse".bold().white());
    StatefulWidget::render(
        Table::new(rows, [Constraint::Max(100), Constraint::Length(15)])
            .header(Row::new(vec!["Host", "Address"]).set_style(THEME.traceroute.header))
            .row_highlight_style(THEME.traceroute.selected)
            .block(block),
        area,
        buf,
        &mut state,
    );
    let mut scrollbar_state = ScrollbarState::default()
        .content_length(HOPS.len())
        .position(selected_row);
    let area = Rect {
        width: area.width + 1,
        y: area.y + 3,
        height: area.height - 4,
        ..area
    };
    Scrollbar::default()
        .orientation(ScrollbarOrientation::VerticalLeft)
        .begin_symbol(None)
        .end_symbol(None)
        .track_symbol(None)
        .thumb_symbol("▌")
        .render(area, buf, &mut scrollbar_state);
}

examples/table.rs (line 255)

    fn render_table(&mut self, frame: &mut Frame, area: Rect) {
        let header_style = Style::default()
            .fg(self.colors.header_fg)
            .bg(self.colors.header_bg);
        let selected_row_style = Style::default()
            .add_modifier(Modifier::REVERSED)
            .fg(self.colors.selected_row_style_fg);
        let selected_col_style = Style::default().fg(self.colors.selected_column_style_fg);
        let selected_cell_style = Style::default()
            .add_modifier(Modifier::REVERSED)
            .fg(self.colors.selected_cell_style_fg);

        let header = ["Name", "Address", "Email"]
            .into_iter()
            .map(Cell::from)
            .collect::<Row>()
            .style(header_style)
            .height(1);
        let rows = self.items.iter().enumerate().map(|(i, data)| {
            let color = match i % 2 {
                0 => self.colors.normal_row_color,
                _ => self.colors.alt_row_color,
            };
            let item = data.ref_array();
            item.into_iter()
                .map(|content| Cell::from(Text::from(format!("\n{content}\n"))))
                .collect::<Row>()
                .style(Style::new().fg(self.colors.row_fg).bg(color))
                .height(4)
        });
        let bar = " █ ";
        let t = Table::new(
            rows,
            [
                // + 1 is for padding.
                Constraint::Length(self.longest_item_lens.0 + 1),
                Constraint::Min(self.longest_item_lens.1 + 1),
                Constraint::Min(self.longest_item_lens.2),
            ],
        )
        .header(header)
        .row_highlight_style(selected_row_style)
        .column_highlight_style(selected_col_style)
        .cell_highlight_style(selected_cell_style)
        .highlight_symbol(Text::from(vec![
            "".into(),
            bar.into(),
            bar.into(),
            "".into(),
        ]))
        .bg(self.colors.buffer_bg)
        .highlight_spacing(HighlightSpacing::Always);
        frame.render_stateful_widget(t, area, &mut self.state);
    }

pub fn column_highlight_style<S: Into<Style>>(self, highlight_style: S) -> Self

Set the style of the selected column

style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

This style will be applied to the entire column, and will override any style set on the row or on the individual cells.

This is a fluent setter method which must be chained or used as it consumes self

Examples

let table = Table::new(rows, widths).column_highlight_style(Style::new().red().italic());

Examples found in repository

examples/table.rs (line 256)

    fn render_table(&mut self, frame: &mut Frame, area: Rect) {
        let header_style = Style::default()
            .fg(self.colors.header_fg)
            .bg(self.colors.header_bg);
        let selected_row_style = Style::default()
            .add_modifier(Modifier::REVERSED)
            .fg(self.colors.selected_row_style_fg);
        let selected_col_style = Style::default().fg(self.colors.selected_column_style_fg);
        let selected_cell_style = Style::default()
            .add_modifier(Modifier::REVERSED)
            .fg(self.colors.selected_cell_style_fg);

        let header = ["Name", "Address", "Email"]
            .into_iter()
            .map(Cell::from)
            .collect::<Row>()
            .style(header_style)
            .height(1);
        let rows = self.items.iter().enumerate().map(|(i, data)| {
            let color = match i % 2 {
                0 => self.colors.normal_row_color,
                _ => self.colors.alt_row_color,
            };
            let item = data.ref_array();
            item.into_iter()
                .map(|content| Cell::from(Text::from(format!("\n{content}\n"))))
                .collect::<Row>()
                .style(Style::new().fg(self.colors.row_fg).bg(color))
                .height(4)
        });
        let bar = " █ ";
        let t = Table::new(
            rows,
            [
                // + 1 is for padding.
                Constraint::Length(self.longest_item_lens.0 + 1),
                Constraint::Min(self.longest_item_lens.1 + 1),
                Constraint::Min(self.longest_item_lens.2),
            ],
        )
        .header(header)
        .row_highlight_style(selected_row_style)
        .column_highlight_style(selected_col_style)
        .cell_highlight_style(selected_cell_style)
        .highlight_symbol(Text::from(vec![
            "".into(),
            bar.into(),
            bar.into(),
            "".into(),
        ]))
        .bg(self.colors.buffer_bg)
        .highlight_spacing(HighlightSpacing::Always);
        frame.render_stateful_widget(t, area, &mut self.state);
    }

pub fn cell_highlight_style<S: Into<Style>>(self, highlight_style: S) -> Self

Set the style of the selected cell

style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

This style will be applied to the selected cell, and will override any style set on the row or on the individual cells.

This is a fluent setter method which must be chained or used as it consumes self

Examples

let table = Table::new(rows, widths).cell_highlight_style(Style::new().red().italic());

Examples found in repository

examples/table.rs (line 257)

    fn render_table(&mut self, frame: &mut Frame, area: Rect) {
        let header_style = Style::default()
            .fg(self.colors.header_fg)
            .bg(self.colors.header_bg);
        let selected_row_style = Style::default()
            .add_modifier(Modifier::REVERSED)
            .fg(self.colors.selected_row_style_fg);
        let selected_col_style = Style::default().fg(self.colors.selected_column_style_fg);
        let selected_cell_style = Style::default()
            .add_modifier(Modifier::REVERSED)
            .fg(self.colors.selected_cell_style_fg);

        let header = ["Name", "Address", "Email"]
            .into_iter()
            .map(Cell::from)
            .collect::<Row>()
            .style(header_style)
            .height(1);
        let rows = self.items.iter().enumerate().map(|(i, data)| {
            let color = match i % 2 {
                0 => self.colors.normal_row_color,
                _ => self.colors.alt_row_color,
            };
            let item = data.ref_array();
            item.into_iter()
                .map(|content| Cell::from(Text::from(format!("\n{content}\n"))))
                .collect::<Row>()
                .style(Style::new().fg(self.colors.row_fg).bg(color))
                .height(4)
        });
        let bar = " █ ";
        let t = Table::new(
            rows,
            [
                // + 1 is for padding.
                Constraint::Length(self.longest_item_lens.0 + 1),
                Constraint::Min(self.longest_item_lens.1 + 1),
                Constraint::Min(self.longest_item_lens.2),
            ],
        )
        .header(header)
        .row_highlight_style(selected_row_style)
        .column_highlight_style(selected_col_style)
        .cell_highlight_style(selected_cell_style)
        .highlight_symbol(Text::from(vec![
            "".into(),
            bar.into(),
            bar.into(),
            "".into(),
        ]))
        .bg(self.colors.buffer_bg)
        .highlight_spacing(HighlightSpacing::Always);
        frame.render_stateful_widget(t, area, &mut self.state);
    }

pub fn highlight_symbol<T: Into<Text<'a>>>(self, highlight_symbol: T) -> Self

Set the symbol to be displayed in front of the selected row

This is a fluent setter method which must be chained or used as it consumes self

Examples

use ratatui::{
    layout::Constraint,
    widgets::{Cell, Row, Table},
};

let table = Table::new(rows, widths).highlight_symbol(">>");

Examples found in repository

examples/async.rs (line 246)

    fn render(self, area: Rect, buf: &mut Buffer) {
        let mut state = self.state.write().unwrap();

        // a block with a right aligned title with the loading state on the right
        let loading_state = Line::from(format!("{:?}", state.loading_state)).right_aligned();
        let block = Block::bordered()
            .title("Pull Requests")
            .title(loading_state)
            .title_bottom("j/k to scroll, q to quit");

        // a table with the list of pull requests
        let rows = state.pull_requests.iter();
        let widths = [
            Constraint::Length(5),
            Constraint::Fill(1),
            Constraint::Max(49),
        ];
        let table = Table::new(rows, widths)
            .block(block)
            .highlight_spacing(HighlightSpacing::Always)
            .highlight_symbol(">>")
            .row_highlight_style(Style::new().on_blue());

        StatefulWidget::render(table, area, buf, &mut state.table_state);
    }

examples/table.rs (lines 258-263)

    fn render_table(&mut self, frame: &mut Frame, area: Rect) {
        let header_style = Style::default()
            .fg(self.colors.header_fg)
            .bg(self.colors.header_bg);
        let selected_row_style = Style::default()
            .add_modifier(Modifier::REVERSED)
            .fg(self.colors.selected_row_style_fg);
        let selected_col_style = Style::default().fg(self.colors.selected_column_style_fg);
        let selected_cell_style = Style::default()
            .add_modifier(Modifier::REVERSED)
            .fg(self.colors.selected_cell_style_fg);

        let header = ["Name", "Address", "Email"]
            .into_iter()
            .map(Cell::from)
            .collect::<Row>()
            .style(header_style)
            .height(1);
        let rows = self.items.iter().enumerate().map(|(i, data)| {
            let color = match i % 2 {
                0 => self.colors.normal_row_color,
                _ => self.colors.alt_row_color,
            };
            let item = data.ref_array();
            item.into_iter()
                .map(|content| Cell::from(Text::from(format!("\n{content}\n"))))
                .collect::<Row>()
                .style(Style::new().fg(self.colors.row_fg).bg(color))
                .height(4)
        });
        let bar = " █ ";
        let t = Table::new(
            rows,
            [
                // + 1 is for padding.
                Constraint::Length(self.longest_item_lens.0 + 1),
                Constraint::Min(self.longest_item_lens.1 + 1),
                Constraint::Min(self.longest_item_lens.2),
            ],
        )
        .header(header)
        .row_highlight_style(selected_row_style)
        .column_highlight_style(selected_col_style)
        .cell_highlight_style(selected_cell_style)
        .highlight_symbol(Text::from(vec![
            "".into(),
            bar.into(),
            bar.into(),
            "".into(),
        ]))
        .bg(self.colors.buffer_bg)
        .highlight_spacing(HighlightSpacing::Always);
        frame.render_stateful_widget(t, area, &mut self.state);
    }

pub const fn highlight_spacing(self, value: HighlightSpacing) -> Self

Set when to show the highlight spacing

The highlight spacing is the spacing that is allocated for the selection symbol column (if enabled) and is used to shift the table when a row is selected. This method allows you to configure when this spacing is allocated.

• HighlightSpacing::Always will always allocate the spacing, regardless of whether a row is selected or not. This means that the table will never change size, regardless of if a row is selected or not.
• HighlightSpacing::WhenSelected will only allocate the spacing if a row is selected. This means that the table will shift when a row is selected. This is the default setting for backwards compatibility, but it is recommended to use HighlightSpacing::Always for a better user experience.
• HighlightSpacing::Never will never allocate the spacing, regardless of whether a row is selected or not. This means that the highlight symbol will never be drawn.

This is a fluent setter method which must be chained or used as it consumes self

Examples

use ratatui::{
    layout::Constraint,
    widgets::{HighlightSpacing, Row, Table},
};

let rows = [Row::new(vec!["Cell1", "Cell2"])];
let widths = [Constraint::Length(5), Constraint::Length(5)];
let table = Table::new(rows, widths).highlight_spacing(HighlightSpacing::Always);

Examples found in repository

examples/async.rs (line 245)

    fn render(self, area: Rect, buf: &mut Buffer) {
        let mut state = self.state.write().unwrap();

        // a block with a right aligned title with the loading state on the right
        let loading_state = Line::from(format!("{:?}", state.loading_state)).right_aligned();
        let block = Block::bordered()
            .title("Pull Requests")
            .title(loading_state)
            .title_bottom("j/k to scroll, q to quit");

        // a table with the list of pull requests
        let rows = state.pull_requests.iter();
        let widths = [
            Constraint::Length(5),
            Constraint::Fill(1),
            Constraint::Max(49),
        ];
        let table = Table::new(rows, widths)
            .block(block)
            .highlight_spacing(HighlightSpacing::Always)
            .highlight_symbol(">>")
            .row_highlight_style(Style::new().on_blue());

        StatefulWidget::render(table, area, buf, &mut state.table_state);
    }

examples/table.rs (line 265)

    fn render_table(&mut self, frame: &mut Frame, area: Rect) {
        let header_style = Style::default()
            .fg(self.colors.header_fg)
            .bg(self.colors.header_bg);
        let selected_row_style = Style::default()
            .add_modifier(Modifier::REVERSED)
            .fg(self.colors.selected_row_style_fg);
        let selected_col_style = Style::default().fg(self.colors.selected_column_style_fg);
        let selected_cell_style = Style::default()
            .add_modifier(Modifier::REVERSED)
            .fg(self.colors.selected_cell_style_fg);

        let header = ["Name", "Address", "Email"]
            .into_iter()
            .map(Cell::from)
            .collect::<Row>()
            .style(header_style)
            .height(1);
        let rows = self.items.iter().enumerate().map(|(i, data)| {
            let color = match i % 2 {
                0 => self.colors.normal_row_color,
                _ => self.colors.alt_row_color,
            };
            let item = data.ref_array();
            item.into_iter()
                .map(|content| Cell::from(Text::from(format!("\n{content}\n"))))
                .collect::<Row>()
                .style(Style::new().fg(self.colors.row_fg).bg(color))
                .height(4)
        });
        let bar = " █ ";
        let t = Table::new(
            rows,
            [
                // + 1 is for padding.
                Constraint::Length(self.longest_item_lens.0 + 1),
                Constraint::Min(self.longest_item_lens.1 + 1),
                Constraint::Min(self.longest_item_lens.2),
            ],
        )
        .header(header)
        .row_highlight_style(selected_row_style)
        .column_highlight_style(selected_col_style)
        .cell_highlight_style(selected_cell_style)
        .highlight_symbol(Text::from(vec![
            "".into(),
            bar.into(),
            bar.into(),
            "".into(),
        ]))
        .bg(self.colors.buffer_bg)
        .highlight_spacing(HighlightSpacing::Always);
        frame.render_stateful_widget(t, area, &mut self.state);
    }

pub const fn flex(self, flex: Flex) -> Self

Set how extra space is distributed amongst columns.

This determines how the space is distributed when the constraints are satisfied. By default, the extra space is not distributed at all. But this can be changed to distribute all extra space to the last column or to distribute it equally.

This is a fluent setter method which must be chained or used as it consumes self

Examples

Create a table that needs at least 30 columns to display. Any extra space will be assigned to the last column.

use ratatui::{
    layout::{Constraint, Flex},
    widgets::{Row, Table},
};

let widths = [
    Constraint::Min(10),
    Constraint::Min(10),
    Constraint::Min(10),
];
let table = Table::new(Vec::<Row>::new(), widths).flex(Flex::Legacy);

Trait Implementations

impl<'a> Clone for Table<'a>

fn clone(&self) -> Table<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for Table<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Default for Table<'a>

fn default() -> Self

Returns the “default value” for a type.

impl<'a, Item> FromIterator<Item> for Table<'a>

where Item: Into<Row<'a>>,

fn from_iter<Iter: IntoIterator<Item = Item>>(rows: Iter) -> Self

Collects an iterator of rows into a table.

When collecting from an iterator into a table, the user must provide the widths using Table::widths after construction.

impl<'a> Hash for Table<'a>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a> PartialEq for Table<'a>

fn eq(&self, other: &Table<'a>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StatefulWidget for &Table<'_>

type State = TableState

State associated with the stateful widget.

fn render(self, area: Rect, buf: &mut Buffer, state: &mut Self::State)

Draws the current state of the widget in the given buffer. That is the only method required to implement a custom stateful widget.

impl StatefulWidget for Table<'_>

type State = TableState

State associated with the stateful widget.

fn render(self, area: Rect, buf: &mut Buffer, state: &mut Self::State)

Draws the current state of the widget in the given buffer. That is the only method required to implement a custom stateful widget.

impl StatefulWidgetRef for Table<'_>

type State = TableState

Available on crate feature unstable-widget-ref only.

State associated with the stateful widget.

fn render_ref(&self, area: Rect, buf: &mut Buffer, state: &mut Self::State)

Available on crate feature unstable-widget-ref only.

Draws the current state of the widget in the given buffer. That is the only method required to implement a custom stateful widget.

impl<'a> Styled for Table<'a>

type Item = Table<'a>

fn style(&self) -> Style

Returns the style of the object.

fn set_style<S: Into<Style>>(self, style: S) -> Self::Item

Sets the style of the object.

impl Widget for Table<'_>

fn render(self, area: Rect, buf: &mut Buffer)

Draws the current state of the widget in the given buffer. That is the only method required to implement a custom widget.

impl WidgetRef for Table<'_>

fn render_ref(&self, area: Rect, buf: &mut Buffer)

Available on crate feature unstable-widget-ref only.

Draws the current state of the widget in the given buffer. That is the only method required to implement a custom widget.

impl<'a> Eq for Table<'a>

impl<'a> StructuralPartialEq for Table<'a>