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

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

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

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();

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();

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();

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();

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 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 Eq for ListState

impl StructuralPartialEq for ListState