bubble-t

A Rust reimagining of the Bubble Tea TUI framework — inspired by, and paying homage to, the original Go project from Charmbracelet.

Repository: github.com/Nexlab-One/Bubble-T

Build terminal user interfaces with the Model-View-Update pattern, async commands, and rich styling.

Status: Active development. Core APIs are stabilizing under the bubble-t crate (formerly bubbletea-rs).

Monorepo layout

This repository is a single Cargo workspace containing the full Rust Bubble Tea ecosystem:

Crate	Path	Purpose
bubble-t	crates/bubble-t	Core MVU framework with async runtime
bubble-t-layout	crates/bubble-t-layout	Cassowary constraint layout (Layout, Constraint, Rect)
bubble-t-widgets	crates/bubble-t-widgets	MVU widgets + native frame widgets (bubble_t_widgets::frame)
ansi	crates/ansi	ANSI/OSC escape builders + incremental parser (port of x/ansi)
cellbuf	crates/cellbuf	Width-aware styled cell grid + screen diff
colorprofile	crates/colorprofile	Terminal color profile detection + downsampling
term	crates/term	Cross-platform raw mode, TTY, and size
harmonica	crates/harmonica	Spring animations (progress widget)
lipgloss	crates/lipgloss	Terminal styling, compositing (Canvas/Compositor), OutputContext
lipgloss-list	crates/lipgloss-list	Styled vertical lists
lipgloss-table	crates/lipgloss-table	Styled tables
lipgloss-tree	crates/lipgloss-tree	Tree diagrams
lipgloss-extras	crates/lipgloss-extras	Feature-gated facade over lipgloss components
bubble-zone	crates/bubble-zone	Mouse hit zones with async scan worker (BubbleZone)
ntcharts	crates/ntcharts	Terminal charting: line, bar, sparkline, heatmap, braille
glamour	crates/glamour	Markdown renderer with themes, syntax highlight, emoji

Quick start

From GitHub (current recommended install — crates are not yet on crates.io):

[dependencies]
bubble-t = { git = "https://github.com/Nexlab-One/Bubble-T" }
bubble-t-widgets = { git = "https://github.com/Nexlab-One/Bubble-T" }
lipgloss-extras = { git = "https://github.com/Nexlab-One/Bubble-T", features = ["full"] }
tokio = { version = "1", features = ["full"] }

From this monorepo (path dependencies, e.g. for a new examples/ crate):

[dependencies]
bubble-t = { path = "../crates/bubble-t" }
bubble-t-widgets = { path = "../crates/bubble-t-widgets" }
lipgloss-extras = { path = "../crates/lipgloss-extras", features = ["full"] }
tokio = { version = "1", features = ["full"] }

From crates.io (when published):

[dependencies]
bubble-t = "0.1.12"
bubble-t-widgets = "0.1.12"
lipgloss-extras = { version = "0.1.12", features = ["full"] }
tokio = { version = "1", features = ["full"] }

Minimal application:

use bubble_t::{Model, Msg, Cmd, Program};

struct App { count: i32 }

impl Model for App {
    fn init() -> (Self, Option<Cmd>) {
        (Self { count: 0 }, None)
    }
    fn update(&mut self, _msg: Msg) -> Option<Cmd> { None }
    fn view(&self) -> View {
        View::new(format!("count: {}", self.count))
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    Program::<App>::builder().build()?.run().await?;
    Ok(())
}

Native layout and frame widgets

Use constraint layout and cell-buffer widgets without changing the MVU loop:

use bubble_t::{Model, View, /* ... */};
use bubble_t_layout::{Constraint, Layout, Rect};
use bubble_t_widgets::frame::{Block, Borders, Paragraph};
use cellbuf::Frame;

fn view(&self) -> View {
    View::new("").render_frame(|frame: &mut Frame| {
        let area = Rect::new(0, 0, self.width, self.height);
        let [header, body] = Layout::vertical([
            Constraint::Length(3),
            Constraint::Fill(1),
        ]).areas(area);
        frame.render_widget(Block::new().title("App").borders(Borders::ALL), header.to_rectangle());
        frame.render_widget(Paragraph::new("Hello"), body.to_rectangle());
    })
}

See examples/native-layout, examples/frame-widgets, and docs/NATIVE-TUI-CAPABILITY-MATRIX.md.

Examples

50 examples mirror the upstream Go Bubble Tea gallery, including three v2-specific demos (capability, cursor-color, keyboard-enhancements). See examples/README.md.

Unified showcase — browse ecosystem crates and widget demos from one menu:

cargo run -p showcase-example

Individual examples:

cd examples/simple
cargo run

Or from the workspace root:

cargo run -p simple-example

Development

Requires Rust 1.92+ (edition 2024). The repo pins stable via rust-toolchain.toml.

cargo test --workspace --all-features
cargo fmt --all
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo doc --no-deps --all-features

Documentation

• bubble-t API — core MVU framework
• bubble-t-widgets API — UI components
• lipgloss API — styling and layout
• CHANGELOG — release history

Inspiration and credits

• Bubble Tea (Go) — original design and inspiration
• Charm — CLI design philosophy
• Elm Architecture — Model-View-Update pattern
• Original Rust ports by whit3rabbit; fork maintained by Nexlab-One

License

MIT — see LICENSE.