Struct ListItem

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

A single item in a List

The item’s height is defined by the number of lines it contains. This can be queried using ListItem::height. Similarly, ListItem::width will return the maximum width of all lines.

You can set the style of an item with ListItem::style or using the Stylize trait. This Style will be combined with the Style of the inner Text. The Style of the Text will be added to the Style of the ListItem.

You can also align a ListItem by aligning its underlying Text and Lines. For that, see Text::alignment and Line::alignment. On a multiline Text, one Line can override the alignment by setting it explicitly.

Examples

You can create ListItems from simple &str

use ratatui::widgets::ListItem;
let item = ListItem::new("Item 1");

Anything that can be converted to Text can be a ListItem.

use ratatui::{text::Line, widgets::ListItem};

let item1: ListItem = "Item 1".into();
let item2: ListItem = Line::raw("Item 2").into();

A ListItem styled with Stylize

use ratatui::{style::Stylize, widgets::ListItem};

let item = ListItem::new("Item 1").red().on_white();

If you need more control over the item’s style, you can explicitly style the underlying Text

use ratatui::{
    style::Stylize,
    text::{Span, Text},
    widgets::ListItem,
};

let mut text = Text::default();
text.extend(["Item".blue(), Span::raw(" "), "1".bold().red()]);
let item = ListItem::new(text);

A right-aligned ListItem

use ratatui::{text::Text, widgets::ListItem};

ListItem::new(Text::from("foo").right_aligned());

Implementations

impl<'a> ListItem<'a>

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

where T: Into<Text<'a>>,

Creates a new ListItem

The content parameter accepts any value that can be converted into Text.

Examples

You can create ListItems from simple &str

use ratatui::widgets::ListItem;

let item = ListItem::new("Item 1");

Anything that can be converted to Text can be a ListItem.

use ratatui::{text::Line, widgets::ListItem};

let item1: ListItem = "Item 1".into();
let item2: ListItem = Line::raw("Item 2").into();

You can also create multiline items

use ratatui::widgets::ListItem;

let item = ListItem::new("Multi-line\nitem");

See also

• List::new to create a list of items that can be converted to ListItem

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

Sets the item style

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

This Style can be overridden by the Style of the Text content.

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

Example

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

let item = ListItem::new("Item 1").style(Style::new().red().italic());

ListItem 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::ListItem};

let item = ListItem::new("Item 1").red().italic();

pub fn height(&self) -> usize

Returns the item height

Examples

One line item

use ratatui::widgets::ListItem;

let item = ListItem::new("Item 1");
assert_eq!(item.height(), 1);

Two lines item (note the \n)

use ratatui::widgets::ListItem;

let item = ListItem::new("Multi-line\nitem");
assert_eq!(item.height(), 2);

pub fn width(&self) -> usize

Returns the max width of all the lines

Examples

use ratatui::widgets::ListItem;

let item = ListItem::new("12345");
assert_eq!(item.width(), 5);

use ratatui::widgets::ListItem;

let item = ListItem::new("12345\n1234567");
assert_eq!(item.width(), 7);

Trait Implementations

impl<'a> Clone for ListItem<'a>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for ListItem<'a>

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

Formats the value using the given formatter.

impl<'a, T> From<T> for ListItem<'a>

where T: Into<Text<'a>>,

fn from(value: T) -> Self

Converts to this type from the input type.

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

fn eq(&self, other: &ListItem<'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<'a> Styled for ListItem<'a>

type Item = ListItem<'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<'a> Eq for ListItem<'a>

impl<'a> StructuralPartialEq for ListItem<'a>