Versions and component selection #

Resolve the repository before choosing an API #

Research snapshot: 2026-09-23. The inspected published documentation showed Bubble Tea v2.0.9, Bubbles v2.2.1, and Lip Gloss v2.0.6. This records what was inspected, not a promise that those are permanently the newest releases or an instruction to upgrade a working project. S01 S02 S03

Start with the repository's go.mod, go.sum, go.work if present, and source imports. Follow the installed APIs and existing conventions. Check each dependency's Go/toolchain requirement before proposing changes. Module resolution may need network access; do not silently modify the module graph just to inspect it.

Useful local checks, when the repository and dependencies are available:

go version
go list -m all
go test ./...

Use a focused import search as well. Multiple versions can legitimately appear in a dependency graph, but v1 and v2 Tea model/message/component APIs cannot be casually interchanged in one implementation.

For an existing v1 application, fixing a focus bug does not require migration. For an explicit migration, move the interdependent Tea/Bubbles/Lip Gloss layer together, adapt the relevant tests, and verify behavior before optimizing. Bubbles' upgrade guide expressly calls for the companion upgrades. S02

High-impact v1/v2 differences #

This is a triage map, not a replacement for the full upgrade guides. Refer to S01, S02, and S03. Do not mechanically convert unrelated packages that retain a github.com/charmbracelet/... module path.

An original minimal v2 method sketch, not a standalone application:

func (m model) View() tea.View {
    v := tea.NewView(m.renderContent())
    v.AltScreen = m.fullScreen
    return v
}

For background-aware styling, the documented v2 pattern requests background color through Tea and reacts to tea.BackgroundColorMsg. Keep a fallback style when no reply arrives. Root model methods return a tea.View; embedded Bubbles often still render strings. Do not change every component's View signature merely because the root signature changed.

Choose components for their interaction semantics #

Text input / textarea: use for editing, cursor movement, focus, and paste behavior. Configure their styles and dimensions with the target version's API. Keep app shortcuts from stealing printable input. Do not replace their editing model with ad hoc rune slicing to save a small amount of code.

List: appropriate when its filtering, pagination, selection, and help behavior fit. A custom delegate can preserve a bespoke row design. A simple fixed list may only need a slice and cursor; a huge variable-height transcript may need a specialized view. Do not force all three into one abstraction.

Table: appropriate when column comparison is the main task. Decide what columns survive narrowing and what long values do. A table-shaped display is not necessarily an interactive Bubbles table; static Lip Gloss tables serve a different role.

Viewport: owns scrolling, not necessarily the expensive work of generating all content. Decide whether to wrap, clip, or scroll horizontally. Regenerating content should preserve the user's anchor unless a deliberate navigation action changes it.

Help + key: use a shared vocabulary for routing and hints. Enabled bindings should reflect the active state. A hand-written one-line footer can be sufficient for a truly tiny interaction, but it must not drift from the implementation.

Spinner / progress / timer: choose according to available information. Unknown-duration work needs activity, not a fabricated percentage. Preserve returned scheduling commands and stop inactive animation.

These component categories are documented in the Bubbles catalogue; the selection criteria above are recommendations. S02

Huh: useful for forms, field validation, and accessible prompting. It is not a reason to turn an arbitrary browser into a form. Do not start a second blocking interactive loop inside a running Tea update function; follow documented embedding or handoff patterns. S11

Gum: useful for shell-script composition. Importing an entire application because it contains an appealing picker is usually less appropriate than using the underlying Bubbles or learning its interaction pattern. S07

Glamour: use when Markdown formatting is the task, then cache or schedule expensive rendering appropriately. Wish: investigate when serving a TUI over SSH, with session-local ownership. These are optional capabilities, not default dependencies. S17

Testing dependencies must match too #

The inspected legacy github.com/charmbracelet/x/exp/teatest module depends on Bubble Tea v1. The separate module github.com/charmbracelet/x/exp/teatest/v2 exists and imports charm.land/bubbletea/v2. Its inspected go.mod declares Go 1.24.2 and a v2 release-candidate minimum dependency. These are facts about the inspected files, not proof of compatibility with every later release. Select and test an appropriate revision in the target application's graph. S12 S13

The v2 helper supports initial terminal size, program options, sending messages, typing text, waiting for conditions, and reading final model/output with timeouts. Read its current implementation before relying on test lifecycle behavior. A virtual-input test is not equivalent to a real terminal restoration test. S14