Struct List

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

A widget to display several items among which one can be selected (optional)

A list is a collection of ListItems.

This is different from a Table because it does not handle columns, headers or footers and the item’s height is automatically determined. A List can also be put in reverse order (i.e. bottom to top) whereas a Table cannot.

List items can be aligned using Text::alignment, for more details see ListItem.

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

List is also a StatefulWidget, which means you can use it with ListState to allow the user to scroll through items and select one of them.

See the list in the Examples directory for a more in depth example of the various configuration options and for how to handle state.

Fluent setters

• List::highlight_style sets the style of the selected item.
• List::highlight_symbol sets the symbol to be displayed in front of the selected item.
• List::repeat_highlight_symbol sets whether to repeat the symbol and style over selected multi-line items
• List::direction sets the list direction

Examples

use ratatui::{
    layout::Rect,
    style::{Style, Stylize},
    widgets::{Block, List, ListDirection, ListItem},
    Frame,
};

let items = ["Item 1", "Item 2", "Item 3"];
let list = List::new(items)
    .block(Block::bordered().title("List"))
    .style(Style::new().white())
    .highlight_style(Style::new().italic())
    .highlight_symbol(">>")
    .repeat_highlight_symbol(true)
    .direction(ListDirection::BottomToTop);

frame.render_widget(list, area);

Stateful example

use ratatui::{
    layout::Rect,
    style::{Style, Stylize},
    widgets::{Block, List, ListState},
    Frame,
};

// This should be stored outside of the function in your application state.
let mut state = ListState::default();
let items = ["Item 1", "Item 2", "Item 3"];
let list = List::new(items)
    .block(Block::bordered().title("List"))
    .highlight_style(Style::new().reversed())
    .highlight_symbol(">>")
    .repeat_highlight_symbol(true);

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

In addition to List::new, any iterator whose element is convertible to ListItem can be collected into List.

use ratatui::widgets::List;

(0..5).map(|i| format!("Item{i}")).collect::<List>();

Implementations

impl<'a> List<'a>

pub fn new<T>(items: T) -> Self

where T: IntoIterator, T::Item: Into<ListItem<'a>>,

Creates a new list from ListItems

The items parameter accepts any value that can be converted into an iterator of Into<ListItem>. This includes arrays of &str or Vecs of Text.

Example

From a slice of &str

use ratatui::widgets::List;

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

From Text

use ratatui::{
    style::{Style, Stylize},
    text::Text,
    widgets::List,
};

let list = List::new([
    Text::styled("Item 1", Style::new().red()),
    Text::styled("Item 2", Style::new().red()),
]);

You can also create an empty list using the Default implementation and use the List::items fluent setter.

use ratatui::widgets::List;

let empty_list = List::default();
let filled_list = empty_list.items(["Item 1"]);

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

where T: IntoIterator, T::Item: Into<ListItem<'a>>,

Set the items

The items parameter accepts any value that can be converted into an iterator of Into<ListItem>. This includes arrays of &str or Vecs of Text.

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

Example

use ratatui::widgets::List;

let list = List::default().items(["Item 1", "Item 2"]);

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

Wraps the list with a custom Block widget.

The block parameter holds the specified Block to be created around the List

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

Examples

use ratatui::widgets::{Block, List};

let items = ["Item 1"];
let block = Block::bordered().title("List");
let list = List::new(items).block(block);

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, ListItem::style, or the styles of the ListItem’s content.

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

Examples

use ratatui::{
    style::{Style, Stylize},
    widgets::List,
};

let items = ["Item 1"];
let list = List::new(items).style(Style::new().red().italic());

List 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::{style::Stylize, widgets::List};

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

pub const fn highlight_symbol(self, highlight_symbol: &'a str) -> Self

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

By default there are no highlight symbol.

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

Examples

use ratatui::widgets::List;

let items = ["Item 1", "Item 2"];
let list = List::new(items).highlight_symbol(">>");

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

Set the style of the selected item

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 item, including the highlight symbol if it is displayed, and will override any style set on the item or on the individual cells.

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

Examples

use ratatui::{
    style::{Style, Stylize},
    widgets::List,
};

let items = ["Item 1", "Item 2"];
let list = List::new(items).highlight_style(Style::new().red().italic());

pub const fn repeat_highlight_symbol(self, repeat: bool) -> Self

Set whether to repeat the highlight symbol and style over selected multi-line items

This is false by default.

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

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 (if enabled) and is used to shift the list when an item is selected. This method allows you to configure when this spacing is allocated.

• HighlightSpacing::Always will always allocate the spacing, regardless of whether an item is selected or not. This means that the table will never change size, regardless of if an item is selected or not.
• HighlightSpacing::WhenSelected will only allocate the spacing if an item is selected. This means that the table will shift when an item 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 an item 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::widgets::{HighlightSpacing, List};

let items = ["Item 1"];
let list = List::new(items).highlight_spacing(HighlightSpacing::Always);

pub const fn direction(self, direction: ListDirection) -> Self

Defines the list direction (up or down)

Defines if the List is displayed top to bottom (default) or bottom to top. If there is too few items to fill the screen, the list will stick to the starting edge.

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

Example

Bottom to top

use ratatui::widgets::{List, ListDirection};

let items = ["Item 1"];
let list = List::new(items).direction(ListDirection::BottomToTop);

pub const fn scroll_padding(self, padding: usize) -> Self

Sets the number of items around the currently selected item that should be kept visible

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

Example

A padding value of 1 will keep 1 item above and 1 item bellow visible if possible

use ratatui::widgets::List;

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

pub fn len(&self) -> usize

Returns the number of ListItems in the list

pub fn is_empty(&self) -> bool

Returns true if the list contains no elements.

Trait Implementations

impl<'a> Clone for List<'a>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for List<'a>

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

Formats the value using the given formatter.

impl<'a> Default for List<'a>

fn default() -> List<'a>

Returns the “default value” for a type.

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

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

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

Creates a value from an iterator.

impl<'a> Hash for List<'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 List<'a>

fn eq(&self, other: &List<'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 &List<'_>

type State = ListState

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 List<'_>

type State = ListState

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 List<'_>

type State = ListState

State associated with the stateful widget.

fn render_ref(&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<'a> Styled for List<'a>

type Item = List<'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 List<'_>

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 List<'_>

fn render_ref(&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<'a> Eq for List<'a>

impl<'a> StructuralPartialEq for List<'a>