Struct TableState

pub struct TableState { /* private fields */ }

State of a Table widget

This state can be used to scroll through the rows and select one of them. When the table is rendered as a stateful widget, the selected row, column and cell will be highlighted and the table will be shifted to ensure that the selected row is visible. This will modify the TableState object passed to the Frame::render_stateful_widget method.

The state consists of two fields:

• offset: the index of the first row to be displayed
• selected: the index of the selected row, which can be None if no row is selected
• selected_column: the index of the selected column, which can be None if no column is selected

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.

Example

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

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

// 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();
*table_state.offset_mut() = 1; // display the second row and onwards
table_state.select(Some(3)); // select the forth row (0-indexed)
table_state.select_column(Some(2)); // select the third column (0-indexed)

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

Note that if Table::widths is not called before rendering, the rendered columns will have equal width.

Implementations

impl TableState

pub const fn new() -> Self

Creates a new TableState

Examples

use ratatui::widgets::TableState;

let state = TableState::new();

pub const fn with_offset(self, offset: usize) -> Self

Sets the index of the first row to be displayed

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

Examples

use ratatui::widgets::TableState;

let state = TableState::new().with_offset(1);

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

where T: Into<Option<usize>>,

Sets the index of the selected row

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

Examples

use ratatui::widgets::TableState;

let state = TableState::new().with_selected(Some(1));

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

where T: Into<Option<usize>>,

Sets the index of the selected column

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

Examples

let state = TableState::new().with_selected_column(Some(1));

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

where T: Into<Option<(usize, usize)>>,

Sets the indexes of the selected cell

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

Examples

let state = TableState::new().with_selected_cell(Some((1, 5)));

pub const fn offset(&self) -> usize

Index of the first row to be displayed

Examples

use ratatui::widgets::TableState;

let state = TableState::new();
assert_eq!(state.offset(), 0);

pub fn offset_mut(&mut self) -> &mut usize

Mutable reference to the index of the first row to be displayed

Examples

use ratatui::widgets::TableState;

let mut state = TableState::default();
*state.offset_mut() = 1;

pub const fn selected(&self) -> Option<usize>

Index of the selected row

Returns None if no row is selected

Examples

use ratatui::widgets::TableState;

let state = TableState::new();
assert_eq!(state.selected(), None);

pub const fn selected_column(&self) -> Option<usize>

Index of the selected column

Returns None if no column is selected

Examples

let state = TableState::new();
assert_eq!(state.selected_column(), None);

pub const fn selected_cell(&self) -> Option<(usize, usize)>

Indexes of the selected cell

Returns None if no cell is selected

Examples

let state = TableState::new();
assert_eq!(state.selected_cell(), None);

pub fn selected_mut(&mut self) -> &mut Option<usize>

Mutable reference to the index of the selected row

Returns None if no row is selected

Examples

use ratatui::widgets::TableState;

let mut state = TableState::default();
*state.selected_mut() = Some(1);

pub fn selected_column_mut(&mut self) -> &mut Option<usize>

Mutable reference to the index of the selected column

Returns None if no column is selected

Examples

let mut state = TableState::default();
*state.selected_column_mut() = Some(1);

pub fn select(&mut self, index: Option<usize>)

Sets the index of the selected row

Set to None if no row is selected. This will also reset the offset to 0.

Examples

use ratatui::widgets::TableState;

let mut state = TableState::default();
state.select(Some(1));

pub fn select_column(&mut self, index: Option<usize>)

Sets the index of the selected column

Examples

let mut state = TableState::default();
state.select_column(Some(1));

pub fn select_cell(&mut self, indexes: Option<(usize, usize)>)

Sets the indexes of the selected cell

Set to None if no cell is selected. This will also reset the row offset to 0.

Examples

let mut state = TableState::default();
state.select_cell(Some((1, 5)));

pub fn select_next(&mut self)

Selects the next row or the first one if no row is selected

Note: until the table is rendered, the number of rows is not known, so the index is set to 0 and will be corrected when the table is rendered

Examples

use ratatui::widgets::TableState;

let mut state = TableState::default();
state.select_next();

pub fn select_next_column(&mut self)

Selects the next column or the first one if no column is selected

Note: until the table is rendered, the number of columns is not known, so the index is set to 0 and will be corrected when the table is rendered

Examples

let mut state = TableState::default();
state.select_next_column();

pub fn select_previous(&mut self)

Selects the previous row or the last one if no item is selected

Note: until the table is rendered, the number of rows is not known, so the index is set to usize::MAX and will be corrected when the table is rendered

Examples

use ratatui::widgets::TableState;

let mut state = TableState::default();
state.select_previous();

pub fn select_previous_column(&mut self)

Selects the previous column or the last one if no column is selected

Note: until the table is rendered, the number of columns is not known, so the index is set to usize::MAX and will be corrected when the table is rendered

Examples

let mut state = TableState::default();
state.select_previous_column();

pub fn select_first(&mut self)

Selects the first row

Note: until the table is rendered, the number of rows is not known, so the index is set to 0 and will be corrected when the table is rendered

Examples

use ratatui::widgets::TableState;

let mut state = TableState::default();
state.select_first();

pub fn select_first_column(&mut self)

Selects the first column

Note: until the table is rendered, the number of columns is not known, so the index is set to 0 and will be corrected when the table is rendered

Examples

let mut state = TableState::default();
state.select_first_column();

pub fn select_last(&mut self)

Selects the last row

Note: until the table is rendered, the number of rows is not known, so the index is set to usize::MAX and will be corrected when the table is rendered

Examples

use ratatui::widgets::TableState;

let mut state = TableState::default();
state.select_last();

pub fn select_last_column(&mut self)

Selects the last column

Note: until the table is rendered, the number of columns is not known, so the index is set to usize::MAX and will be corrected when the table is rendered

Examples

let mut state = TableState::default();
state.select_last();

pub fn scroll_down_by(&mut self, amount: u16)

Scrolls down by a specified amount in the table.

This method updates the selected index by moving it down by the given amount. If the amount causes the index to go out of bounds (i.e., if the index is greater than the number of rows in the table), the last row in the table will be selected.

Examples

use ratatui::widgets::TableState;

let mut state = TableState::default();
state.scroll_down_by(4);

pub fn scroll_up_by(&mut self, amount: u16)

Scrolls up by a specified amount in the table.

This method updates the selected index by moving it up by the given amount. If the amount causes the index to go out of bounds (i.e., less than zero), the first row in the table will be selected.

Examples

use ratatui::widgets::TableState;

let mut state = TableState::default();
state.scroll_up_by(4);

pub fn scroll_right_by(&mut self, amount: u16)

Scrolls right by a specified amount in the table.

This method updates the selected index by moving it right by the given amount. If the amount causes the index to go out of bounds (i.e., if the index is greater than the number of columns in the table), the last column in the table will be selected.

Examples

let mut state = TableState::default();
state.scroll_right_by(4);

pub fn scroll_left_by(&mut self, amount: u16)

Scrolls left by a specified amount in the table.

This method updates the selected index by moving it left by the given amount. If the amount causes the index to go out of bounds (i.e., less than zero), the first item in the table will be selected.

Examples

let mut state = TableState::default();
state.scroll_left_by(4);

Trait Implementations

impl Clone for TableState

fn clone(&self) -> TableState

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for TableState

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

Formats the value using the given formatter.

impl Default for TableState

fn default() -> TableState

Returns the “default value” for a type.

impl Hash for TableState

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 PartialEq for TableState

fn eq(&self, other: &TableState) -> 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 Eq for TableState

impl StructuralPartialEq for TableState