1. What Is Bubble Tea and Why Use It?

Bubble Tea is a powerful, elegant, and productive framework for building terminal user interfaces (TUIs) in Go. Inspired by the Elm architecture from functional programming, it offers a simple yet incredibly flexible model based on three core concepts: Model (state), Update (update function), and View (display function).

Why use Bubble Tea? If you're tired of boring, single-line CLI utilities and want to create interactive, beautiful, and responsive applications right in the terminal — this is your tool. Bubble Tea lets you build everything from simple input forms and selection lists to complex file managers, music players, games, and monitoring dashboards. It handles all the low-level terminal work (signal processing, cursor management, rendering), letting you focus on your application logic.

The library is part of the Charm ecosystem, which also includes other useful tools like Bubbles (a set of ready-made components such as text inputs, spinners, progress bars) and Lip Gloss (a styling library for output). Together, they form a complete toolkit for building professional TUI applications.

2. Installation

Install the library using the standard Go method:

go get github.com/charmbracelet/bubbletea@latest

To use ready-made components (widgets), also install the bubbles package:

go get github.com/charmbracelet/bubbles@latest

And for styling:

go get github.com/charmbracelet/lipgloss@latest

3. Quick Start — Minimal Working Example

Create a file called main.go and paste the following code. This app will count your key presses. Press Ctrl+C to exit.

package main

import (
    "fmt"
    "os"
    tea "github.com/charmbracelet/bubbletea"
)

// 1. Model — stores the application state.
type model struct {
    count int
}

// 2. Init — returns the initial command (usually nil).
func (m model) Init() tea.Cmd {
    return nil
}

// 3. Update — handles incoming messages and returns a new model and command.
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.KeyMsg:
        switch msg.String() {
        case "ctrl+c":
            return m, tea.Quit // Command to exit
        default:
            m.count++
            return m, nil
        }
    }
    return m, nil
}

// 4. View — returns a string that will be displayed in the terminal.
func (m model) View() string {
    return fmt.Sprintf("Key presses: %d\n\nPress any key. Press Ctrl+C to exit.", m.count)
}

func main() {
    p := tea.NewProgram(model{})
    if _, err := p.Run(); err != nil {
        fmt.Printf("Error: %v", err)
        os.Exit(1)
    }
}

Run the application:

go run main.go

4. Core Methods and Types

In Bubble Tea, the key elements are interfaces and functions, not classes. Let's look at 8 essential components.