Struct Model 

pub struct Model<I: Item> { /* private fields */ }

The main list component model.

Model<I> is a generic list component that can display any items implementing the Item trait. It provides filtering, navigation, pagination, and customizable rendering through the delegate pattern.

Type Parameters

• I - The item type that must implement Item + Send + Sync + 'static

Examples

use bubbletea_widgets::list::{Model, DefaultDelegate, DefaultItem};

let items = vec![
    DefaultItem::new("Apple", "Red fruit"),
    DefaultItem::new("Banana", "Yellow fruit"),
];
let list = Model::new(items, DefaultDelegate::new(), 80, 24);

A flexible, interactive list component with filtering, pagination, and customizable rendering.

The Model<I> is the main list component that can display any items implementing the Item trait. It provides fuzzy filtering, keyboard navigation, viewport scrolling, help integration, and customizable styling through delegates.

Features

• Fuzzy filtering: Real-time search with character-level highlighting
• Smooth scrolling: Viewport-based navigation that maintains context
• Customizable rendering: Delegate pattern for complete visual control
• Keyboard navigation: Vim-style keys plus standard arrow navigation
• Contextual help: Automatic help text generation from key bindings
• Responsive design: Adapts to different terminal sizes
• State management: Clean separation of filtering, selection, and view states

Architecture

The list uses a viewport-based scrolling system that maintains smooth navigation context instead of discrete page jumps. Items are rendered using delegates that control appearance and behavior, while filtering uses fuzzy matching with character-level highlighting for search results.

Navigation

• Up/Down: Move cursor through items with smooth viewport scrolling
• Page Up/Down: Jump by pages while maintaining cursor visibility
• Home/End: Jump to first/last item
• / : Start filtering
• Enter: Accept filter (while filtering)
• Escape: Cancel filter (while filtering)
• Ctrl+C: Clear active filter

Filtering

The list supports fuzzy filtering with real-time preview:

• Type “/” to start filtering
• Type characters to filter items in real-time
• Matched characters are highlighted in the results
• Press Enter to accept the filter or Escape to cancel

Styling

Visual appearance is controlled through the ListStyles struct and item delegates. The list adapts to light/dark terminal themes automatically and supports customizable colors, borders, and typography.

Examples

use bubbletea_widgets::list::{Model, DefaultDelegate, DefaultItem};

let items = vec![
    DefaultItem::new("Task 1", "Complete documentation"),
    DefaultItem::new("Task 2", "Review pull requests"),
];
let delegate = DefaultDelegate::new();
let list = Model::new(items, delegate, 80, 24);

With Custom Items

use bubbletea_widgets::list::{Item, Model, DefaultDelegate};
use std::fmt::Display;

#[derive(Clone)]
struct CustomItem {
    title: String,
    priority: u8,
}

impl Display for CustomItem {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "[{}] {}", self.priority, self.title)
    }
}

impl Item for CustomItem {
    fn filter_value(&self) -> String {
        format!("{} priority:{}", self.title, self.priority)
    }
}

let items = vec![
    CustomItem { title: "Fix bug".to_string(), priority: 1 },
    CustomItem { title: "Add feature".to_string(), priority: 2 },
];
let list = Model::new(items, DefaultDelegate::new(), 80, 24);

Implementations

impl<I: Item + Send + Sync + 'static> Model<I>

pub fn is_filtering(&self) -> bool

Returns true if filtering is currently active in any form.

This method provides a simple way to check if the list is in any filtering state (either actively typing a filter or has an applied filter). It’s useful for applications that need to conditionally show UI elements or change behavior based on filtering status.

Returns

• true if in Filtering or FilterApplied state
• false if in Unfiltered state

Examples

use bubbletea_widgets::list::{Model, DefaultDelegate, DefaultItem, FilterState};

let items = vec![DefaultItem::new("Apple", "Red fruit")];
let mut list = Model::new(items, DefaultDelegate::new(), 80, 24);

assert!(!list.is_filtering()); // Initially not filtering

// Simulate applying a filter (would normally be done through user input)
list.set_filter_text("app");
// In a real application, filter would be applied through the update() method
assert!(!list.is_filtering()); // Still not filtering until state changes

pub fn clear_filter(&mut self) -> Option<Cmd>

Forces complete filter clearing in a single operation.

This method provides a programmatic way to completely clear any active filter, equivalent to the user pressing the clear filter key binding. It’s useful for applications that need to reset the list state or implement custom clear functionality.

Returns

Returns None as no follow-up commands are needed for the clear operation.

Effects

• Clears the filter input text
• Sets state to Unfiltered
• Clears filtered items list
• Resets cursor to position 0
• Updates pagination

Examples

use bubbletea_widgets::list::{Model, DefaultDelegate, DefaultItem};

let items = vec![DefaultItem::new("Apple", "Red fruit")];
let mut list = Model::new(items, DefaultDelegate::new(), 80, 24);

// Apply a filter (this would normally be done through user interaction)
list.set_filter_text("app");

// Clear it programmatically
let cmd = list.clear_filter();
assert!(cmd.is_none()); // Returns None
assert!(!list.is_filtering()); // No longer filtering

pub fn filter_state_info(&self) -> FilterStateInfo

Returns detailed information about the current filter state.

This method provides comprehensive information about filtering without requiring direct access to internal fields. It’s particularly useful for applications that need to display filter status information or make decisions based on detailed filter state.

Returns

A FilterStateInfo struct containing:

• Current filter state enum
• Filter query text
• Number of matching items
• Whether filtering is active
• Whether currently in clearing state

Examples

use bubbletea_widgets::list::{Model, DefaultDelegate, DefaultItem, FilterState};

let items = vec![
    DefaultItem::new("Apple", "Red fruit"),
    DefaultItem::new("Banana", "Yellow fruit"),
];
let mut list = Model::new(items, DefaultDelegate::new(), 80, 24);

// Check initial state
let info = list.filter_state_info();
assert_eq!(info.state, FilterState::Unfiltered);
assert_eq!(info.query, "");
assert_eq!(info.match_count, 2); // All items visible
assert!(!info.is_filtering);
assert!(!info.is_clearing);

// Set filter text (would be applied through user interaction)
list.set_filter_text("app");
let info = list.filter_state_info();
assert_eq!(info.query, "app"); // Query is set

impl<I: Item + Send + Sync + 'static> Model<I>

pub fn new<D>(items: Vec<I>, delegate: D, width: usize, height: usize) -> Self

where D: ItemDelegate<I> + Send + Sync + 'static,

Creates a new list with the provided items, delegate, and dimensions.

This is the primary constructor for creating a list component. The delegate controls how items are rendered and behave, while the dimensions determine the initial size for layout calculations.

Arguments

• items - Vector of items to display in the list
• delegate - Item delegate that controls rendering and behavior
• width - Initial width in terminal columns (can be updated later)
• height - Initial height in terminal rows (affects pagination)

Returns

A new Model<I> configured with default settings:

• Title set to “List”
• 10 items per page
• Cursor at position 0
• All items initially visible (no filtering)
• Status bar enabled with default item names

Examples

use bubbletea_widgets::list::{Model, DefaultDelegate, DefaultItem};

let items = vec![
    DefaultItem::new("First", "Description 1"),
    DefaultItem::new("Second", "Description 2"),
];

let list = Model::new(items, DefaultDelegate::new(), 80, 24);
assert_eq!(list.len(), 2);

pub fn set_items(&mut self, items: Vec<I>)

Sets the items displayed in the list.

This method replaces all current items with the provided vector. The cursor is reset to position 0, and pagination is recalculated based on the new item count.

Arguments

• items - Vector of new items to display

Examples

let mut list = Model::new(vec![], DefaultDelegate::new(), 80, 24);

let items = vec![
    DefaultItem::new("Apple", "Red fruit"),
    DefaultItem::new("Banana", "Yellow fruit"),
];
list.set_items(items);
assert_eq!(list.len(), 2);

pub fn visible_items(&self) -> Vec<I>

Returns a vector of currently visible items.

The returned items reflect the current filtering state:

• When unfiltered: returns all items
• When filtered: returns only items matching the current filter

Returns

A vector containing clones of all currently visible items.

Examples

let items = vec![
    DefaultItem::new("First", "Description 1"),
    DefaultItem::new("Second", "Description 2"),
];

let list = Model::new(items, DefaultDelegate::new(), 80, 24);
let visible = list.visible_items();
assert_eq!(visible.len(), 2);

pub fn set_filter_text(&mut self, s: &str)

Sets the filter text without applying the filter.

This method updates the filter input text but does not trigger the filtering process. It’s primarily used for programmatic filter setup or testing.

Arguments

• s - The filter text to set

Examples

let mut list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
list.set_filter_text("search term");
// Filter text is set but not applied until filtering is activated

pub fn set_filter_state(&mut self, st: FilterState)

Sets the current filtering state.

This method directly controls the list’s filtering state without triggering filter application. It’s useful for programmatic state management or testing specific filter conditions.

Arguments

• st - The new filter state to set

Examples

let mut list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
list.set_filter_state(FilterState::Filtering);
// List is now in filtering mode

pub fn set_status_bar_item_name(&mut self, singular: &str, plural: &str)

Sets custom singular and plural names for status bar items.

The status bar displays item counts using these names. If not set, defaults to “item” and “items”.

Arguments

• singular - Name for single item (e.g., “task”)
• plural - Name for multiple items (e.g., “tasks”)

Examples

let mut list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
list.set_status_bar_item_name("task", "tasks");
// Status bar will now show "1 task" or "5 tasks"

pub fn set_size(&mut self, width: usize, height: usize)

Updates the list dimensions and recalculates layout.

This method allows dynamic resizing of the list to match terminal size changes, similar to the Go bubbles list’s SetSize method. It updates both width and height, then recalculates pagination to show the appropriate number of items.

Arguments

• width - New width in terminal columns
• height - New height in terminal rows

Examples

let mut list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);

// Resize list to match new terminal size
list.set_size(100, 30);
assert_eq!(list.width(), 100);
assert_eq!(list.height(), 30);

pub fn width(&self) -> usize

Returns the current width of the list.

Returns

The current width in terminal columns.

pub fn height(&self) -> usize

Returns the current height of the list.

Returns

The current height in terminal rows.

pub fn per_page(&self) -> usize

Returns the current items per page setting.

Returns

The number of items displayed per page.

pub fn total_pages(&self) -> usize

Returns the total number of pages in the paginator.

Returns

The total number of pages based on item count and per_page setting.

pub fn calculate_element_height(&self, element: &str) -> usize

Calculates the actual rendered height of UI elements based on their known configurations.

This method mimics Go’s lipgloss.Height() function by using the known style configurations to determine how many terminal lines each element will actually occupy when rendered, matching the default padding values set in style.rs.

Arguments

• element - A string identifier for the UI element type

Returns

The total number of terminal lines this element will occupy.

pub fn len(&self) -> usize

Returns the number of currently visible items.

This count reflects the items actually visible to the user:

• When unfiltered: returns the total number of items
• When filtering is active: returns only the count of matching items

Returns

The number of items currently visible in the list.

Examples

let items = vec![
    DefaultItem::new("Apple", "Red"),
    DefaultItem::new("Banana", "Yellow"),
];
let list = Model::new(items, DefaultDelegate::new(), 80, 24);
assert_eq!(list.len(), 2);

pub fn is_empty(&self) -> bool

Returns whether the list has no visible items.

Returns

true if there are no currently visible items, false otherwise.

Examples

let list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
assert!(list.is_empty());

pub fn selected_item(&self) -> Option<&I>

Returns a reference to the currently selected item.

The selected item is the one at the current cursor position. If the list is empty or the cursor is out of bounds, returns None.

Returns

A reference to the selected item, or None if no valid selection exists.

Examples

let items = vec![
    DefaultItem::new("First", "Description 1"),
    DefaultItem::new("Second", "Description 2"),
];
let list = Model::new(items, DefaultDelegate::new(), 80, 24);

if let Some(selected) = list.selected_item() {
    println!("Selected: {}", selected);
}

pub fn cursor(&self) -> usize

Returns the current cursor position.

The cursor represents the currently selected item index within the visible (possibly filtered) list. This is always relative to the currently visible items, not the original full list.

Returns

The zero-based index of the currently selected item.

Examples

let items = vec![
    DefaultItem::new("First", "Description"),
    DefaultItem::new("Second", "Description"),
];
let list = Model::new(items, DefaultDelegate::new(), 80, 24);
assert_eq!(list.cursor(), 0); // Initially at first item

pub fn matches_for_original_item( &self, original_index: usize, ) -> Option<&Vec<usize>>

Returns fuzzy match character indices for a given original item index.

This method finds the character positions that matched the current filter for a specific item identified by its original index in the full items list. These indices can be used for character-level highlighting in custom delegates.

Arguments

• original_index - The original index of the item in the full items list

Returns

A reference to the vector of character indices that matched the filter, or None if no matches exist for this item or if filtering is not active.

Examples

let items = vec![DefaultItem::new("Apple", "Red fruit")];
let mut list = Model::new(items, DefaultDelegate::new(), 80, 24);

// Apply a filter first
list.set_filter_text("app");
// In a real application, this would be done through user interaction

if let Some(matches) = list.matches_for_original_item(0) {
    // matches contains the character indices that matched "app" in "Apple"
    println!("Matched characters at indices: {:?}", matches);
}

pub fn with_title(self, title: &str) -> Self

Sets the list title (builder pattern).

The title is displayed at the top of the list when not filtering. During filtering, the title is replaced with the filter input interface.

Arguments

• title - The new title for the list

Returns

Self, for method chaining.

Examples

let list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24)
    .with_title("My Tasks");

pub fn with_show_pagination(self, show: bool) -> Self

Sets pagination display visibility (builder pattern).

Arguments

• show - true to show pagination, false to hide it

Returns

Self, for method chaining.

Examples

let list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24)
    .with_show_pagination(false);
assert!(!list.show_pagination());

pub fn with_pagination_type(self, pagination_type: Type) -> Self

Sets the pagination type (builder pattern).

Arguments

• pagination_type - The type of pagination to display

Returns

Self, for method chaining.

Examples

let list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24)
    .with_pagination_type(Type::Dots);
assert_eq!(list.pagination_type(), Type::Dots);

pub fn with_show_title(self, show: bool) -> Self

Sets title display visibility (builder pattern).

Arguments

• show - true to show title, false to hide it

Returns

Self, for method chaining.

Examples

let list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24)
    .with_show_title(false);
assert!(!list.show_title());

pub fn with_show_status_bar(self, show: bool) -> Self

Sets status bar display visibility (builder pattern).

Arguments

• show - true to show status bar, false to hide it

Returns

Self, for method chaining.

Examples

let list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24)
    .with_show_status_bar(false);
assert!(!list.show_status_bar());

pub fn with_show_spinner(self, show: bool) -> Self

Sets spinner display visibility (builder pattern).

Arguments

• show - true to show spinner, false to hide it

Returns

Self, for method chaining.

Examples

let list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24)
    .with_show_spinner(true);
assert!(list.show_spinner());

pub fn with_show_help(self, show: bool) -> Self

Sets help display visibility (builder pattern).

Arguments

• show - true to show help, false to hide it

Returns

Self, for method chaining.

Examples

let list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24)
    .with_show_help(true);
assert!(list.show_help());

pub fn with_styles(self, styles: ListStyles) -> Self

Sets the list’s styling configuration (builder pattern).

This replaces all current styles with the provided configuration.

Arguments

• styles - The styling configuration to apply

Returns

Self, for method chaining.

Examples

let custom_styles = ListStyles::default();
let list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24)
    .with_styles(custom_styles);

pub fn show_pagination(&self) -> bool

Returns whether pagination is currently shown.

Returns

true if pagination is displayed, false otherwise.

Examples

let list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
assert!(list.show_pagination()); // pagination is shown by default

pub fn set_show_pagination(&mut self, show: bool)

Sets whether pagination should be displayed.

When disabled, the pagination section will not be rendered in the list view, but pagination state and navigation will continue to work normally.

Arguments

• show - true to show pagination, false to hide it

Examples

let mut list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
list.set_show_pagination(false);
assert!(!list.show_pagination());

pub fn toggle_pagination(&mut self) -> bool

Toggles pagination display on/off.

This is a convenience method that flips the current pagination display state.

Returns

The new pagination display state after toggling.

Examples

let mut list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
let new_state = list.toggle_pagination();
assert_eq!(new_state, list.show_pagination());

pub fn pagination_type(&self) -> Type

Returns the current pagination type (Arabic or Dots).

Returns

The pagination type currently configured for this list.

Examples

let list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
let pagination_type = list.pagination_type();

pub fn set_pagination_type(&mut self, pagination_type: Type)

Sets the pagination display type.

This controls how pagination is rendered:

• paginator::Type::Arabic: Shows “1/5” style numbering
• paginator::Type::Dots: Shows “• ○ • ○ •” style dots

Arguments

• pagination_type - The type of pagination to display

Examples

let mut list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
list.set_pagination_type(Type::Dots);
assert_eq!(list.pagination_type(), Type::Dots);

pub fn insert_item(&mut self, index: usize, item: I)

Inserts an item at the specified index.

All items at and after the specified index are shifted to the right. The cursor and pagination are updated appropriately.

Arguments

• index - The position to insert the item at
• item - The item to insert

Panics

Panics if index > len().

Examples

let mut list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
list.insert_item(0, DefaultItem::new("First", "Description"));
assert_eq!(list.len(), 1);

pub fn remove_item(&mut self, index: usize) -> I

Removes and returns the item at the specified index.

All items after the specified index are shifted to the left. The cursor and pagination are updated appropriately.

Arguments

• index - The position to remove the item from

Returns

The removed item.

Panics

Panics if index >= len().

Examples

let mut list = Model::new(
    vec![DefaultItem::new("First", "Desc")],
    DefaultDelegate::new(), 80, 24
);
let removed = list.remove_item(0);
assert_eq!(list.len(), 0);

pub fn move_item(&mut self, from_index: usize, to_index: usize)

Moves an item from one position to another.

The item at from_index is removed and inserted at to_index. The cursor is updated to follow the moved item if it was selected.

Arguments

• from_index - The current position of the item to move
• to_index - The target position to move the item to

Panics

Panics if either index is out of bounds.

Examples

let mut list = Model::new(
    vec![
        DefaultItem::new("First", "1"),
        DefaultItem::new("Second", "2"),
    ],
    DefaultDelegate::new(), 80, 24
);
list.move_item(0, 1); // Move "First" to position 1

pub fn push_item(&mut self, item: I)

Adds an item to the end of the list.

This is equivalent to insert_item(len(), item).

Arguments

• item - The item to add

Examples

let mut list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
list.push_item(DefaultItem::new("New Item", "Description"));
assert_eq!(list.len(), 1);

pub fn pop_item(&mut self) -> Option<I>

Removes and returns the last item from the list.

Returns

The last item, or None if the list is empty.

Examples

let mut list = Model::new(
    vec![DefaultItem::new("Item", "Desc")],
    DefaultDelegate::new(), 80, 24
);
let popped = list.pop_item();
assert!(popped.is_some());
assert_eq!(list.len(), 0);

pub fn items(&self) -> &[I]

Returns a reference to the underlying items collection.

This provides read-only access to all items in the list, regardless of the current filtering state.

Returns

A slice containing all items in the list.

Examples

let items = vec![DefaultItem::new("First", "1"), DefaultItem::new("Second", "2")];
let list = Model::new(items.clone(), DefaultDelegate::new(), 80, 24);
assert_eq!(list.items().len(), 2);
assert_eq!(list.items()[0].to_string(), items[0].to_string());

pub fn items_mut(&mut self) -> &mut Vec<I>

Returns a mutable reference to the underlying items collection.

This provides direct mutable access to the items. Note that after modifying items through this method, you should call update_pagination() to ensure pagination state remains consistent.

Warning: Direct modification may invalidate the current filter state. Consider using the specific item manipulation methods instead.

Returns

A mutable slice containing all items in the list.

Examples

let mut list = Model::new(
    vec![DefaultItem::new("First", "1")],
    DefaultDelegate::new(), 80, 24
);
list.items_mut()[0] = DefaultItem::new("Modified", "Updated");
assert_eq!(list.items()[0].to_string(), "Modified");

pub fn items_len(&self) -> usize

Returns the total number of items in the list.

This returns the count of all items, not just visible items. For visible items count, use len().

Returns

The total number of items in the underlying collection.

Examples

let list = Model::new(
    vec![DefaultItem::new("1", ""), DefaultItem::new("2", "")],
    DefaultDelegate::new(), 80, 24
);
assert_eq!(list.items_len(), 2);

pub fn items_empty(&self) -> bool

Returns whether the underlying items collection is empty.

This checks the total items count, not just visible items. For visible items check, use is_empty().

Returns

true if there are no items in the underlying collection, false otherwise.

Examples

let list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
assert!(list.items_empty());

pub fn show_title(&self) -> bool

Returns whether the title is currently shown.

Returns

true if the title is displayed, false otherwise.

Examples

let list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
assert!(list.show_title()); // title is shown by default

pub fn set_show_title(&mut self, show: bool)

Sets whether the title should be displayed.

When disabled, the title section will not be rendered in the list view.

Arguments

• show - true to show the title, false to hide it

Examples

let mut list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
list.set_show_title(false);
assert!(!list.show_title());

pub fn toggle_title(&mut self) -> bool

Toggles title display on/off.

This is a convenience method that flips the current title display state.

Returns

The new title display state after toggling.

Examples

let mut list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
let new_state = list.toggle_title();
assert_eq!(new_state, list.show_title());

pub fn show_status_bar(&self) -> bool

Returns whether the status bar is currently shown.

Returns

true if the status bar is displayed, false otherwise.

Examples

let list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
assert!(list.show_status_bar()); // status bar is shown by default

pub fn set_show_status_bar(&mut self, show: bool)

Sets whether the status bar should be displayed.

When disabled, the status bar section will not be rendered in the list view.

Arguments

• show - true to show the status bar, false to hide it

Examples

let mut list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
list.set_show_status_bar(false);
assert!(!list.show_status_bar());

pub fn toggle_status_bar(&mut self) -> bool

Toggles status bar display on/off.

This is a convenience method that flips the current status bar display state.

Returns

The new status bar display state after toggling.

Examples

let mut list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
let new_state = list.toggle_status_bar();
assert_eq!(new_state, list.show_status_bar());

pub fn show_spinner(&self) -> bool

Returns whether the spinner is currently shown.

Returns

true if the spinner is displayed, false otherwise.

Examples

let list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
assert!(!list.show_spinner()); // spinner is hidden by default

pub fn set_show_spinner(&mut self, show: bool)

Sets whether the spinner should be displayed.

When enabled, the spinner will be rendered as part of the list view, typically to indicate loading state.

Arguments

• show - true to show the spinner, false to hide it

Examples

let mut list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
list.set_show_spinner(true);
assert!(list.show_spinner());

pub fn toggle_spinner(&mut self) -> bool

Toggles spinner display on/off.

This is a convenience method that flips the current spinner display state.

Returns

The new spinner display state after toggling.

Examples

let mut list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
let new_state = list.toggle_spinner();
assert_eq!(new_state, list.show_spinner());

pub fn spinner(&self) -> &Model

Returns a reference to the spinner model.

This allows access to the underlying spinner for customization and state management.

Returns

A reference to the spinner model.

Examples

let list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
let spinner = list.spinner();

pub fn spinner_mut(&mut self) -> &mut Model

Returns a mutable reference to the spinner model.

This allows modification of the underlying spinner for customization and state management.

Returns

A mutable reference to the spinner model.

Examples

let mut list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
let spinner = list.spinner_mut();

pub fn show_help(&self) -> bool

Returns whether the help is currently shown.

Returns

true if help is displayed, false otherwise.

Examples

let list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
assert!(list.show_help()); // help is shown by default

pub fn set_show_help(&mut self, show: bool)

Sets whether help should be displayed.

When enabled, help text will be rendered as part of the list view, showing available key bindings and controls.

Arguments

• show - true to show help, false to hide it

Examples

let mut list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
list.set_show_help(true);
assert!(list.show_help());

pub fn toggle_help(&mut self) -> bool

Toggles help display on/off.

This is a convenience method that flips the current help display state.

Returns

The new help display state after toggling.

Examples

let mut list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
let new_state = list.toggle_help();
assert_eq!(new_state, list.show_help());

pub fn help(&self) -> &Model

Returns a reference to the help model.

This allows access to the underlying help system for customization and state management.

Returns

A reference to the help model.

Examples

let list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
let help = list.help();

pub fn help_mut(&mut self) -> &mut Model

Returns a mutable reference to the help model.

This allows modification of the underlying help system for customization and state management.

Returns

A mutable reference to the help model.

Examples

let mut list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
let help = list.help_mut();

pub fn styles(&self) -> &ListStyles

Returns a reference to the list’s styling configuration.

This provides read-only access to all visual styles used by the list, including title, item, status bar, pagination, and help styles.

Returns

A reference to the ListStyles configuration.

Examples

let list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
let styles = list.styles();
// Access specific styles, e.g., styles.title, styles.pagination_style

pub fn styles_mut(&mut self) -> &mut ListStyles

Returns a mutable reference to the list’s styling configuration.

This provides direct mutable access to all visual styles used by the list. Changes to styles take effect immediately on the next render.

Returns

A mutable reference to the ListStyles configuration.

Examples

let mut list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
let styles = list.styles_mut();
styles.title = Style::new().foreground("#FF0000"); // Red title

pub fn set_styles(&mut self, styles: ListStyles)

Sets the list’s styling configuration.

This replaces all current styles with the provided configuration. Changes take effect immediately on the next render.

Arguments

• styles - The new styling configuration to apply

Examples

let mut list: Model<DefaultItem> = Model::new(vec![], DefaultDelegate::new(), 80, 24);
let custom_styles = ListStyles::default();
list.set_styles(custom_styles);

pub fn status_view(&self) -> String

Renders the status bar as a formatted string.

The status bar shows the current selection position and total item count, using the custom item names if set. The format is “X/Y items” where X is the current cursor position + 1, and Y is the total item count.

Returns

A formatted status string, or empty string if status bar is disabled.

Examples

let items = vec![
    DefaultItem::new("First", ""),
    DefaultItem::new("Second", ""),
];
let list = Model::new(items, DefaultDelegate::new(), 80, 24);
let status = list.status_view();
assert!(status.contains("1/2"));

Trait Implementations

impl<I: Item> KeyMap for Model<I>

fn short_help(&self) -> Vec<&Binding>

Returns key bindings for compact help display.

Provides a minimal set of the most important key bindings based on the current list state. The bindings change depending on whether the user is actively filtering or navigating.

Context-Sensitive Help

• While filtering: Shows Enter (accept) and Escape (cancel) bindings
• Normal navigation: Shows up/down navigation and filter activation

fn full_help(&self) -> Vec<Vec<&Binding>>

Returns all key bindings organized into logical groups.

Provides comprehensive help information with bindings grouped by functionality. The grouping helps users understand related actions and discover advanced features.

Binding Groups

1. Cursor movement: Up/down navigation
2. Page navigation: Page up/down, home/end
3. Filtering: Start filter, clear filter, accept
4. Help and quit: Show help, quit application

impl<I: Item + Send + Sync + 'static> Model for Model<I>

fn init() -> (Self, Option<Cmd>)

Initializes a new empty list model with default settings.

This creates a new list with no items, using the default delegate and standard dimensions. This method is called by the BubbleTea runtime when the model is first created.

Returns

A tuple containing:

• The initialized list model with default settings
• None (no initial command to execute)

Default Configuration

• Empty items list
• DefaultDelegate for rendering
• 80 columns × 24 rows dimensions
• Default styling and key bindings

fn update(&mut self, msg: Msg) -> Option<Cmd>

Handles keyboard input and state updates.

This method processes all user input and updates the list state accordingly. It implements different input handling modes based on the current filtering state:

While Filtering (FilterState::Filtering)

• Escape: Cancel filtering, return to previous state
• Enter: Accept current filter, change to FilterApplied state
• Characters: Add to filter text, update results in real-time
• Backspace: Remove characters from filter
• Arrow keys: Navigate filter input cursor position

Normal Navigation (other states)

• Up/Down: Move cursor through items with smooth viewport scrolling
• Page Up/Page Down: Move cursor by one page (viewport height)
• Home/End: Jump to first/last item
• / : Start filtering mode
• Ctrl+C: Clear any active filter

Viewport and Paginator Management

The update method automatically:

• Manages viewport scrolling to ensure the cursor remains visible
• Synchronizes the paginator component to reflect the current page

fn view(&self) -> String

Renders the complete list view as a formatted string.

This method combines all visual components of the list into a single string suitable for terminal display. The layout adapts based on the current filtering state and available content.

Returns

A formatted string containing the complete list UI with ANSI styling codes.

Layout Structure

The view consists of three vertically stacked sections:

1. Header: Title or filter input (depending on state)

   • Normal: “List Title” or “List Title (filtered: N)”
   • Filtering: “Filter: > user_input”

2. Items: The main content area showing visible items

   • Styled according to the current delegate
   • Shows “No items” message when empty
   • Viewport-based rendering for large lists

3. Footer: Status and help information

   • Status: “X/Y items” format
   • Help: Context-sensitive key bindings

Performance

The view method only renders items currently visible in the viewport, ensuring consistent performance regardless of total item count.

Examples

let list = Model::new(
    vec![DefaultItem::new("Item 1", "Description")],
    DefaultDelegate::new(),
    80, 24
);

let output = list.view();
// Contains formatted list with title, items, and status bar