Bubbles

Bubbles is a collection of common terminal UI components built for Bubble Tea, the Elm-architecture TUI framework from Charm. Instead of hand-rolling spinners, paginated lists, text inputs, file pickers, or scrollable viewports for every new command-line tool, developers import the pieces they need and wire them into their own Bubble Tea Model.

Each component—spinner, textinput, textarea, table, progress, paginator, viewport, list, filepicker, timer, stopwatch, help, key, cursor, and tree—is a self-contained Bubble Tea model with its own Init, Update, and View methods, so they compose the same way a hand-written Bubble Tea program would. The components ship in production inside Charm’s own tools (like Crush) and a wide range of community CLIs, making Bubbles the de facto standard component kit for Go terminal applications.

What You Get

• A spinner component with several built-in animation styles (Line, Dot, MiniDot, Jump, Pulse, Points, Globe, Moon, Monkey) plus support for custom frame sequences
• Text input and text area components with unicode support, paste handling, in-place horizontal/vertical scrolling, and extensive styling hooks
• A batteries-included list component with pagination, fuzzy filtering, an activity spinner, and auto-generated status/help text
• A table component for rendering and navigating columnar data with vertical scrolling
• A progress bar with optional physics-based animation (via Harmonica) and solid or gradient fills
• Paginator, viewport, file picker, timer, stopwatch, help, and tree components covering the remaining common TUI patterns
• A dedicated key package for declaring user-remappable keybindings that also auto-generate their own help text

Common Use Cases

• Building developer CLI tools that need a polished interactive experience (progress indicators, selection lists, forms) instead of raw stdin prompts
• Assembling admin or ops dashboards that run entirely in the terminal, using the table and viewport components to browse data
• Adding an interactive file or directory picker to a CLI without writing custom filesystem-navigation UI
• Implementing consistent, remappable keyboard shortcuts across a multi-screen terminal application via the key and help packages

Under The Hood

Architecture

Bubbles is organized as one independent Go package per component (spinner, list, table, textinput, and so on), each implementing the same Elm-style contract Bubble Tea expects: a Model struct plus Init, Update(tea.Msg), and View() methods, so any component drops straight into a parent program’s Update/View without adapters. There is no central registry, dependency injection, or shared mutable state; composition happens by embedding component models as fields on the consumer’s own model and forwarding messages explicitly. A shared key package standardizes keybinding declaration and matching across every component, and the list and help packages depend on lower-level components (paginator, spinner, textinput) directly, showing a clear internal layering from primitives up to composite widgets.

Tech Stack

The module targets Go 1.25 and builds on the charm.land/bubbletea/v2 runtime and charm.land/lipgloss/v2 for styling, both from the same Charm ecosystem. Terminal-specific concerns are handled by small, focused dependencies: github.com/charmbracelet/harmonica for physics-based progress animation, github.com/mattn/go-runewidth and github.com/rivo/uniseg for unicode-aware width and grapheme handling, github.com/sahilm/fuzzy for the list’s fuzzy filtering, and github.com/atotto/clipboard for paste support in text inputs. Releases are cut with GoReleaser and a Taskfile drives local build/lint/test tasks.

Code Quality

The repository has test files alongside roughly half its component packages (spinner, list, key, and others), written as external _test packages that exercise the public API rather than internals—a black-box style that keeps tests honest about what consumers actually see. .golangci.yml configures a strict linter, and GitHub Actions workflows run build, lint, and coverage checks on every push, giving the project consistent CI gating even without exhaustive test coverage across every component.

API Design Every component follows the identical New() / Update(msg) / View() shape, so learning one component (spinner) transfers directly to the next (list, table, textinput)—this consistency is Bubbles’ main developer-experience win over rolling custom terminal widgets. The key package turns keybinding declarations into both matching logic and auto-generated help text in one definition, removing a whole class of boilerplate and drift between what a shortcut does and what the help view says it does. Godoc comments are thorough at the package level, though runnable examples live in the separate bubbletea repository rather than inline, so newcomers need to cross-reference both repos to get started.