Charm Bracelet Tui

Charm Bracelet TUI Stack

The Charm Bracelet ecosystem is a collection of Go libraries for building beautiful terminal UIs. They are designed to work together but can also be used independently.

Current versions: All core Charm libs are on v2 as of early 2026 (import paths use charm.land/<lib>/v2).

The Stack at a Glance

┌─────────────────────────────────────────────────────────────┐
│                   Your TUI Application                       │
├──────────────────────────┬──────────────────────────────────┤
│   huh (forms/prompts)    │   Bubbles (pre-built components)  │
├──────────────────────────┴──────────────────────────────────┤
│                BubbleTea (MVU framework)                     │
├──────────────────┬──────────────┬───────────────────────────┤
│  Lip Gloss       │   Glamour    │   Harmonica               │
│  (styling)       │  (markdown)  │   (animation)             │
├──────────────────┴──────────────┴───────────────────────────┤
│           BubbleZone (mouse tracking) │ ntcharts (charts)    │
└─────────────────────────────────────────────────────────────┘

Library Roles

Quick Reference: Which Library for What?

• Need a TUI framework? → BubbleTea (always the foundation)
• Need forms / user input collection? → Huh (or Bubbles textinput/textarea)
• Need styled output / layouts? → Lip Gloss
• Need to render Markdown? → Glamour
• Need pre-built components? → Bubbles (spinner, progress, list, table, viewport, filepicker...)
• Need smooth animations? → Harmonica
• Need mouse click detection per-component? → BubbleZone
• Need charts / graphs? → ntcharts

How They Work Together

BubbleTea + Lip Gloss (the core combo)

BubbleTea handles the update loop; Lip Gloss handles the rendering. Your View() method returns a tea.View built by rendering Lip Gloss styles:

func (m model) View() tea.View {
    title := lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("#FF75B7")).Render("My App")
    body := lipgloss.NewStyle().Padding(1, 2).Render("Hello world")
    return tea.NewView(lipgloss.JoinVertical(lipgloss.Left, title, body))
}

BubbleTea + Huh (embedded forms)

huh.Form is a tea.Model, so embed it directly:

type Model struct {
    form *huh.Form
}
func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    form, cmd := m.form.Update(msg)
    if f, ok := form.(*huh.Form); ok { m.form = f }
    return m, cmd
}
func (m Model) View() string { return m.form.View() }

BubbleTea + BubbleZone (mouse support)

Wrap your root View() in zone.Scan(), mark individual areas with zone.Mark(id, content), check zone.Get(id).InBounds(mouseMsg) in Update().

BubbleTea + ntcharts (charts)

ntcharts components are standalone (they have their own Draw()/View() methods), so embed them in your model and call them during Update() and View().

Getting Started

# Core framework
go get charm.land/bubbletea/v2

# Styling
go get charm.land/lipgloss/v2

# Pre-built components
go get github.com/charmbracelet/bubbles

# Forms
go get charm.land/huh/v2

# Markdown
go get github.com/charmbracelet/glamour

# Animations
go get github.com/charmbracelet/harmonica

# Mouse tracking
go get github.com/lrstanley/bubblezone/v2

# Charts
go get github.com/NimbleMarkets/ntcharts

Minimal BubbleTea App (v2 API)

package main

import (
    "fmt"
    "os"
    tea "charm.land/bubbletea/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 "q", "ctrl+c": return m, tea.Quit
        case "up": m.count++
        case "down": m.count--
        }
    }
    return m, nil
}

func (m model) View() tea.View {
    return tea.NewView(fmt.Sprintf("Count: %d\n\nPress q to quit.", m.count))
}

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

Reference Files

Read the relevant reference file(s) for deep implementation details:

• references/bubbletea.md — BubbleTea framework: MVU lifecycle, commands, messages, v2 View API
• references/lipgloss.md — Lip Gloss: styles, colors, layouts, tables, trees, lists, compositing
• references/bubbles.md — Bubbles components: spinner, textinput, textarea, list, table, viewport, progress, filepicker, timer, help
• references/glamour.md — Glamour: markdown rendering, themes, custom styles
• references/huh.md — Huh: forms, fields, dynamic forms, BubbleTea integration, spinner
• references/harmonica.md — Harmonica: spring animations, damping ratios, BubbleTea integration
• references/bubblezone.md — BubbleZone: mouse zones, InBounds, global vs local manager
• references/ntcharts.md — ntcharts: canvas, bar, line, sparkline, heatmap, OHLC, time series, waveline

When to Read Which

Common Gotchas

• v2 import paths: Core Charm libs moved to charm.land/<lib>/v2 in 2025-2026. github.com/charmbracelet/* paths still work for some (glamour, harmonica), but prefer charm.land for bubbletea, lipgloss, huh.
• BubbleTea v2 View: View() now returns tea.View (not string). Use tea.NewView(str) to wrap string content.
• AltScreen for BubbleZone: BubbleZone requires alt-screen mode — set view.AltScreen = true in your root view.
• Dynamic hex colors in Lip Gloss: Use lipgloss.Color("#RRGGBB") — Lip Gloss will automatically downsample for lower-color terminals.
• Lip Gloss Width vs len(): Always use lipgloss.Width(str) instead of len() — ANSI codes inflate len().
• BubbleZone zone.Scan() at root only: Only wrap your root model's view output with zone.Scan().
• ntcharts: Call .Draw() before .View() to rasterize the chart each frame.