tea package (library)

Active contributors: aymanbagabas, meowgorithm, muesli, caarlos0

The Bubble Tea library itself: a single Go package at the repository root with module path charm.land/bubbletea/v2. It is published on pkg.go.dev and used in tens of thousands of dependent repos.

Module declaration

go.mod declares Go 1.25.0 and 8 direct dependencies:

require (
    github.com/charmbracelet/colorprofile v0.4.3
    github.com/charmbracelet/ultraviolet v0.0.0-20260416155717-489999b90468
    github.com/charmbracelet/x/ansi v0.11.7
    github.com/charmbracelet/x/exp/golden v0.0.0-20241212170349-ad4b7ae0f25f
    github.com/charmbracelet/x/term v0.2.2
    github.com/lucasb-eyer/go-colorful v1.4.0
    github.com/muesli/cancelreader v0.2.2
    golang.org/x/sys v0.43.0
)

It also retracts the broken v2.0.0-beta1 tag (the canonical name has the dot — v2.0.0-beta.1).

Public API surface

The package exports the runtime, the model interface, every public message type, every View field, the cursor / progress bar / keyboard enhancement helpers, plus the command helpers (Quit, Tick, Every, Batch, Sequence, Println, Printf, Exec, ExecProcess, the terminal-query commands, …) and the program options (WithContext, WithInput, WithOutput, WithEnvironment, WithFilter, WithFPS, WithColorProfile, WithWindowSize, WithoutSignalHandler, WithoutCatchPanics, WithoutSignals, WithoutRenderer).

For exhaustive listings, see the Reference / messages and Reference / program options pages, or read the GoDoc for the package.

Source layout

File	Lines	Topic
tea.go	1,439	Runtime, public types, panic recovery
cursed_renderer.go	854	Default renderer
key.go	371	Key model
commands.go	175	Command helpers
options.go	168	Program options
mouse.go	144	Mouse model
tty.go (+ unix/windows variants)	136+	Input + raw mode
exec.go	129	Subprocess support
renderer.go	104	Renderer interface
color.go	91	Color queries
screen.go	68	Screen-level messages
nil_renderer.go	53	Headless renderer
clipboard.go	70	OSC 52
keyboard.go	59	Kitty enhancements
Other small files	small	One concept each (focus, paste, raw, termcap, xterm, mod, environ, etc.)

Backwards compatibility

The v2 major version drew a hard line. The v1 module path (github.com/charmbracelet/bubbletea) is no longer maintained — see UPGRADE_GUIDE_V2.md. Within v2 the team treats the public API as stable but reserves the right to add new fields and message types as new ANSI features come along.

Related pages

• Examples — runnable demos.
• Tutorials — annotated grocery-list tutorial.
• Architecture — how the package fits together.