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/model-view.md

View on GitHub
# Model, Update, and View — The Elm Architecture in Go

In-depth reference for Bubble Tea's core architecture: the `Model` interface, the `Update`/`View` cycle, the declarative `View` struct, and how views are composed and diffed.

## The Model Interface

Every Bubble Tea program implements a single interface:

```go
type Model interface {
    Init() Cmd
    Update(Msg) (Model, Cmd)
    View() View
}
```

- **`Init()`** — Called once when the program starts. Returns an initial `Cmd` (or `nil` for no-op). Use it to kick off async work (HTTP requests, timers, etc.).
- **`Update(msg)`** — Called for every message. Receives the current model and a message, returns a new model and an optional `Cmd`. This is a **pure state transition** — no side effects except via returned commands.
- **`View()`** — Called after every `Update`. Returns a `View` struct that declaratively describes what the terminal should look like. **Must be side-effect-free** — no I/O, no mutations.

### The Cycle

```
Init() → Cmd → Msg → Update(Msg) → (Model, Cmd) → View() → render
                ↑                                              |
                └──────────── Cmd() → Msg ────────────────────┘
```

1. `Init()` returns a `Cmd`
2. The `Cmd` executes asynchronously and produces a `Msg`
3. `Update(Msg)` processes the message, returns new `Model` + optional `Cmd`
4. `View()` renders the model into a `View` struct
5. The renderer diffs the new `View` against the previous one and emits ANSI updates
6. Any returned `Cmd` executes and the cycle repeats

## The View Struct (v2)

The `View` struct is the central declarative type in v2. It replaces v1's approach of using commands and program options to control terminal state.

```go
type View struct {
    Content                   string
    AltScreen                 bool
    ReportFocus               bool
    DisableBracketedPasteMode bool
    MouseMode                 MouseMode
    KeyboardEnhancements      KeyboardEnhancements
    OnMouse                   func(MouseMsg) Cmd
    Cursor                    *Cursor
    BackgroundColor           color.Color
    ForegroundColor           color.Color
    WindowTitle               string
    ProgressBar               *ProgressBar
}
```

### Constructor

```go
func NewView(s string) View {
    var view View
    view.SetContent(s)
    return view
}
```

### Content

`Content` is a `string` containing ANSI-styled text (typically produced by lipgloss). The renderer parses it into a cell buffer for diffing against the previous frame.

```go
func (m model) View() tea.View {
    v := tea.NewView(lipgloss.NewStyle().Bold(true).Render("Hello"))
    return v
}
```

### AltScreen

Set `AltScreen = true` to enter the alternate screen buffer. The renderer automatically enters on `true` and exits on `false` (or when the program quits).

```go
v.AltScreen = true
```

In v1, this was `tea.EnterAltScreen` / `tea.ExitAltScreen` commands or `tea.WithAltScreen()` program option.

### Cursor

The `Cursor` field controls cursor visibility, position, shape, and color. When `nil`, the cursor is hidden.

```go
type Cursor struct {
    Position
    Color color.Color
    Shape CursorShape
    Blink bool
}

type Position struct{ X, Y int }
```

**CursorShape constants:**

| Constant | Shape |
|----------|-------|
| `CursorBlock` | Block cursor (default) |
| `CursorUnderline` | Underline cursor |
| `CursorBar` | Vertical bar cursor |

**Usage:**

```go
// Show blinking block cursor at (5, 3)
v.Cursor = tea.NewCursor(5, 3)

// Show non-blinking underline cursor
v.Cursor = &tea.Cursor{
    Position: tea.Position{X: 5, Y: 3},
    Shape:    tea.CursorUnderline,
    Blink:    false,
}

// Hide cursor
v.Cursor = nil
```

In v1, cursor was implicit from string position, and `tea.HideCursor`/`tea.ShowCursor` were commands.

### MouseMode

Controls what mouse events the terminal reports:

| Constant | Events |
|----------|--------|
| `MouseModeNone` | No mouse events |
| `MouseModeCellMotion` | Click, release, wheel, drag (button held) |
| `MouseModeAllMotion` | All events including motion with no button |

```go
v.MouseMode = tea.MouseModeCellMotion
```

In v1, this was `tea.EnableMouseCellMotion` / `tea.EnableMouseAllMotion` commands or `tea.WithMouseCellMotion()` program option.

### KeyboardEnhancements

Requests advanced keyboard features from the terminal (Kitty keyboard protocol + modifyOtherKeys2):

```go
type KeyboardEnhancements struct {
    ReportEventTypes           bool  // key repeat + release events
    ReportAlternateKeys        bool  // alternate key values
    ReportAllKeysAsEscapeCodes bool  // all keys as escape codes
    ReportAssociatedText       bool  // text associated with key events
}
```

When `ReportEventTypes` is enabled, you receive `KeyReleaseMsg` and `KeyPressMsg` with `IsRepeat` field set.

```go
v.KeyboardEnhancements = tea.KeyboardEnhancements{
    ReportEventTypes:    true,
    ReportAlternateKeys: true,
}
```

### OnMouse

A callback that intercepts mouse events before they reach `Update`. Return a `Cmd` to produce a message, or `nil` for no-op.

```go
v.OnMouse = func(msg tea.MouseMsg) tea.Cmd {
    m := msg.Mouse()
    if m.Y == 0 && m.Button == tea.MouseLeft {
        return func() tea.Msg { return headerClickMsg{x: m.X} }
    }
    return nil
}
```

### ReportFocus

When `true`, the program receives `FocusMsg` and `BlurMsg` when the terminal gains or loses focus.

```go
v.ReportFocus = true
```

### WindowTitle

Sets the terminal window/tab title:

```go
v.WindowTitle = "My App"
```

### BackgroundColor / ForegroundColor

Set terminal default colors:

```go
v.BackgroundColor = color.RGBA{R: 30, G: 30, B: 46, A: 255}
v.ForegroundColor = color.RGBA{R: 205, G: 214, B: 244, A: 255}
```

### ProgressBar

Controls the terminal's native progress bar (supported terminals only):

```go
type ProgressBar struct {
    State ProgressBarState
    Value int  // 0-100
}
```

**ProgressBarState constants:**

| Constant | Meaning |
|----------|---------|
| `ProgressBarNone` | No progress bar |
| `ProgressBarDefault` | Normal progress |
| `ProgressBarError` | Error state |
| `ProgressBarIndeterminate` | Indeterminate/spinning |
| `ProgressBarWarning` | Warning state |

```go
v.ProgressBar = tea.NewProgressBar(tea.ProgressBarDefault, 75)
```

Bracketed paste is enabled by default. Set to `true` to disable:

```go
v.DisableBracketedPasteMode = true
```

## View Diffing

The renderer compares the new `View` against `lastView` using `viewEquals()`, which checks all fields:

- `Content` (string equality)
- `AltScreen`, `ReportFocus`, `DisableBracketedPasteMode` (bool equality)
- `MouseMode`, `KeyboardEnhancements` (struct equality)
- `WindowTitle` (string equality)
- `ForegroundColor`, `BackgroundColor` (nil + deep equality)
- `Cursor` (nil check + deep equality)
- `ProgressBar` (nil check + deep equality)

If nothing changed and the frame area is the same, the renderer **skips the frame entirely** — no ANSI output. This is the primary performance optimization.

When content changes, the renderer:
1. Parses `Content` into a `uv.StyledString`
2. Draws it into a `uv.ScreenBuffer` (cell buffer)
3. Compares the cell buffer against the previous frame
4. Emits only the changed cells as ANSI cursor-movement + character sequences

## View Composition Patterns

For the Draw/View split pattern (rendering to a ScreenBuffer with pixel-level layout control), see [patterns.md](patterns.md#pointer-based-model-with-drawview-split).

### Simple View

```go
func (m model) View() tea.View {
    return tea.NewView(m.text)
}
```

### Styled View with Lipgloss

```go
func (m model) View() tea.View {
    style := lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("205"))
    return tea.NewView(style.Render("Hello, World"))
}
```

### Multi-Section Layout

```go
func (m model) View() tea.View {
    content := lipgloss.JoinVertical(lipgloss.Left,
        m.headerView(),
        m.bodyView(),
        m.footerView(),
    )
    v := tea.NewView(content)
    v.AltScreen = true
    v.Cursor = tea.NewCursor(m.cursorX, m.cursorY)
    v.MouseMode = tea.MouseModeCellMotion
    return v
}
```

### Conditional Alt Screen

```go
func (m model) View() tea.View {
    v := tea.NewView(m.content)
    if m.fullscreen {
        v.AltScreen = true
    }
    return v
}
```

### Dynamic Terminal State

All View fields are evaluated every frame. This means terminal state changes (alt screen, mouse mode, cursor, etc.) are **reactive** — they change when the model state changes, without needing explicit commands.

```go
func (m model) View() tea.View {
    v := tea.NewView(m.renderContent())
    v.MouseMode = tea.MouseModeCellMotion
    if m.showCursor {
        v.Cursor = tea.NewCursor(m.cursorX, m.cursorY)
    }
    if m.focused {
        v.WindowTitle = "My App — Editing"
    } else {
        v.WindowTitle = "My App"
    }
    return v
}
```
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