Struct DefaultDelegate 

pub struct DefaultDelegate {
    pub show_description: bool,
    pub styles: DefaultItemStyles,
    /* private fields */
}

A delegate for rendering DefaultItem instances in list components.

This delegate provides the standard rendering logic for DefaultItem objects, handling different visual states, filtering highlights, and layout options. It implements the ItemDelegate trait to integrate seamlessly with the list component system.

Features

• Adaptive styling: Automatically adjusts colors for light/dark terminals
• State rendering: Handles normal, selected, and dimmed visual states
• Filter highlighting: Character-level highlighting of search matches
• Flexible layout: Configurable description display and item spacing
• Responsive design: Adjusts rendering based on available width

Configuration

The delegate can be customized through its public fields:

• show_description: Controls whether descriptions are rendered below titles
• styles: Complete styling configuration for all visual states

Usage with List

The delegate is designed to work with the Model<DefaultItem> list component and handles all the rendering complexity automatically.

Examples

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

// Create a delegate with default settings
let delegate = DefaultDelegate::new();

// Customize the delegate
let mut custom_delegate = DefaultDelegate::new();
custom_delegate.show_description = false; // Hide descriptions

// Use with a list
let items = vec![
    DefaultItem::new("Task 1", "First task description"),
    DefaultItem::new("Task 2", "Second task description"),
];
let list = Model::new(items, delegate, 80, 24);

Fields

show_description: bool

Whether to show the description beneath the title.

styles: DefaultItemStyles

Styling used for different visual states.

Implementations

impl DefaultDelegate

pub fn new() -> Self

Creates a new delegate with default styles and layout.

This is equivalent to DefaultDelegate::default() and provides a convenient constructor for creating a new delegate with standard settings.

Returns

A new DefaultDelegate configured with default settings suitable for most list use cases.

Examples

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

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

Trait Implementations

impl Clone for DefaultDelegate

fn clone(&self) -> DefaultDelegate

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DefaultDelegate

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for DefaultDelegate

fn default() -> Self

Creates a new delegate with default configuration.

The default delegate is configured with:

• Description display enabled
• Standard adaptive styling
• Height of 2 lines (title + description)
• 1 line spacing between items

This configuration provides a standard list appearance that matches the Go bubbles library defaults.

Examples

use bubbletea_widgets::list::DefaultDelegate;

let delegate = DefaultDelegate::default();
assert_eq!(delegate.show_description, true);

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

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

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

This method implements the complete rendering pipeline for list items, with special handling for filter highlighting that avoids common ANSI spacing issues.

Rendering Pipeline

1. State Detection: Determine if item is selected, dimmed, or has filter matches
2. Filter Highlighting: Apply character-level highlighting using segment-based approach
3. Style Application: Apply colors, borders, and padding based on item state
4. Layout Formatting: Combine title and description if enabled

Filter Highlighting Implementation

The filter highlighting system is complex due to lipgloss rendering behavior:

Problem

Lipgloss styles with padding add spaces when applied to individual text segments. If we pass styles with padding directly to apply_character_highlighting, we get:

• Input: “Nutella” with matches [0] (highlighting ‘N’)
• Expected: “│ Nutella”
• Actual: “│ N utella” (extra space between ‘N’ and ‘utella’)

Solution

1. Create “base” styles WITHOUT padding/borders for segment highlighting
2. Apply highlighting using these clean styles via apply_character_highlighting
3. Manually apply border and padding AFTER highlighting is complete

Selected vs Unselected Items

• Selected: Left border (│) + 1 space padding + colored text
• Unselected: No border + 2 spaces padding + normal text color

This approach ensures seamless text rendering while preserving visual hierarchy.

Arguments

• m - The list model containing state and filter information
• index - The index of this item in the current list view
• item - The item to render

Returns

A formatted string with ANSI styling codes. Returns empty string if list width is 0.

Visual States

• Normal: Standard appearance with left padding
• Selected: Highlighted with left border and accent colors
• Dimmed: Faded appearance when filter input is empty
• Filtered: Normal or selected appearance with character-level match highlighting

CRITICAL DEVELOPER NOTES - List Component Bug Fixes

This render method is part of comprehensive fixes for list component issues. READ THIS before modifying anything related to index handling!

Index Parameter Semantics (VERY IMPORTANT!)

The index parameter represents the original item index in the full items list, NOT a viewport-relative or filtered-relative position. This design is crucial for:

1. Cursor Highlighting: index == m.cursor comparison works correctly
2. Filter Highlighting: We can find matches by searching filtered_items
3. Viewport Scrolling: Highlighting persists across viewport changes

Fixed Bug Context

Previous issues that were resolved:

• Cursor highlighting loss: Caused by passing viewport-relative indices
• Filter input accumulation: Fixed by proper textinput event forwarding
• Viewport page jumping: Fixed by smooth scrolling implementation

System Integration

This method works with other fixes in mod.rs:

• sync_viewport_with_cursor(): Provides smooth viewport scrolling
• view_items(): Passes original indices instead of viewport-relative ones
• Filter input handlers: Ensure proper character accumulation

⚠️ WARNING: If you modify index handling here, ensure consistency with view_items()!

fn height(&self) -> usize

Returns the height in lines that each item occupies.

The height depends on whether descriptions are enabled:

• With descriptions: Returns the configured height (default 2 lines)
• Without descriptions: Always returns 1 line

This height is used by the list component for layout calculations, viewport sizing, and scroll positioning.

Returns

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

fn spacing(&self) -> usize

Returns the number of blank lines between items.

This spacing is added between each item in the list to improve readability and visual separation. The default spacing is 1 line.

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.

The default delegate implementation does not require any message handling, so this method always returns None. Override this method in custom delegates that need to respond to keyboard input, timer events, or other application messages.

Arguments

• _msg - The message to handle (unused in default implementation)
• _m - Mutable reference to the list model (unused in default implementation)

Returns

Always returns None as the default delegate requires no update commands.

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

Returns key bindings for the short help view.

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

Returns key bindings for the full help view.

fn on_select(&self, _index: usize, _item: &I) -> Option<Cmd>

Called when an item is selected (e.g., Enter key pressed).

fn on_remove(&self, _index: usize, _item: &I) -> Option<Cmd>

Called when an item is about to be removed.

fn can_remove(&self, _index: usize, _item: &I) -> bool

Determines whether an item can be removed.