Skip to content

carapace-sh/carapace-bin / skills/bubbletea

bubbletea

Verified

Use when working with Bubble Tea (charmbracelet/bubbletea) — the Elm Architecture TUI framework for Go. Covers the Model/Update/View cycle, commands, messages, the View struct, renderer, input handling, program lifecycle, testing, component composition, integration with the Charm ecosystem (lipgloss, bubbles, huh, glamour), and production design patterns. Triggers on: "bubbletea", "bubble tea", "tea.Model", "tea.Cmd", "tea.Msg", "tea.Program", "tea.View", "tea.KeyPressMsg", "tea.WindowSizeMsg", "tea.MouseMsg", "tea.Batch", "tea.Sequence", "tea.Quit", "Elm Architecture", "charmbracelet", "Bubble Tea v2", "tea.NewProgram", "tea.Send", "tea.Tick", "tea.Every", "cursedRenderer", "ultraviolet", "ScreenBuffer", "ProgramContext", "compositor".

FileKindSize
SKILL.mdskill md9.2 KB
references/commands.mdmarkdown7.7 KB
references/composition.mdmarkdown13.4 KB
references/input-signals.mdmarkdown10.4 KB
references/messages.mdmarkdown10.4 KB
references/model-view.mdmarkdown8.8 KB
references/patterns.mdmarkdown32.3 KB
references/program.mdmarkdown10.5 KB
references/renderer.mdmarkdown11.5 KB
references/testing.mdmarkdown7.1 KB
references/v1-v2-migration.mdmarkdown10.5 KB

references/composition.md

View on GitHub
# Component Composition and Charm Ecosystem

In-depth reference for composing Bubble Tea applications: embedding sub-models, focus management, layout patterns, building custom components, and integrating with the Charm ecosystem.

## Embedding Sub-Models

The standard pattern for composing multiple components in a single Bubble Tea model:

### 1. Embed as Value-Type Fields

```go
type MainModel struct {
    textInput textinput.Model
    viewport  viewport.Model
    spinner   spinner.Model
    list      list.Model
    table     table.Model
    help      help.Model
}
```

Components are **value types** (not pointers). This is important — you must reassign after `Update`.

### 2. Initialize with New() Constructors

```go
func initialModel() MainModel {
    m := MainModel{
        textInput: textinput.New(),
        viewport:  viewport.New(width, height),
        spinner:   spinner.New(),
        list:      list.New(items, delegate, width, height),
    }
    m.textInput.Placeholder = "Type here..."
    m.textInput.Focus()
    return m
}
```

### 3. Forward Update Calls

```go
func (m MainModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    var cmds []tea.Cmd

    // Handle parent-level messages first
    switch msg := msg.(type) {
    case tea.WindowSizeMsg:
        m.viewport.SetWidth(msg.Width)
        m.viewport.SetHeight(msg.Height - statusBarHeight)
    case tea.KeyPressMsg:
        switch msg.String() {
        case "tab":
            m.switchFocus()
        case "ctrl+c":
            return m, tea.Quit
        }
    }

    // Forward to focused sub-model
    var cmd tea.Cmd
    m.textInput, cmd = m.textInput.Update(msg)  // MUST reassign
    cmds = append(cmds, cmd)

    m.spinner, cmd = m.spinner.Update(msg)
    cmds = append(cmds, cmd)

    return m, tea.Batch(cmds...)
}
```

**Critical**: `m.textInput, cmd = m.textInput.Update(msg)` — the reassignment is required because components are value types. If you don't reassign, the update is lost.

### 4. Compose Views

```go
func (m MainModel) View() tea.View {
    content := lipgloss.JoinVertical(lipgloss.Left,
        m.headerView(),
        m.textInput.View(),
        m.viewport.View(),
        m.footerView(),
    )
    v := tea.NewView(content)
    v.AltScreen = true
    v.MouseMode = tea.MouseModeCellMotion
    return v
}
```

## Focus Management

For advanced focus/mode patterns (input controller with mode switching), see [patterns.md](patterns.md#input-controller-with-mode-switching).

### Focus/Blur Pattern

Most bubbles components implement `Focus()` and `Blur()`:

```go
// Focus returns a Cmd (typically for cursor blink initialization)
func (m *Model) Focus() tea.Cmd {
    m.focus = true
    return m.virtualCursor.Focus()
}

// Blur is void — no return Cmd
func (m *Model) Blur() {
    m.focus = false
    m.virtualCursor.Blur()
}
```

### Update Guard on Focus

Components skip processing when blurred:

```go
func (m Model) Update(msg tea.Msg) (Model, tea.Cmd) {
    if !m.focus {
        return m, nil  // textinput, textarea, table all do this
    }
    // ... process msg
}
```

### Focus Switching in Parent

```go
type focusState int

const (
    inputFocus focusState = iota
    viewportFocus
    listFocus
)

func (m *MainModel) switchFocus() tea.Cmd {
    var cmds []tea.Cmd

    // Blur current
    switch m.focus {
    case inputFocus:
        m.textInput.Blur()
    case listFocus:
        m.list.Blur()
    }

    // Advance to next
    m.focus = (m.focus + 1) % 3

    // Focus new
    switch m.focus {
    case inputFocus:
        cmds = append(cmds, m.textInput.Focus())
    case listFocus:
        cmds = append(cmds, m.list.Focus())
    }

    return tea.Batch(cmds...)
}
```

### Conditional Forwarding

Only forward messages to the focused component:

```go
func (m MainModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    var cmd tea.Cmd
    switch m.focus {
    case inputFocus:
        m.textInput, cmd = m.textInput.Update(msg)
    case viewportFocus:
        m.viewport, cmd = m.viewport.Update(msg)
    case listFocus:
        m.list, cmd = m.list.Update(msg)
    }
    return m, cmd
}
```

## Layout Patterns

For overlay positioning with compositor layers, see [patterns.md](patterns.md#compositor-layers-for-overlays).

### Vertical Stack (Most Common)

```go
func (m Model) View() tea.View {
    return tea.NewView(lipgloss.JoinVertical(lipgloss.Left,
        m.titleView(),
        m.contentView(),
        m.statusView(),
        m.helpView(),
    ))
}
```

### Horizontal Split

```go
func (m Model) View() tea.View {
    sidebar := lipgloss.NewStyle().Width(20).Render(m.sidebarView())
    main := lipgloss.NewStyle().Width(m.width - 20).Render(m.mainView())
    return tea.NewView(lipgloss.JoinHorizontal(lipgloss.Top, sidebar, main))
}
```

### Status Bar at Bottom

```go
const statusBarHeight = 1

func (m Model) View() tea.View {
    return tea.NewView(lipgloss.JoinVertical(lipgloss.Left,
        m.viewport.View(),
        m.statusBarView(),
    ))
}

// On WindowSizeMsg:
m.viewport.SetHeight(msg.Height - statusBarHeight)
```

### Fixed Header + Scrollable Body

```go
func (m Model) View() tea.View {
    header := m.headerView()  // fixed height
    body := m.viewport.View() // scrollable, fills remaining space
    return tea.NewView(header + "\n" + body)
}
```

### Bordered Panels

```go
var (
    borderStyle = lipgloss.NewStyle().
        Border(lipgloss.RoundedBorder()).
        BorderForeground(lipgloss.Color("63")).
        Padding(1, 2)
)

func (m Model) View() tea.View {
    left := borderStyle.Width(m.width/2 - 2).Render(m.leftView())
    right := borderStyle.Width(m.width/2 - 2).Render(m.rightView())
    return tea.NewView(lipgloss.JoinHorizontal(lipgloss.Top, left, right))
}
```

## Key Bindings

For production key binding patterns (structured KeyMap, user-configurable rebinding, view-conditional help), see [patterns.md](patterns.md#key-binding-patterns).

### key.Binding

```go
type Binding struct {
    keys     []string
    help     Help
    disabled bool
}
```

Create with functional options:

```go
var UpKey = key.NewBinding(
    key.WithKeys("k", "up"),
    key.WithHelp("↑/k", "move up"),
)

var QuitKey = key.NewBinding(
    key.WithKeys("q", "ctrl+c"),
    key.WithHelp("q", "quit"),
)
```

### KeyMap Struct

```go
type KeyMap struct {
    Up    key.Binding
    Down  key.Binding
    Enter key.Binding
    Quit  key.Binding
}

func DefaultKeyMap() KeyMap {
    return KeyMap{
        Up:    key.NewBinding(key.WithKeys("k", "up"), key.WithHelp("↑/k", "up")),
        Down:  key.NewBinding(key.WithKeys("j", "down"), key.WithHelp("↓/j", "down")),
        Enter: key.NewBinding(key.WithKeys("enter"), key.WithHelp("↵", "select")),
        Quit:  key.NewBinding(key.WithKeys("q", "ctrl+c"), key.WithHelp("q", "quit")),
    }
}
```

### Matching Keys

```go
func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.KeyPressMsg:
        switch {
        case key.Matches(msg, m.KeyMap.Up):
            m.cursorUp()
        case key.Matches(msg, m.KeyMap.Down):
            m.cursorDown()
        case key.Matches(msg, m.KeyMap.Enter):
            return m, m.selectItem()
        case key.Matches(msg, m.KeyMap.Quit):
            return m, tea.Quit
        }
    }
    return m, nil
}
```

### Dynamic Enable/Disable

```go
// Disable a binding
m.KeyMap.Quit.SetEnabled(false)

// Re-enable
m.KeyMap.Quit.SetEnabled(true)

// Check if enabled
if m.KeyMap.Quit.Enabled() { ... }
```

### Help Integration

For view-conditional help that changes based on the current view and sub-context, see [patterns.md](patterns.md#view-conditional-help).

Implement `help.KeyMap` interface:

```go
func (m Model) ShortHelp() []key.Binding {
    return []key.Binding{m.KeyMap.Up, m.KeyMap.Down, m.KeyMap.Enter}
}

func (m Model) FullHelp() [][]key.Binding {
    return [][]key.Binding{
        {m.KeyMap.Up, m.KeyMap.Down},
        {m.KeyMap.Enter, m.KeyMap.Quit},
    }
}
```

Render help:

```go
m.help.View(m.KeyMap)  // or m.help.View(m) if m implements help.KeyMap
```

## Building Custom Components

Follow the conventions used by all bubbles components:

```go
package mycomponent

import (
    tea "charm.land/bubbletea/v2"
    "charm.land/bubbles/v2/key"
    "charm.land/lipgloss/v2"
)

// 1. KeyMap
type KeyMap struct {
    Up    key.Binding
    Down  key.Binding
    Enter key.Binding
}

func DefaultKeyMap() KeyMap {
    return KeyMap{
        Up:    key.NewBinding(key.WithKeys("k", "up"), key.WithHelp("↑/k", "up")),
        Down:  key.NewBinding(key.WithKeys("j", "down"), key.WithHelp("↓/j", "down")),
        Enter: key.NewBinding(key.WithKeys("enter"), key.WithHelp("↵", "select")),
    }
}

// 2. Model (value type)
type Model struct {
    focus  bool
    KeyMap KeyMap
    Style  lipgloss.Style
    items  []string
    cursor int
    width  int
    height int
}

// 3. Constructor
func New() Model {
    return Model{
        KeyMap: DefaultKeyMap(),
        Style:  lipgloss.NewStyle(),
    }
}

// 4. Focus/Blur
func (m *Model) Focus() tea.Cmd {
    m.focus = true
    return nil
}

func (m *Model) Blur() {
    m.focus = false
}

// 5. Init
func (m Model) Init() tea.Cmd { return nil }

// 6. Update
func (m Model) Update(msg tea.Msg) (Model, tea.Cmd) {
    if !m.focus {
        return m, nil
    }

    switch msg := msg.(type) {
    case tea.KeyPressMsg:
        switch {
        case key.Matches(msg, m.KeyMap.Up):
            if m.cursor > 0 {
                m.cursor--
            }
        case key.Matches(msg, m.KeyMap.Down):
            if m.cursor < len(m.items)-1 {
                m.cursor++
            }
        case key.Matches(msg, m.KeyMap.Enter):
            return m, func() tea.Msg { return selectMsg{index: m.cursor} }
        }
    case tea.WindowSizeMsg:
        m.width = msg.Width
        m.height = msg.Height
    }
    return m, nil
}

// 7. View
func (m Model) View() string {
    var s strings.Builder
    for i, item := range m.items {
        if i == m.cursor {
            s.WriteString(m.Style.Bold(true).Render("> " + item))
        } else {
            s.WriteString("  " + item)
        }
        s.WriteString("\n")
    }
    return s.String()
}

// 8. Help integration
func (m Model) ShortHelp() []key.Binding {
    return []key.Binding{m.KeyMap.Up, m.KeyMap.Down, m.KeyMap.Enter}
}

func (m Model) FullHelp() [][]key.Binding {
    return [][]key.Binding{
        {m.KeyMap.Up, m.KeyMap.Down},
        {m.KeyMap.Enter},
    }
}
```

### Component Conventions

| Convention | Description |
|-----------|-------------|
| Value-type `Model` | Not a pointer — reassign after `Update` |
| `Focus()` returns `tea.Cmd` | For cursor blink initialization |
| `Blur()` is void | No return value |
| `Update` early-returns when blurred | Skip processing when not focused |
| `KeyMap` struct with `key.Binding` | Define all keybindings |
| `DefaultKeyMap()` constructor | Provide sensible defaults |
| `key.Matches(msg, binding)` | Key dispatch pattern |
| `SetEnabled(bool)` | Dynamic keybinding toggling |
| `lipgloss.Style.Render()` | All styled output |
| Component IDs | Disambiguate messages when multiple instances exist |

## Charm Ecosystem Integration

### Lipgloss (Styling/Layout)

```go
import "charm.land/lipgloss/v2"
```

- `lipgloss.NewStyle().Bold(true).Foreground(color).Render(text)` — styled text
- `lipgloss.JoinVertical(alignment, sections...)` — vertical layout
- `lipgloss.JoinHorizontal(alignment, sections...)` — horizontal layout
- `lipgloss.Width(s)` / `lipgloss.Height(s)` — measure rendered size
- `lipgloss.NewStyle().Width(w).Height(h)` — constrain dimensions

### Bubbles (Component Library)

```go
import "charm.land/bubbles/v2"
```

| Component | Import | Key Features |
|-----------|--------|-------------|
| textinput | `bubbles/textinput` | Single-line text input with placeholder, cursor, suggestions |
| textarea | `bubbles/textarea` | Multi-line text editor with line numbers |
| viewport | `bubbles/viewport` | Scrollable content area with keyboard/mouse scrolling |
| spinner | `bubbles/spinner` | Loading spinner with multiple styles |
| list | `bubbles/list` | Selectable/filterable item list with delegates |
| table | `bubbles/table` | Columnar data table with sorting |
| help | `bubbles/help` | Keybinding help display |
| paginator | `bubbles/paginator` | Page navigation |
| progress | `bubbles/progress` | Visual progress bar |
| cursor | `bubbles/cursor` | Cursor blink management |

### Glamour (Markdown Rendering)

```go
import "charm.land/glamour/v2"
```

Not a Bubble Tea model — renders markdown to ANSI string:

```go
r, _ := glamour.NewTermRenderer(glamour.WithWordWrap(80))
out, _ := r.Render(markdownContent)
m.viewport.SetContent(out)
```

### Huh (Form Library)

```go
import "charm.land/huh/v2"
```

Built on Bubble Tea. Can run standalone or embedded:

```go
// Standalone
form := huh.NewForm(
    huh.NewGroup(
        huh.NewInput().Title("Name"),
        huh.NewSelect().Options(huh.NewOptions("a", "b", "c")...),
    ),
)
err := form.Run()

// Embedded in Bubble Tea app
// huh.Field interface: Model + Focus/Blur + Error/Skip/Zoom + KeyBinds
```

### Harmonica (Spring Animations)

```go
import "github.com/charmbracelet/harmonica"
```

Spring physics for smooth animations:

```go
spring := harmonica.NewSpring(harmonica.Frequency(2.0), harmonica.Damping(0.5))
position, velocity := spring.Update(target, current, velocity)
```

### BubbleZone (Mouse Tracking)

```go
import "github.com/lrstanley/bubblezone"
```

Easy mouse event tracking for components:

```go
zone := bubblezone.New()
zone.Mark("button", styledButton)
// In Update: if zone.Get("button").InBounds(msg) { ... }
```
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall