Bubbles — TUI Components for Bubble Tea in Go

Introduction

Bubbles is the official component library for Bubble Tea, the Go framework for building terminal user interfaces. It provides ready-to-use widgets that follow the Elm architecture, allowing developers to compose rich TUIs without building every element from scratch.

What Bubbles Does

• Provides text input fields with placeholder text, cursor control, and validation
• Includes spinner animations with multiple built-in styles
• Offers list and table components with filtering, pagination, and selection
• Supports viewport scrolling for content that exceeds the terminal height
• Delivers progress bars, file pickers, timers, and stopwatch components

Architecture Overview

Bubbles follows the Elm architecture used by Bubble Tea: each component implements the Model interface with Init, Update, and View methods. Components receive messages (keyboard input, window resize, ticks) and return updated state plus optional commands. They compose naturally by embedding one Bubble Tea model inside another.

Self-Hosting & Configuration

• Add to your Go project: go get github.com/charmbracelet/bubbles
• Requires Bubble Tea (bubbletea) as a peer dependency
• Components are imported individually from subpackages (e.g., bubbles/textinput)
• Styling is handled via Lip Gloss, the Charm terminal styling library
• No configuration files; all customization is done through Go code

Key Features

• Over 15 pre-built components covering common TUI patterns
• Composable architecture where components nest inside each other
• Built-in keyboard navigation and accessibility patterns
• Customizable styling via Lip Gloss integration
• Active maintenance by the Charm team with regular updates

Comparison with Similar Tools

• tview (Go) — widget-based TUI library; Bubbles follows the Elm architecture for better state management
• Ratatui (Rust) — Rust TUI ecosystem; Bubbles is the Go equivalent with a similar component approach
• FTXUI (C++) — C++ functional TUI; Bubbles targets Go developers with idiomatic patterns
• Textual (Python) — Python TUI framework; Bubbles is compiled Go with lower overhead
• Gum — Charm's shell-script TUI tool; Bubbles is the Go library for building custom applications

FAQ

Q: Can I use Bubbles without Bubble Tea? A: No. Bubbles components implement the Bubble Tea Model interface and depend on its runtime.

Q: How do I style components? A: Use Lip Gloss to define styles and apply them to component rendering in the View method.

Q: Can I create custom components? A: Yes. Implement the Bubble Tea Model interface and follow the same Init/Update/View pattern.

Q: Does it support mouse input? A: Some components like the list and viewport handle mouse scroll events when enabled in Bubble Tea.

Sources

• https://github.com/charmbracelet/bubbles
• https://charm.sh/