🐹 Go Fan Report: charmbracelet/bubbles

Today's priority pick: github.com/charmbracelet/bubbles — the repo was pushed today (2026-03-17) with a dependency update to charm.land/bubbletea/v2@2.0.2 and charm.land/lipgloss/v2@2.0.2, making it the most recently active unreviewed direct dependency.

Module Overview

Bubbles is the official TUI component library for the Bubble Tea framework. It provides production-ready, reusable UI primitives — spinners, progress bars, text inputs, text areas, lists, viewports, tables, file pickers, and more — all implementing the tea.Model interface and fitting naturally into the Elm Architecture.

Version in go.mod: v1.0.0
Latest release: v2.0.0 (released 2026-02-24) ⚠️

Note: v2 ships with a new import path: charm.land/bubbles/v2

Current Usage in gh-aw

• Files: 3 files in pkg/console/
• Components used: spinner, progress, list

Notable patterns:

• The spinner uses tea.WithoutRenderer() with manual carriage-return clearing — idiomatic for non-full-screen spinners
• The list uses tea.WithAltScreen() for a full-screen selection experience
• All components are gated on TTY detection; non-TTY environments fall back to plain text

Research Findings: v2 is Here!

The bubbles library just shipped v2.0.0 — the biggest release in the project's history. The main highlights:

Recent Updates (v1 → v2)

• New home: charm.land/bubbles/v2 — module path changed entirely
• Getters & Setters: All exported Width/Height fields replaced with SetWidth()/Width() methods
• Functional options: Constructors now use New(...Option) instead of positional args
• DefaultKeyMap: All package-level variables → functions (DefaultKeyMap())
• Real cursor support: textarea and textinput now support terminal-native cursors (opt-in)
• Viewport: Major upgrade with horizontal scrolling, regex highlights, line-number gutters, soft wrapping

Best Practices from Maintainers

• Use tea.RequestBackgroundColor + BackgroundColorMsg for proper light/dark detection (rather than blocking I/O)
• Use DefaultStyles(isDark bool) on components that support it (help, list, textarea, textinput)
• Prefer DefaultKeyMap() (function) over the old variable to get fresh values

Improvement Opportunities

⚠️ v2 Migration — Breaking Changes Affecting Current Code

The project is on v1.0.0 while v2.0.0 is available. Three specific breakages would need fixing on upgrade:

// v1 (current)
prog := progress.New(
    progress.WithScaledGradient("#BD93F9", "#8BE9FD"),
    progress.WithWidth(40),
)

// v2 equivalent
prog := progress.New(
    progress.WithColors(colorPurple, colorCyan), // image/color.Color values
    progress.WithScaled(true),
    progress.WithWidth(40),
)

// v1 (current) — string assignment
prog.EmptyColor = "#6272A4"

// v2 — requires image/color.Color
prog.EmptyColor = /* some color.Color value */

// v1 (current)
l.Styles.FilterPrompt = lipgloss.NewStyle().Foreground(styles.ColorInfo)
l.Styles.FilterCursor = lipgloss.NewStyle().Foreground(styles.ColorSuccess)

// v2 — these are now consolidated into Styles.Filter (a textinput.Styles)
// Exact migration path: see UPGRADE_GUIDE_V2.md

🏃 Quick Wins (v1-compatible)

These improvements apply now, without upgrading:

• list.go L154: The hardcoded dimensions list.New(listItems, delegate, 80, 20) ignore the terminal's actual size. Consider initializing with a sensible default and handling tea.WindowSizeMsg to also update the list height (currently only width is updated on resize)
• progress.go: The indeterminate pulsing animation manually steps through 8 states; bubbles' progress component supports animation via Harmonica natively — consider using progress.IncrPercent()/DecrPercent() with progress.FrameMsg to get smoother hardware-accelerated animation

✨ Feature Opportunities (v2)

Once migrated to v2:

• Viewport for workflow output: The new viewport supports LeftGutterFunc (line numbers!), regex highlights via SetHighlights(), and soft wrapping — a great fit for displaying structured workflow output in gh-aw
• Progress WithColorFunc: Enable dynamic color transitions — e.g., shift to red on error, green at 100% completion
• Light/Dark awareness: Use tea.RequestBackgroundColor + BackgroundColorMsg in the list model's Init() to properly adapt to the user's terminal background

📐 Best Practice Alignment

• The spinner's tea.WithoutRenderer() + manual print approach is well-executed and remains valid in v2
• list.go correctly propagates tea.WindowSizeMsg to the list width, but could also update height
• TTY gating is correct and robust — good pattern throughout the package

Recommendations

Next Steps

1. Review the v2 upgrade guide and assess migration effort
2. Coordinate with bubbletea and lipgloss upgrades (all part of the Charm v2 ecosystem — they go together)
3. Consider opening a tracking issue for the bubbles v2 migration

Generated by Go Fan 🐹
Module summary saved to: scratchpad/mods/bubbles.md
Workflow run: §23182991466

References:

• charmbracelet/bubbles v2.0.0 release notes
• Bubbles v2 Upgrade Guide
• Workflow run §23182991466

AI generated by Go Fan · history

• expires on Mar 18, 2026, 7:26 AM UTC