Bubbletea — Functional TUI Framework for Go

Introduction

Bubbletea is a Go framework for building terminal applications using a functional, Elm-inspired architecture. It separates state management from rendering, making even complex TUIs predictable and testable.

What Bubbletea Does

• Provides an Elm Architecture (Model-Update-View) loop for terminal apps
• Handles keyboard, mouse, and window-resize events out of the box
• Supports asynchronous I/O through commands and subscriptions
• Integrates with Lip Gloss for styling and Bubbles for reusable components
• Runs on Linux, macOS, and Windows terminals without platform-specific code

Architecture Overview

A Bubbletea program revolves around a single Model struct that holds application state. The runtime sends messages (events) to an Update function that returns a new model and optional commands. The View function renders the model to a string. Commands are side-effect functions that return messages asynchronously, keeping the main loop pure and deterministic.

Self-Hosting & Configuration

• Install via go get github.com/charmbracelet/bubbletea
• Requires Go 1.18 or later
• No external dependencies beyond the Go standard library and Charm ecosystem packages
• Configure alternate input/output with tea.WithInput() and tea.WithOutput() options
• Enable mouse support via tea.WithMouseCellMotion() or tea.WithMouseAllMotion()

Key Features

• Pure functional update loop makes state transitions explicit and easy to test
• Built-in support for full-screen, alternate-screen, and inline rendering modes
• First-class concurrency through commands (one-off) and subscriptions (streams)
• Works with the Bubbles component library (text inputs, spinners, tables, viewports)
• Minimal binary size and fast startup due to zero CGO dependencies

Comparison with Similar Tools

• tview — imperative widget API; Bubbletea is functional and composable
• Textual (Python) — similar Elm-style approach but for Python; Bubbletea targets Go
• Ratatui (Rust) — lower-level immediate-mode rendering; Bubbletea is higher-level with managed state
• Ink (JS) — React-like TUI for Node; Bubbletea avoids a virtual DOM in favor of plain strings
• ncurses — C library for cursor control; Bubbletea abstracts away raw terminal escape codes

FAQ

Q: Can I use Bubbletea for non-interactive CLI tools? A: Yes. You can run a program in non-interactive mode or use it purely for styled output alongside Lip Gloss.

Q: How do I test a Bubbletea program? A: Call your Update function directly with synthetic messages and assert on the returned model. No terminal required.

Q: Does it support Windows Terminal? A: Yes. Bubbletea works on Windows Terminal, PowerShell, and cmd.exe with full color and mouse support.

Q: Can multiple Bubbletea programs run concurrently? A: Each program manages its own goroutine and I/O; you can embed one inside another using the Bubbles viewport pattern.

Sources

• https://github.com/charmbracelet/bubbletea
• https://charm.sh/libs/bubbletea/