tui_widget_list/
lib.rs

1//! # A versatile widget list for Ratatui
2//!
3//!<div align="center">
4//!     
5//! [![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)
6//!
7//! </div>
8//!
9//! This crate provides a stateful widget [`ListView`] implementation for `Ratatui`. The associated [`ListState`], offers functionalities such as navigating to the next and previous items.
10//! The list view support both horizontal and vertical scrolling.
11//!
12//! ## Configuration
13//! The [`ListView`] can be customized with the following options:
14//! - [`ListView::scroll_axis`]: Specifies whether the list is vertically or horizontally scrollable.
15//!
16//! - [`ListView::scroll_padding`]: Specifies whether content should remain visible while scrolling, ensuring that a specified amount of padding is preserved above/below the selected item during scrolling.
17//! - [`ListView::infinite_scrolling`]: Allows the list to wrap around when scrolling past the first or last element.
18//! - [`ListView::style`]: Defines the base style of the list.
19//! - [`ListView::block`]: Optional outer block surrounding the list.
20//!
21//! ## Example
22//!```
23//! use ratatui::prelude::*;
24//! use tui_widget_list::{ListBuilder, ListState, ListView};
25//!
26//! #[derive(Debug, Clone)]
27//! pub struct ListItem {
28//!     text: String,
29//!     style: Style,
30//! }
31//!
32//! impl ListItem {
33//!     pub fn new<T: Into<String>>(text: T) -> Self {
34//!         Self {
35//!             text: text.into(),
36//!             style: Style::default(),
37//!         }
38//!     }
39//! }
40//!
41//! impl Widget for ListItem {
42//!     fn render(self, area: Rect, buf: &mut Buffer) {
43//!         Line::from(self.text).style(self.style).render(area, buf);
44//!     }
45//! }
46//!
47//! pub struct App {
48//!     state: ListState,
49//! }
50//!
51//! impl Widget for &mut App {
52//!     fn render(self, area: Rect, buf: &mut Buffer) {
53//!         let builder = ListBuilder::new(|context| {
54//!            let mut item = ListItem::new(&format!("Item {:0}", context.index));
55//!
56//!            // Alternating styles
57//!            if context.index % 2 == 0 {
58//!                item.style = Style::default().bg(Color::Rgb(28, 28, 32));
59//!            } else {
60//!                item.style = Style::default().bg(Color::Rgb(0, 0, 0));
61//!            }
62//!
63//!            // Style the selected element
64//!            if context.is_selected {
65//!                item.style = Style::default()
66//!                    .bg(Color::Rgb(255, 153, 0))
67//!                    .fg(Color::Rgb(28, 28, 32));
68//!            };
69//!
70//!            // Return the size of the widget along the main axis.
71//!            let main_axis_size = 1;
72//!
73//!            (item, main_axis_size)
74//!         });
75//!
76//!         let item_count = 2;
77//!         let list = ListView::new(builder, item_count);
78//!         let state = &mut self.state;
79//!
80//!         list.render(area, buf, state);
81//!     }
82//! }
83//!```
84//!
85//! For more examples see [tui-widget-list](https://github.com/preiter93/tui-widget-list/tree/main/examples).
86//!
87//! ## Documentation
88//! [docs.rs](https://docs.rs/tui-widget-list/)
89//!
90//! ## Demos
91//!
92//! ### Demo
93//!
94//!![](examples/tapes/demo.gif?v=1)
95//!
96//! ### Infinite scrolling, scroll padding, horizontal scrolling
97//!
98//!![](examples/tapes/variants.gif?v=1)
99pub(crate) mod legacy;
100pub(crate) mod state;
101pub(crate) mod utils;
102pub(crate) mod view;
103
104pub use state::ListState;
105pub use view::{ListBuildContext, ListBuilder, ListView, ScrollAxis};
106
107#[allow(deprecated)]
108pub use legacy::{
109    traits::{PreRender, PreRenderContext},
110    widget::List,
111};
tui_widget_list/lib.rs

tui_widget_list/
lib.rs
