How to handle mouse events in Bubble Tea?

Use the BubbleZone library for easier mouse event tracking. Bubble Tea supports mouse input natively, but BubbleZone simplifies component-level handling, as mentioned in the libraries section.

Bubble Tea or Cobra for building CLI apps?

Bubble Tea is for interactive terminal UIs with stateful interfaces like dashboards, while Cobra focuses on command parsing. Choose Bubble Tea when you need rich, interactive elements beyond simple commands.

How to add animations to a Bubble Tea app?

Integrate the Harmonica library for spring animations. It's designed for smooth motion in terminal apps and works seamlessly with Bubble Tea's update cycle, as listed in the companion libraries.

Can I use Bubble Tea for text-based games?

Yes, it's well-suited for games like Tetrigo. The high-performance renderer and input handling support real-time updates, but for complex graphics, you might need custom rendering or additional libraries.

What's the best way to test Bubble Tea applications?

Unit test the Init, Update, and View methods in isolation since they are pure functions. This approach avoids the complexity of full TUI execution and is recommended in community practices.

How to upgrade from Bubble Tea v1 to v2?

Follow the upgrade guide provided in the README, which details breaking changes. The framework team recommends using this guide or pointing an LLM at it for automated assistance.

Open-Awesome

bubbletea

MITGov2.0.6

A fun, functional, and stateful Go framework for building terminal user interfaces (TUIs) based on The Elm Architecture.

GitHub

41.8k stars1.2k forks0 contributors

What is bubbletea?

Bubble Tea is a Go framework for building terminal user interfaces (TUIs) using The Elm Architecture. It provides a declarative, stateful way to create interactive command-line applications, from simple tools to full-window interfaces. The framework handles rendering, input events, and component lifecycle, allowing developers to focus on application logic.

Target Audience

Go developers building interactive command-line tools, system administrators creating custom terminal dashboards, and anyone needing to build rich text-based interfaces beyond basic CLI output.

Value Proposition

Developers choose Bubble Tea for its elegant functional design, production-ready performance optimizations, and comprehensive feature set including mouse support, clipboard integration, and a vibrant ecosystem of companion libraries like Bubbles for UI components.

Overview

A powerful little TUI framework 🏗

Use Cases

Best For

Building interactive CLI tools with complex user interfaces
Creating terminal dashboards for system monitoring
Developing text-based games or educational applications
Building custom DevOps or deployment tools with rich feedback
Porting web app patterns to command-line interfaces
Adding interactive configuration wizards to existing Go applications

Not Ideal For

Projects requiring graphical user interfaces or multimedia support beyond terminal capabilities
Simple command-line scripts that only need basic argument parsing and static output
Teams preferring imperative UI programming styles over declarative state management

Pros & Cons

Pros

Functional State Management

Adopts The Elm Architecture with Init, Update, and View methods, ensuring predictable and testable UI behavior, as demonstrated in the tutorial's shopping list example.

High-Performance Rendering

Includes a cell-based renderer with built-in color downsampling, optimized for efficient terminal output and used in production apps like Glow and Chezmoi.

Rich Input Handling

Supports keyboard, mouse, and native clipboard events, enabling complex interactivity without external dependencies, as highlighted in the features list.

Declarative View System

Allows UI description without manual redrawing logic, simplifying updates and reducing bugs, evident in the View method that builds content based on model state.

Cons

Debugging Complexity

Requires running delve in headless mode due to stdin/stdout control, making iterative debugging more cumbersome than standard Go programs, as admitted in the debugging section.

Terminal-Only Restriction

Confined to text-based interfaces, so it cannot handle graphical elements or web apps, limiting use cases for projects needing visual richness.

Ecosystem Dependency

While Bubbles provides common components, the ecosystem is still maturing, and advanced features like charts require additional libraries like ntcharts, increasing setup complexity.

Frequently Asked Questions

Related Projects

Terminal JSON viewer & processor

Stars20,434

Forks478

Last commit27 days ago

termui

Golang terminal dashboard

Stars13,542

Forks816

Last commit9 months ago

lipgloss

Style definitions for nice terminal layouts 👄

Stars11,105

Forks334

Last commit2 days ago

gocui

Minimalist Go package aimed at creating Console User Interfaces.

Stars10,554

Forks641

Last commit11 months ago

Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a project Star on GitHub