tui_widget_list/
lib.rs

1//!<div align="center">
2//!
3//! # A versatile widget list for Ratatui
4//!
5//! [![Crate Badge]](https://crates.io/crates/tui-widget-list) [![Continuous Integration](https://github.com/preiter93/tui-widget-list/actions/workflows/ci.yml/badge.svg)](https://github.com/preiter93/tui-widget-list/actions/workflows/ci.yml) [![Deps Status](https://deps.rs/repo/github/preiter93/tui-widget-list/status.svg)](https://deps.rs/repo/github/preiter93/tui-widget-list) [![License Badge]](./LICENSE)
6//!
7//! </div>
8//!
9//! This crate provides a stateful widget [`ListView`] implementation for `Ratatui`.
10//! The associated [`ListState`], offers functionalities such as navigating to the next and previous items.
11//! The list view support both horizontal and vertical scrolling.
12//!
13//! ## Configuration
14//! The [`ListView`] can be customized with the following options:
15//! - [`ListView::scroll_axis`]: Specifies whether the list is vertically or horizontally scrollable.
16//! - [`ListView::scroll_padding`]: Specifies whether content should remain visible while scrolling, ensuring that a
17//!   specified amount of padding is preserved above/below the selected item during scrolling.
18//! - [`ListView::infinite_scrolling`]: Allows the list to wrap around when scrolling past the first or last element.
19//! - [`ListView::style`]: Defines the base style of the list.
20//! - [`ListView::block`]: Optional outer block surrounding the list.
21//! - [`ListView::scrollbar`]: Optional scrollbar widget.
22//!
23//! ## Example
24//!```
25//! use ratatui::prelude::*;
26//! use tui_widget_list::{ListBuilder, ListState, ListView};
27//!
28//! #[derive(Debug, Clone)]
29//! pub struct ListItem {
30//!     text: String,
31//!     style: Style,
32//! }
33//!
34//! impl ListItem {
35//!     pub fn new<T: Into<String>>(text: T) -> Self {
36//!         Self {
37//!             text: text.into(),
38//!             style: Style::default(),
39//!         }
40//!     }
41//! }
42//!
43//! impl Widget for ListItem {
44//!     fn render(self, area: Rect, buf: &mut Buffer) {
45//!         Line::from(self.text).style(self.style).render(area, buf);
46//!     }
47//! }
48//!
49//! pub struct App {
50//!     state: ListState,
51//! }
52//!
53//! impl Widget for &mut App {
54//!     fn render(self, area: Rect, buf: &mut Buffer) {
55//!         let builder = ListBuilder::new(|context| {
56//!            let mut item = ListItem::new(&format!("Item {:0}", context.index));
57//!
58//!            // Alternating styles
59//!            if context.index % 2 == 0 {
60//!                item.style = Style::default().bg(Color::Rgb(28, 28, 32));
61//!            } else {
62//!                item.style = Style::default().bg(Color::Rgb(0, 0, 0));
63//!            }
64//!
65//!            // Style the selected element
66//!            if context.is_selected {
67//!                item.style = Style::default()
68//!                    .bg(Color::Rgb(255, 153, 0))
69//!                    .fg(Color::Rgb(28, 28, 32));
70//!            };
71//!
72//!            // Return the size of the widget along the main axis.
73//!            let main_axis_size = 1;
74//!
75//!            (item, main_axis_size)
76//!         });
77//!
78//!         let item_count = 2;
79//!         let list = ListView::new(builder, item_count);
80//!         let state = &mut self.state;
81//!
82//!         list.render(area, buf, state);
83//!     }
84//! }
85//!```
86//!
87//! ## Mouse handling
88//!
89//! You can handle mouse clicks using `ListState` via `hit_test`:
90//!```ignore
91//! match event::read()? {
92//!     Event::Mouse(MouseEvent {
93//!         kind: MouseEventKind::Down(MouseButton::Left),
94//!         column, row, ..
95//!     }) => {
96//!         match state.hit_test(column, row) {
97//!             Some(tui_widget_list::hit_test::Hit::Item(index)) => state.select(Some(index)),
98//!             Some(tui_widget_list::hit_test::Hit::Area) | None => {}
99//!         }
100//!         }
101//!     }
102//!     Event::Mouse(MouseEvent { kind: MouseEventKind::ScrollUp, .. }) => {
103//!         state.previous();
104//!     }
105//!     Event::Mouse(MouseEvent { kind: MouseEventKind::ScrollDown, .. }) => {
106//!         state.next();
107//!     }
108//!     _ => {}
109//! }
110//!```
111//!
112//! For more examples see [tui-widget-list](https://github.com/preiter93/tui-widget-list/tree/main/examples).
113//!
114//! ## Documentation
115//! [docs.rs](https://docs.rs/tui-widget-list/)
116//!
117//! ## Demo
118//!
119//! ### Infinite scrolling, scroll padding, horizontal scrolling
120//!
121//!![](examples/tapes/variants.gif?v=1)
122//!
123//! [Crate Badge]: https://img.shields.io/crates/v/tui-widget-list?logo=rust&style=flat-square&logoColor=E05D44&color=E05D44
124//! [License Badge]: https://img.shields.io/crates/l/tui-widget-list?style=flat-square&color=1370D3
125pub mod hit_test;
126pub(crate) mod state;
127pub(crate) mod utils;
128pub(crate) mod view;
129
130pub use state::ListState;
131pub use view::{ListBuildContext, ListBuilder, ListView, ScrollAxis};
tui_widget_list/lib.rs

tui_widget_list/
lib.rs
