Shell
Bubbletea Reference (Go)
The Elm Architecture for terminal UIs
Installation
go get github.com/charmbracelet/bubbletea
go get github.com/charmbracelet/lipgloss # Styling
go get github.com/charmbracelet/bubbles # Pre-built components
Core Concepts
The Elm Architecture (MVU)
Model → The application state
Update → Handle messages, return new state
View → Render state to string
Basic Structure
package main
import (
"fmt"
"os"
tea "github.com/charmbracelet/bubbletea"
)
// MODEL - Application state
type model struct {
cursor int
choices []string
selected map[int]struct{}
quitting bool
}
func initialModel() model {
return model{
choices: []string{"Buy milk", "Wash dishes", "Learn Bubbletea"},
selected: make(map[int]struct{}),
}
}
// INIT - Initial command (side effect)
func (m model) Init() tea.Cmd {
return nil // No initial command
}
// UPDATE - Handle messages
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
switch msg := msg.(type) {
case tea.KeyMsg:
switch msg.String() {
case "ctrl+c", "q":
m.quitting = true
return m, tea.Quit
case "up", "k":
if m.cursor > 0 {
m.cursor--
}
case "down", "j":
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
}
// VIEW - Render to string
func (m model) View() string {
if m.quitting {
return "Goodbye!\n"
}
s := "What needs to be done?\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)
}
s += "\nPress q to quit.\n"
return s
}
func main() {
p := tea.NewProgram(initialModel())
if _, err := p.Run(); err != nil {
fmt.Printf("Error: %v", err)
os.Exit(1)
}
}
Messages & Commands
Built-in Messages
// Key press
case tea.KeyMsg:
switch msg.String() {
case "ctrl+c": // Ctrl+C
case "enter": // Enter key
case "up": // Arrow up
case "a": // Letter a
}
// Window resize
case tea.WindowSizeMsg:
width := msg.Width
height := msg.Height
// Mouse events (if enabled)
case tea.MouseMsg:
x, y := msg.X, msg.Y
button := msg.Button
Custom Messages
// Define custom message types
type statusMsg string
type errMsg struct{ err error }
// Command that returns a message
func fetchStatus() tea.Msg {
// Simulate API call
time.Sleep(time.Second)
return statusMsg("Ready!")
}
// Use in Update
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
switch msg := msg.(type) {
case statusMsg:
m.status = string(msg)
case errMsg:
m.err = msg.err
}
return m, nil
}
// Trigger command from Init or Update
func (m model) Init() tea.Cmd {
return fetchStatus // Note: no parentheses!
}
Commands
// Return multiple commands
return m, tea.Batch(cmd1, cmd2, cmd3)
// Quit the program
return m, tea.Quit
// Do nothing
return m, nil
// Tick (for animations)
func tickCmd() tea.Cmd {
return tea.Tick(time.Second, func(t time.Time) tea.Msg {
return tickMsg(t)
})
}
Styling with Lipgloss
import "github.com/charmbracelet/lipgloss"
var (
// Colors
subtle = lipgloss.AdaptiveColor{Light: "#D9DCCF", Dark: "#383838"}
highlight = lipgloss.AdaptiveColor{Light: "#874BFD", Dark: "#7D56F4"}
special = lipgloss.AdaptiveColor{Light: "#43BF6D", Dark: "#73F59F"}
// Styles
titleStyle = lipgloss.NewStyle().
Bold(true).
Foreground(lipgloss.Color("#FAFAFA")).
Background(lipgloss.Color("#7D56F4")).
Padding(0, 1)
itemStyle = lipgloss.NewStyle().
PaddingLeft(2)
selectedStyle = lipgloss.NewStyle().
PaddingLeft(2).
Foreground(lipgloss.Color("#7D56F4")).
Bold(true)
boxStyle = lipgloss.NewStyle().
Border(lipgloss.RoundedBorder()).
BorderForeground(lipgloss.Color("#874BFD")).
Padding(1, 2)
)
func (m model) View() string {
title := titleStyle.Render("My App")
var items string
for i, item := range m.items {
if i == m.cursor {
items += selectedStyle.Render("> " + item) + "\n"
} else {
items += itemStyle.Render(" " + item) + "\n"
}
}
return boxStyle.Render(title + "\n\n" + items)
}
Bubbles Components
Spinner
import "github.com/charmbracelet/bubbles/spinner"
type model struct {
spinner spinner.Model
loading bool
}
func initialModel() model {
s := spinner.New()
s.Spinner = spinner.Dot
s.Style = lipgloss.NewStyle().Foreground(lipgloss.Color("205"))
return model{spinner: s, loading: true}
}
func (m model) Init() tea.Cmd {
return m.spinner.Tick
}
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
switch msg := msg.(type) {
case spinner.TickMsg:
var cmd tea.Cmd
m.spinner, cmd = m.spinner.Update(msg)
return m, cmd
}
return m, nil
}
func (m model) View() string {
if m.loading {
return m.spinner.View() + " Loading..."
}
return "Done!"
}
Text Input
import "github.com/charmbracelet/bubbles/textinput"
type model struct {
input textinput.Model
}
func initialModel() model {
ti := textinput.New()
ti.Placeholder = "Enter your name"
ti.Focus()
ti.CharLimit = 50
ti.Width = 30
return model{input: ti}
}
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
var cmd tea.Cmd
m.input, cmd = m.input.Update(msg)
switch msg := msg.(type) {
case tea.KeyMsg:
if msg.Type == tea.KeyEnter {
// Handle submission
value := m.input.Value()
}
}
return m, cmd
}
func (m model) View() string {
return fmt.Sprintf("Name:\n%s\n\nPress Enter to submit", m.input.View())
}
List
import "github.com/charmbracelet/bubbles/list"
type item struct {
title, desc string
}
func (i item) Title() string { return i.title }
func (i item) Description() string { return i.desc }
func (i item) FilterValue() string { return i.title }
type model struct {
list list.Model
}
func initialModel() model {
items := []list.Item{
item{title: "Raspberry Pi", desc: "A tiny computer"},
item{title: "Arduino", desc: "A microcontroller"},
}
l := list.New(items, list.NewDefaultDelegate(), 0, 0)
l.Title = "My Hardware"
return model{list: l}
}
Progress Bar
import "github.com/charmbracelet/bubbles/progress"
type model struct {
progress progress.Model
percent float64
}
func initialModel() model {
return model{
progress: progress.New(progress.WithDefaultGradient()),
}
}
func (m model) View() string {
return m.progress.ViewAs(m.percent)
}
Table
import "github.com/charmbracelet/bubbles/table"
columns := []table.Column{
{Title: "ID", Width: 4},
{Title: "Name", Width: 20},
{Title: "Status", Width: 10},
}
rows := []table.Row{
{"1", "Project Alpha", "Active"},
{"2", "Project Beta", "Pending"},
}
t := table.New(
table.WithColumns(columns),
table.WithRows(rows),
table.WithFocused(true),
table.WithHeight(7),
)
Advanced Patterns
Sub-models (Component Composition)
type model struct {
tabs []string
activeTab int
// Sub-models for each tab
homeModel homeModel
settingsModel settingsModel
}
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
var cmd tea.Cmd
// Route to active tab's model
switch m.activeTab {
case 0:
m.homeModel, cmd = m.homeModel.Update(msg)
case 1:
m.settingsModel, cmd = m.settingsModel.Update(msg)
}
return m, cmd
}
Full-screen vs Inline
// Full-screen (default)
p := tea.NewProgram(model{})
// Inline (within existing terminal output)
p := tea.NewProgram(model{}, tea.WithAltScreen())
// With mouse support
p := tea.NewProgram(model{}, tea.WithMouseCellMotion())
Async Operations
// HTTP request command
func fetchData(url string) tea.Cmd {
return func() tea.Msg {
resp, err := http.Get(url)
if err != nil {
return errMsg{err}
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
return dataMsg(body)
}
}
// Use in Update
case tea.KeyMsg:
if msg.String() == "f" {
return m, fetchData("https://api.example.com/data")
}
Testing
func TestUpdate(t *testing.T) {
m := initialModel()
// Simulate key press
m, _ = m.Update(tea.KeyMsg{Type: tea.KeyDown})
if m.cursor != 1 {
t.Errorf("expected cursor 1, got %d", m.cursor)
}
}
func TestView(t *testing.T) {
m := initialModel()
view := m.View()
if !strings.Contains(view, "What needs to be done?") {
t.Error("expected title in view")
}
}