Bubble Tea — Powerful TUI Framework for Go

What it is

Bubble Tea is a terminal user interface (TUI) framework for Go, built on the Elm Architecture pattern. You define a model (state), an update function (handles messages), and a view function (renders the UI). The framework handles the event loop, terminal rendering, and input management.

Bubble Tea is part of the Charm ecosystem, which includes Lip Gloss (styling), Bubbles (pre-built components), Gum (shell scripting), and Wish (SSH apps). It powers tools like lazygit, soft-serve, and many CLI applications.

How it saves time or tokens

Bubble Tea provides a structured architecture for TUI development. Without it, building interactive terminal apps involves raw ANSI escape codes, manual input handling, and custom rendering loops. Bubble Tea abstracts these concerns into a clean Model-Update-View cycle.

The Bubbles component library provides pre-built widgets (text inputs, spinners, lists, tables, file pickers) that you compose into complex UIs without writing rendering logic from scratch.

How to use

1. Add Bubble Tea to your Go project:

go get github.com/charmbracelet/bubbletea

1. Define a model, update, and view:

package main

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

type model struct {
    choices  []string
    cursor   int
    selected map[int]struct{}
}

func (m model) Init() tea.Cmd { return nil }

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.KeyMsg:
        switch msg.String() {
        case "q":
            return m, tea.Quit
        case "up":
            if m.cursor > 0 { m.cursor-- }
        case "down":
            if m.cursor < len(m.choices)-1 { m.cursor++ }
        case "enter":
            if _, ok := m.selected[m.cursor]; ok {
                delete(m.selected, m.cursor)
            } else {
                m.selected[m.cursor] = struct{}{}
            }
        }
    }
    return m, nil
}

func (m model) View() string {
    s := "Pick items:\n\n"
    for i, choice := range m.choices {
        cursor := " "
        if m.cursor == i { cursor = ">" }
        checked := " "
        if _, ok := m.selected[i]; ok { checked = "x" }
        s += fmt.Sprintf("%s [%s] %s\n", cursor, checked, choice)
    }
    return s + "\nPress q to quit.\n"
}

1. Run the program:

func main() {
    p := tea.NewProgram(model{
        choices: []string{"Option A", "Option B", "Option C"},
        selected: make(map[int]struct{}),
    })
    p.Run()
}

Example

Using Lip Gloss for styled output:

import "github.com/charmbracelet/lipgloss"

var style = lipgloss.NewStyle().
    Bold(true).
    Foreground(lipgloss.Color("205")).
    Border(lipgloss.RoundedBorder())

func (m model) View() string {
    return style.Render("Styled TUI content")
}

Related on TokRepo

• AI tools for coding -- Development frameworks and libraries
• Automation tools -- CLI and terminal tools

Common pitfalls

• Mutating the model directly instead of returning a new model from Update. The Elm Architecture expects immutable updates. Always return a new or modified model from the Update function.
• Blocking in the Update function. Long-running operations should be dispatched as Cmds (async functions). Blocking the Update function freezes the UI.
• Not using the Bubbles component library. Before building custom widgets, check if Bubbles already has what you need (text input, spinner, progress bar, viewport, table).