Crate tui_widget_list 

tui-widget-list: A versatile widget list for Ratatui

This crate provides a stateful ListView widget for Ratatui. The associated ListState handles navigation. The list view supports both horizontal and vertical scrolling.

Configuration

ListView can be customized with the following options:

• ListView::scroll_axis: Scroll vertically or horizontally.
• ListView::scroll_direction: Lay items out forward or in reverse.
• ListView::scroll_padding: Keep a number of items visible around the selected item while scrolling.
• ListView::infinite_scrolling: Wrap around when scrolling past the first or last item.
• ListView::style: Base style applied to the entire list.
• ListView::block: Optional surrounding block.
• ListView::scrollbar: Optional scrollbar overlay.

Example

 use ratatui::prelude::*;
 use tui_widget_list::{ListBuilder, ListState, ListView};

 let builder = ListBuilder::new(|context| {
     let mut item = Line::from(format!("Item {}", context.index));
     if context.is_selected {
         item = item.style(Style::default().bg(Color::Rgb(255, 153, 0)));
     }
     (item, 1)
 });

 let mut state = ListState::default();
 let list = ListView::new(builder, 20);

Mouse handling

Handle mouse clicks and scroll events using ListState::hit_test:

 use tui_widget_list::hit_test::Hit;

 match event::read()? {
     Event::Mouse(MouseEvent {
         kind: MouseEventKind::Down(MouseButton::Left),
         column,
         row,
         ..
     }) => match state.hit_test(column, row) {
         Some(Hit::Item(index)) => state.select(Some(index)),
         Some(Hit::Area) | None => {}
     },
     Event::Mouse(MouseEvent {
         kind: MouseEventKind::ScrollUp,
         ..
     }) => {
         state.previous();
     }
     Event::Mouse(MouseEvent {
         kind: MouseEventKind::ScrollDown,
         ..
     }) => {
         state.next();
     }
     _ => {}
 }

Documentation

For more examples see the examples directory. Full API documentation is available on docs.rs.

Modules

hit_test

Structs

ListBuildContext

This structure holds information about the item’s position, selection status, scrolling behavior, and size along the cross axis.

ListBuilder

The builder for constructing list elements in a ListView<T>

ListState

ListView

A struct representing a list view. The widget displays a scrollable list of items.

Enums

ScrollAxis

Represents the scroll axis of a list.

ScrollDirection

Represents the scroll direction of a list.