charm-tui

Charm TUI stack for Go

Build terminal UIs and interactive CLIs in Go with Charm libraries. All Charm libraries below are on v2 and use the charm.land/<lib>/v2 module path (v1 was github.com/charmbracelet/<lib>). BubbleZone and Harmonica keep their github.com paths.

Mental model: The Elm Architecture

Bubble Tea is the runtime; everything else plugs into it. A program is one tea.Model:

• Init() tea.Cmd — kick off startup work (timers, IO). Return nil for none.
• Update(tea.Msg) (tea.Model, tea.Cmd) — the only place state changes. A Msg arrives (keypress, tick, window resize, custom event), you return a new model and optionally a Cmd.
• View() tea.View — pure render of current state to a tea.View (v2 returns tea.View, not string). Never mutate state here.

Cmd = func() tea.Msg: run side effects off the render loop; their result comes back as a Msg to Update. This unidirectional loop (Msg → Update → View) is the whole framework.

Library map — pick by need

Need	Library	Reference
Event loop, program lifecycle, key/mouse/tick messages	Bubble Tea	references/bubbletea.md
Colors, borders, padding, alignment, tables/lists/trees	Lip Gloss	references/lipgloss.md
Ready-made widgets (input, list, table, viewport, spinner, progress)	Bubbles	references/bubbles.md
Render Markdown to styled ANSI	Glamour	references/glamour.md
Spring/physics-based motion for smooth animation	Harmonica	references/harmonica.md
Mouse hit-testing / clickable regions	BubbleZone	references/bubblezone.md
Composite recipes: scroll+mouse, tabs, clickable tabs, split panes	(assembled)	references/patterns.md
One palette across every widget (light/dark source of truth)	(shared)	references/theming.md

Install

go get charm.land/bubbletea/v2 charm.land/lipgloss/v2 charm.land/bubbles/v2 charm.land/glamour/v2
go get github.com/charmbracelet/harmonica github.com/lrstanley/bubblezone/v2

Minimal complete program

package main

import (
	"fmt"
	"os"

	tea "charm.land/bubbletea/v2"
	"charm.land/lipgloss/v2"
)

type model struct{ count int }

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.KeyPressMsg:
		switch msg.String() {
		case "ctrl+c", "q":
			return m, tea.Quit
		case "up", "k":
			m.count++
		case "down", "j":
			m.count--
		}
	}
	return m, nil
}

func (m model) View() tea.View {
	style := lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("205"))
	v := tea.NewView(fmt.Sprintf("Count: %s\n\n↑/↓ to change · q to quit\n",
		style.Render(fmt.Sprintf("%d", m.count))))
	v.AltScreen = true // full-screen mode; omit for inline
	return v
}

func main() {
	if _, err := tea.NewProgram(model{}).Run(); err != nil {
		fmt.Println(err)
		os.Exit(1)
	}
}

Composing components (the key pattern)

Bubbles are themselves Update/View types. Embed them in your model, forward Msgs in Update, and stitch their View() output with Lip Gloss:

type model struct {
	input textinput.Model
	list  list.Model
}

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
	var cmds []tea.Cmd
	var cmd tea.Cmd
	m.input, cmd = m.input.Update(msg) // forward to each child
	cmds = append(cmds, cmd)
	m.list, cmd = m.list.Update(msg)
	cmds = append(cmds, cmd)
	return m, tea.Batch(cmds...) // batch child commands
}

func (m model) View() tea.View {
	return tea.NewView(lipgloss.JoinVertical(lipgloss.Left, m.input.View(), m.list.View()))
}

Rules that prevent most bugs

• Never do IO in Update/View directly. Wrap it in a Cmd so the loop stays responsive.
• View() is pure — read state, return a view, mutate nothing.
• Handle tea.WindowSizeMsg to size viewports/lists; components need explicit sizes.
• A Cmd returning nil is a no-op. Combine several with tea.Batch; sequence with tea.Sequence.
• Enable mouse per-view via v.MouseMode = tea.MouseModeCellMotion (see BubbleZone ref).
• Use lipgloss.Println/Sprint (not fmt) when printing styled text so colors downsample to the terminal's capabilities.

See each reference file for full APIs and worked examples.