Trait ItemDelegate

pub trait ItemDelegate<I: Item> {
    // Required methods
    fn render(&self, m: &Model<I>, index: usize, item: &I) -> String;
    fn height(&self) -> usize;
    fn spacing(&self) -> usize;
    fn update(&self, msg: &Msg, m: &mut Model<I>) -> Option<Cmd>;
}

Core traits and types for list functionality.

These are the fundamental building blocks for creating custom list items and delegates:

• Item: Trait for displayable and filterable list items
• ItemDelegate: Trait for customizing item rendering and behavior
• FilterState: Enum representing the current filtering state
• FilterStateInfo: Detailed information about filter status

Examples

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

#[derive(Clone)]
struct MyItem {
    name: String,
    value: i32,
}

impl Display for MyItem {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}: {}", self.name, self.value)
    }
}

impl Item for MyItem {
    fn filter_value(&self) -> String {
        format!("{} {}", self.name, self.value)
    }
}

Trait for customizing how list items are rendered and behave.

The ItemDelegate trait allows you to completely customize the appearance and behavior of items in a list. This includes rendering individual items, defining their height and spacing, and handling custom update logic.

Examples

// Multi-line delegate that shows item + description
struct DetailedDelegate;

impl<I: Item> ItemDelegate<I> for DetailedDelegate {
    fn height(&self) -> usize {
        2 // Title line + description line
    }
}

Required Methods

fn render(&self, m: &Model<I>, index: usize, item: &I) -> String

Renders an item as a string for display in the list.

This method is called for each visible item and should return a styled string representation. The method receives the complete model state, the item’s original index, and the item itself.

Arguments

• m - The complete list model with current state
• index - The original index of this item in the full items list
• item - The item to render

Returns

A formatted string with any necessary ANSI styling codes.

Examples

struct CustomDelegate;

impl<I: Item + Send + Sync + 'static> ItemDelegate<I> for CustomDelegate {
    fn render(&self, m: &Model<I>, index: usize, item: &I) -> String {
        if index == m.cursor() {
            format!("> {}", item)  // Highlight selected item
        } else {
            format!("  {}", item)  // Normal item
        }
    }
}

fn height(&self) -> usize

Returns the height in terminal lines that each item occupies.

This value is used by the list for layout calculations, viewport sizing, and scroll positioning. It should include any line breaks or multi-line content in your rendered items.

Returns

The number of terminal lines each item will occupy when rendered.

Examples

struct MultiLineDelegate;

impl<I: Item> ItemDelegate<I> for MultiLineDelegate {
    fn height(&self) -> usize {
        3  // Item title + description + blank line
    }
}

fn spacing(&self) -> usize

Returns the number of blank lines to insert between items.

This spacing is added between each item in the list to improve readability and visual separation. The spacing is in addition to the height returned by height().

Returns

The number of blank lines to insert between rendered items.

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

Handles update messages for the delegate.

This method allows delegates to respond to messages and potentially modify the list state or return commands. Most delegates don’t need custom update logic and can return None.

Arguments

• msg - The message to handle
• m - Mutable reference to the list model

Returns

An optional command to be executed by the runtime.

Examples

struct InteractiveDelegate;

impl<I: Item> ItemDelegate<I> for InteractiveDelegate {
    fn update(&self, msg: &Msg, m: &mut Model<I>) -> Option<Cmd> {
        // Example: Handle custom key press
        if let Some(key_msg) = msg.downcast_ref::<KeyMsg>() {
            if key_msg.key == KeyCode::Char(' ') {
                // Custom space key behavior
                return None;
            }
        }
        None
    }
}

Implementors

impl<I: Item + 'static> ItemDelegate<I> for DefaultDelegate