Struct ListState

pub struct ListState { /* private fields */ }

State of the List widget

This state can be used to scroll through items and select one. When the list is rendered as a stateful widget, the selected item will be highlighted and the list will be shifted to ensure that the selected item is visible. This will modify the ListState object passed to the Frame::render_stateful_widget method.

The state consists of two fields:

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

See the list 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::Rect,
    widgets::{List, ListState},
    Frame,
};

let items = ["Item 1"];
let list = List::new(items);

// This should be stored outside of the function in your application state.
let mut state = ListState::default();

*state.offset_mut() = 1; // display the second item and onwards
state.select(Some(3)); // select the forth item (0-indexed)

frame.render_stateful_widget(list, area, &mut state);

Implementations

impl ListState

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

Sets the index of the first item to be displayed

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

Examples

use ratatui::widgets::ListState;

let state = ListState::default().with_offset(1);

pub const fn with_selected(self, selected: Option<usize>) -> Self

Sets the index of the selected item

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

Examples

use ratatui::widgets::ListState;

let state = ListState::default().with_selected(Some(1));

Examples found in repository

examples/demo2/tabs/email.rs (line 103)

fn render_inbox(selected_index: usize, area: Rect, buf: &mut Buffer) {
    let vertical = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
    let [tabs, inbox] = vertical.areas(area);
    let theme = THEME.email;
    Tabs::new(vec![" Inbox ", " Sent ", " Drafts "])
        .style(theme.tabs)
        .highlight_style(theme.tabs_selected)
        .select(0)
        .divider("")
        .render(tabs, buf);

    let highlight_symbol = ">>";
    let from_width = EMAILS
        .iter()
        .map(|e| e.from.width())
        .max()
        .unwrap_or_default();
    let items = EMAILS.iter().map(|e| {
        let from = format!("{:width$}", e.from, width = from_width).into();
        ListItem::new(Line::from(vec![from, " ".into(), e.subject.into()]))
    });
    let mut state = ListState::default().with_selected(Some(selected_index));
    StatefulWidget::render(
        List::new(items)
            .style(theme.inbox)
            .highlight_style(theme.selected_item)
            .highlight_symbol(highlight_symbol),
        inbox,
        buf,
        &mut state,
    );
    let mut scrollbar_state = ScrollbarState::default()
        .content_length(EMAILS.len())
        .position(selected_index);
    Scrollbar::default()
        .begin_symbol(None)
        .end_symbol(None)
        .track_symbol(None)
        .thumb_symbol("▐")
        .render(inbox, buf, &mut scrollbar_state);
}

pub const fn offset(&self) -> usize

Index of the first item to be displayed

Examples

use ratatui::widgets::ListState;

let state = ListState::default();
assert_eq!(state.offset(), 0);

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

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

Examples

use ratatui::widgets::ListState;

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

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

Index of the selected item

Returns None if no item is selected

Examples

use ratatui::widgets::ListState;

let state = ListState::default();
assert_eq!(state.selected(), None);

Examples found in repository

examples/list.rs (line 165)

    fn toggle_status(&mut self) {
        if let Some(i) = self.todo_list.state.selected() {
            self.todo_list.items[i].status = match self.todo_list.items[i].status {
                Status::Completed => Status::Todo,
                Status::Todo => Status::Completed,
            }
        }
    }
}

impl Widget for &mut App {
    fn render(self, area: Rect, buf: &mut Buffer) {
        let [header_area, main_area, footer_area] = Layout::vertical([
            Constraint::Length(2),
            Constraint::Fill(1),
            Constraint::Length(1),
        ])
        .areas(area);

        let [list_area, item_area] =
            Layout::vertical([Constraint::Fill(1), Constraint::Fill(1)]).areas(main_area);

        App::render_header(header_area, buf);
        App::render_footer(footer_area, buf);
        self.render_list(list_area, buf);
        self.render_selected_item(item_area, buf);
    }
}

/// Rendering logic for the app
impl App {
    fn render_header(area: Rect, buf: &mut Buffer) {
        Paragraph::new("Ratatui List Example")
            .bold()
            .centered()
            .render(area, buf);
    }

    fn render_footer(area: Rect, buf: &mut Buffer) {
        Paragraph::new("Use ↓↑ to move, ← to unselect, → to change status, g/G to go top/bottom.")
            .centered()
            .render(area, buf);
    }

    fn render_list(&mut self, area: Rect, buf: &mut Buffer) {
        let block = Block::new()
            .title(Line::raw("TODO List").centered())
            .borders(Borders::TOP)
            .border_set(symbols::border::EMPTY)
            .border_style(TODO_HEADER_STYLE)
            .bg(NORMAL_ROW_BG);

        // Iterate through all elements in the `items` and stylize them.
        let items: Vec<ListItem> = self
            .todo_list
            .items
            .iter()
            .enumerate()
            .map(|(i, todo_item)| {
                let color = alternate_colors(i);
                ListItem::from(todo_item).bg(color)
            })
            .collect();

        // Create a List from all list items and highlight the currently selected one
        let list = List::new(items)
            .block(block)
            .highlight_style(SELECTED_STYLE)
            .highlight_symbol(">")
            .highlight_spacing(HighlightSpacing::Always);

        // We need to disambiguate this trait method as both `Widget` and `StatefulWidget` share the
        // same method name `render`.
        StatefulWidget::render(list, area, buf, &mut self.todo_list.state);
    }

    fn render_selected_item(&self, area: Rect, buf: &mut Buffer) {
        // We get the info depending on the item's state.
        let info = if let Some(i) = self.todo_list.state.selected() {
            match self.todo_list.items[i].status {
                Status::Completed => format!("✓ DONE: {}", self.todo_list.items[i].info),
                Status::Todo => format!("☐ TODO: {}", self.todo_list.items[i].info),
            }
        } else {
            "Nothing selected...".to_string()
        };

        // We show the list item's info under the list in this paragraph
        let block = Block::new()
            .title(Line::raw("TODO Info").centered())
            .borders(Borders::TOP)
            .border_set(symbols::border::EMPTY)
            .border_style(TODO_HEADER_STYLE)
            .bg(NORMAL_ROW_BG)
            .padding(Padding::horizontal(1));

        // We can now render the item info
        Paragraph::new(info)
            .block(block)
            .fg(TEXT_FG_COLOR)
            .wrap(Wrap { trim: false })
            .render(area, buf);
    }

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

Mutable reference to the index of the selected item

Returns None if no item is selected

Examples

use ratatui::widgets::ListState;

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

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

Sets the index of the selected item

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

Examples

use ratatui::widgets::ListState;

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

Examples found in repository

examples/list.rs (line 145)

    fn select_none(&mut self) {
        self.todo_list.state.select(None);
    }

pub fn select_next(&mut self)

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

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

Examples

use ratatui::widgets::ListState;

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

Examples found in repository

examples/list.rs (line 149)

    fn select_next(&mut self) {
        self.todo_list.state.select_next();
    }

pub fn select_previous(&mut self)

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

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

Examples

use ratatui::widgets::ListState;

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

Examples found in repository

examples/list.rs (line 152)

    fn select_previous(&mut self) {
        self.todo_list.state.select_previous();
    }

pub fn select_first(&mut self)

Selects the first item

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

Examples

use ratatui::widgets::ListState;

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

Examples found in repository

examples/list.rs (line 156)

    fn select_first(&mut self) {
        self.todo_list.state.select_first();
    }

pub fn select_last(&mut self)

Selects the last item

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

Examples

use ratatui::widgets::ListState;

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

Examples found in repository

examples/list.rs (line 160)

    fn select_last(&mut self) {
        self.todo_list.state.select_last();
    }

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

Scrolls down by a specified amount in the list.

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 length of the list), the last item in the list will be selected.

Examples

use ratatui::widgets::ListState;

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

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

Scrolls up by a specified amount in the list.

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 item in the list will be selected.

Examples

use ratatui::widgets::ListState;

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

Trait Implementations

impl Clone for ListState

fn clone(&self) -> ListState

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ListState

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

Formats the value using the given formatter.

impl Default for ListState

fn default() -> ListState

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ListState

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Hash for ListState

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 ListState

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

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for ListState

impl StructuralPartialEq for ListState