Bubble Tea

Bubble Tea is a Go framework for building terminal user interfaces (TUIs) using the paradigms of The Elm Architecture. Programs are written as a Model with three methods — Init, Update, and View — and the runtime drives I/O, input, and rendering. The library ships as the Go module charm.land/bubbletea/v2 and powers production TUIs at companies like Microsoft, NVIDIA, AWS, and MinIO.

This wiki documents the source under tea (the package at the repository root), plus the standalone examples/ and tutorials/ Go modules.

What Bubble Tea provides

• A small, opinionated runtime built around the Elm Model-View-Update loop (tea.go).
• A high-performance cell-based renderer with cursor-movement optimization (cursed_renderer.go).
• High-fidelity keyboard input with support for the Kitty keyboard protocol (key.go, keyboard.go).
• Mouse handling with click, release, motion and wheel events (mouse.go).
• Native clipboard (OSC 52) read/write (clipboard.go), bracketed paste, focus reporting, and a terminal progress bar (tea.go).
• Built-in color profile detection and downsampling via github.com/charmbracelet/colorprofile (color.go, profile.go).
• A subprocess Exec mechanism that releases the terminal so programs like $EDITOR can run inline (exec.go).
• Over 60 example programs in examples/ that double as integration smoke tests in CI.

Where to start

If you want to…	Read
Understand the runtime architecture	Architecture
Write your first program	Getting started
Look up a domain term	Glossary
Learn the Elm-style loop in depth	Program runtime
Migrate from v1 to v2	UPGRADE_GUIDE_V2.md
Browse runnable demos	Examples package

Repo at a glance

• Module path: charm.land/bubbletea/v2
• Go version: 1.25.0 (go.mod)
• License: MIT (LICENSE)
• Top-level Go files: 39 source files, ~5,584 lines (see By the numbers)
• Sub-modules: examples/ (66 demos), tutorials/ (basics + commands)
• Default branch: main
• Active version: v2.0.6 is the most recent tag

Status

Bubble Tea v2 is the current major release. The v1 → v2 migration replaced imperative startup options (tea.WithAltScreen()) and toggle commands (tea.EnterAltScreen) with declarative fields on tea.View. See the Lore page for a timeline.