Crate bubbletea_widgets

bubbletea-widgets

A Rust port of the Go library charmbracelet/bubbles, providing reusable TUI components for building terminal applications with bubbletea-rs.

Overview

bubbletea-widgets offers a collection of common terminal UI components that can be easily integrated into bubbletea-rs applications. Each component follows the Elm Architecture pattern with init(), update(), and view() methods, providing a consistent and predictable API for building complex terminal user interfaces.

Features

• Type-safe key bindings with comprehensive key combination support
• Focus management system for keyboard navigation between components
• Responsive design with automatic width/height handling
• Theming support through customizable styles
• Go compatibility for easy migration from charmbracelet/bubbles
• Performance optimized with efficient rendering and state management

Components

• Input Components: TextInput, TextArea, FilePicker
• Display Components: List, Table, Progress, Spinner, Help
• Utility Components: Cursor, Viewport, Paginator, Timer, Stopwatch

Focus Management

All components implement the Component trait which provides standardized focus management:

use bubbletea_widgets::prelude::*;
use bubbletea_rs::Cmd;

fn handle_focus<T: Component>(component: &mut T) {
    let _cmd: Option<Cmd> = component.focus();
    assert!(component.focused());
    component.blur();
    assert!(!component.focused());
}

// Example with a text area (implements Component trait)
let mut textarea = textarea_new();
handle_focus(&mut textarea);

Key Bindings

Components use the type-safe key binding system from the key module:

use bubbletea_widgets::key::{Binding, KeyMap};
use crossterm::event::{KeyCode, KeyModifiers};

// Create key bindings
let confirm = Binding::new(vec![KeyCode::Enter])
    .with_help("enter", "Confirm selection");

let save = Binding::new(vec![(KeyCode::Char('s'), KeyModifiers::CONTROL)])
    .with_help("ctrl+s", "Save file");

// Implement KeyMap for your component
struct MyKeyMap {
    confirm: Binding,
    save: Binding,
}

impl KeyMap for MyKeyMap {
    fn short_help(&self) -> Vec<&Binding> {
        vec![&self.confirm, &self.save]
    }

    fn full_help(&self) -> Vec<Vec<&Binding>> {
        vec![
            vec![&self.confirm],
            vec![&self.save],
        ]
    }
}

Integration with bubbletea-rs

Components are designed to work seamlessly with bubbletea-rs models:

use bubbletea_widgets::prelude::*;
use bubbletea_rs::{Model, Cmd, Msg};

struct App {
    input: TextInput,
}

impl Model for App {
    fn init() -> (Self, Option<Cmd>) {
        let mut input = textinput_new();
        let focus_cmd = input.focus();
        (Self { input }, Some(focus_cmd))
    }

    fn update(&mut self, msg: Msg) -> Option<Cmd> {
        // Handle component updates
        if let Some(cmd) = self.input.update(msg) {
            return Some(cmd);
        }

        // Handle other messages
        match msg {
            // Your app-specific message handling
            _ => None,
        }
    }

    fn view(&self) -> String {
        format!("Enter text: {}\n{}", self.input.view(), "Press Ctrl+C to quit")
    }
}

Quick Start

Add bubbletea-widgets to your Cargo.toml:

[dependencies]
bubbletea-widgets = "0.1.0"
bubbletea-rs = "0.0.7"
crossterm = "0.27"

For convenience, you can import the prelude:

use bubbletea_widgets::prelude::*;

Component Overview

Component	Description	Use Case
TextInput	Single-line text input	Forms, search boxes
TextArea	Multi-line text editor	Code editing, long text
List	Scrollable item list	Menus, file browsers
Table	Tabular data display	Data tables, spreadsheets
Progress	Progress bar with animation	Loading indicators
Spinner	Animated loading spinner	Background operations
Help	Key binding help display	User guidance
FilePicker	File system navigator	File selection
Timer	Countdown timer	Time-based operations
Stopwatch	Elapsed time tracker	Performance monitoring

Re-exports

pub use cursor::Model as Cursor;

pub use filepicker::Model as FilePicker;

pub use help::Model as HelpModel;

pub use key::matches;

pub use key::matches_binding;

pub use key::new_binding;

pub use key::with_disabled;

pub use key::with_help;

pub use key::with_keys;

pub use key::Binding;

pub use key::Help as KeyHelp;

pub use key::KeyMap;

pub use key::KeyPress;

pub use list::Model as List;

pub use list::DefaultDelegate as ListDefaultDelegate;

pub use list::DefaultItem as ListDefaultItem;

pub use list::DefaultItemStyles as ListDefaultItemStyles;

pub use list::FilterState;

pub use list::FilterStateInfo;

pub use list::ListKeyMap;

pub use list::ListStyles;

pub use paginator::Model as Paginator;

pub use progress::Model as Progress;

pub use spinner::new as spinner_new;

pub use spinner::with_spinner;

pub use spinner::with_style;

pub use spinner::Model as Spinner;

pub use spinner::SpinnerOption;

pub use spinner::TickMsg as SpinnerTickMsg;

pub use spinner::DOT;

pub use spinner::ELLIPSIS;

pub use spinner::GLOBE;

pub use spinner::HAMBURGER;

pub use spinner::JUMP;

pub use spinner::LINE;

pub use spinner::METER;

pub use spinner::MINI_DOT;

pub use spinner::MONKEY;

pub use spinner::MOON;

pub use spinner::POINTS;

pub use spinner::PULSE;

pub use stopwatch::Model as Stopwatch;

pub use table::Model as Table;

pub use textarea::default_styles as textarea_default_styles;

pub use textarea::new as textarea_new;

pub use textarea::LineInfo;

pub use textarea::Model as TextArea;

pub use textarea::PasteErrMsg as TextAreaPasteErrMsg;

pub use textarea::PasteMsg as TextAreaPasteMsg;

pub use textinput::blink;

pub use textinput::default_key_map as textinput_default_key_map;

pub use textinput::new as textinput_new;

pub use textinput::paste;

pub use textinput::EchoMode;

pub use textinput::KeyMap as TextInputKeyMap;

pub use textinput::Model as TextInput;

pub use textinput::PasteErrMsg;

pub use textinput::PasteMsg;

pub use textinput::ValidateFunc;

pub use timer::new as timer_new;

pub use timer::new_with_interval as timer_new_with_interval;

pub use timer::Model as Timer;

pub use timer::StartStopMsg as TimerStartStopMsg;

pub use timer::TickMsg as TimerTickMsg;

pub use timer::TimeoutMsg as TimerTimeoutMsg;

pub use viewport::Model as Viewport;

Modules

cursor

Cursor component for Bubble Tea-style text inputs.

filepicker

File picker component for browsing and selecting files in terminal applications.

help

A help component for bubbletea-rs, ported from the Go version.

key

Key binding component for managing keybindings, ported from the Go version.

list

List component with filtering, pagination, contextual help, and customizable rendering.

paginator

A paginator component for bubbletea-rs, ported from the Go version.

prelude

Prelude module for convenient imports.

progress

Progress component for Bubble Tea applications.

spinner

Spinner component for Bubble Tea applications.

stopwatch

High-precision stopwatch component for measuring elapsed time in Bubble Tea applications.

table

Interactive data table component with navigation, selection, and scrolling capabilities.

textarea

Textarea component for Bubble Tea applications.

textinput

Text input component for Bubble Tea applications.

timer

Timer component for Bubble Tea applications.

viewport

Scrollable viewport component for displaying large content in terminal applications.

Traits

Component

Core trait for components that support focus management.