[go-fan] Go Module Review: charm.land/bubbles/v2

[github-actions[bot]]

Today's module pick: charm.land/bubbles/v2 (charmbracelet/bubbles v2.1.0) — selected as the most recently updated eligible dependency (released 2026-03-26, not reviewed in the last 7 days).

---

Module Overview

Bubbles is Charm's official component library for Bubble Tea TUI applications. It ships production-tested primitives — spinner, progress bar, textarea, textinput, viewport, table, list, file picker, paginator, help, key bindings, timer, and stopwatch — all following the Elm Architecture (Init/Update/View).

The v2 series aligns with the Bubble Tea v2 API (new tea.View return type, revised message types).

---

Current Usage in gh-aw

Only 2 components from this 14-component library are currently used:

Component	File	APIs Used
spinner	pkg/console/spinner.go	spinner.New(), WithSpinner(MiniDot), WithStyle(), spinner.TickMsg
progress	pkg/console/progress.go	progress.New(), WithColors(), WithScaled(), WithWidth(), ViewAs()

Spinner pattern — uses a non-standard but correct WithoutRenderer() approach: the spinner runs in a side-channel tea.Program on stderr while huh forms can safely take over stdin. tea.WithInput(nil) explicitly prevents the spinner from consuming keystrokes. The goroutine lifecycle is well-managed: mutex-guarded start/stop, sync.WaitGroup for clean shutdown.

Progress bar pattern — uses ViewAs(float64) for static (non-animated) rendering, bypassing the spring animation system. Two modes are supported:

• Determinate: ViewAs(current/total) — clean and idiomatic.
• Indeterminate: manually cycles pulsePercent via updateCount % 8 to simulate a pulsing bar.

---

Research Findings

Recent Updates — v2.1.0 (2026-03-26)

The headline feature is dynamic textarea height:

ta := textarea.New()
ta.DynamicHeight = true    // Enable vertical auto-resize
ta.MinHeight = 3           // Minimum visible rows
ta.MaxHeight = 10          // Maximum visible rows
ta.MaxContentHeight = 20   // Maximum content rows

This is directly relevant if the project ever needs multi-line input outside a huh form context.

Key progress APIs Worth Knowing

// Static rendering (what gh-aw uses — correct)
bar.ViewAs(0.65)

// Animated transitions via spring physics (not used)
cmd := bar.SetPercent(0.65)   // returns tea.Cmd to drive animation
bar.IncrPercent(0.1)
bar.DecrPercent(0.1)

// Dynamic color based on percentage (not used)
progress.WithColorFunc(func(total, current float64) color.Color {
    if total > 0.9 { return lipgloss.Color("#FF0000") }
    return lipgloss.Color("#00FF00")
})

// Custom fill characters (not used)
progress.WithFillCharacters('█', '░')

Best Practices from Maintainers

• Use ViewAs() when calling from outside a Bubble Tea program (no commands needed).
• Use SetPercent() + Update() when inside a Bubble Tea program for smooth spring animation.
• WithScaled(true) (used in gh-aw) scales the gradient to match filled width — gives a more visually satisfying graduated fill at partial completion.

---

Improvement Opportunities

🏃 Quick Wins

1. Smoother indeterminate pulsing animation

The current code in progress.go:105-113 uses 8 linear steps (updateCount % 8), which creates a stepped — not smooth — visual:

// Current: 8 linear steps producing visible discontinuities
pulseStep := p.updateCount % 8

Replacing with a sine wave would eliminate the stepping:

// Smoother: sinusoidal oscillation
pulsePercent := 0.5 + 0.2*math.Sin(float64(p.updateCount)*math.Pi/4)

This produces a smooth 0.3→0.7→0.3 oscillation with 8 steps per cycle.

2. Terminal-width-aware progress bar

The progress bar width is hardcoded to 40 (progress.WithWidth(40)). If tty.GetTerminalWidth() is available, the bar could fill available horizontal space, looking more polished on wide terminals:

width := 40
if w := tty.GetTerminalWidth(); w > 60 {
    width = w - 20 // leave room for percentage and padding
}
prog := progress.New(
    progress.WithColors(...),
    progress.WithScaled(true),
    progress.WithWidth(width),
)

3. WithColorFunc for contextual colors

The current gradient (purple→cyan) is always the same. WithColorFunc allows the color to encode semantics:

progress.WithColorFunc(func(total, current float64) color.Color {
    // Turn red when nearing a quota limit
    if total > 0.9 { return lipgloss.Color("#FF4444") }
    return lipgloss.InterpolateColors(styles.ColorPurple, styles.ColorInfo, total)
})

✨ Feature Opportunities

Bubbles components not yet used that could benefit gh-aw:

Component	Opportunity
textarea (v2.1.0)	Multi-line text input with dynamic height — useful for user-provided content (prompts, configs) outside a form
viewport	Scrollable content pager for long compile output, YAML previews, or log tailing
filepicker	Interactive file selection — more friendly than typing paths
table	Interactive scrollable tables with row selection — complements the existing static lipgloss table

The bubbles/viewport is particularly interesting: the project currently uses lipgloss.JoinVertical to compose and print sections, but has no way to make long output scrollable. A viewport in a short-lived Bubble Tea program could paginate long results.

📐 Best Practice Alignment

The current usage is mostly idiomatic with a few notes:

• ✅ WithoutRenderer() + manual ANSI for spinner side-channel — correct and intentional.
• ✅ tea.WithInput(nil) prevents spinner from consuming form input — well thought out.
• ✅ ViewAs() (not View()) for static progress — correct choice.
• ✅ Mutex + WaitGroup lifecycle management on spinner — no data races.
• ⚠️ The indeterminate pulsing is hand-rolled rather than using the spring animation. This is acceptable for ViewAs()-based rendering but the stepping is visible.
• ⚠️ Progress bar width is hardcoded at 40 — not responsive to terminal size.

🔧 General Improvements

The project owns 14 components but uses 2. Before building custom TUI widgets, it's worth checking if bubbles already has it:

• Custom numbered text list (list.go:showTextList) → bubbles/list handles this with filtering and pagination.
• RenderTitleBox in console.go → bubbles/viewport could manage these as scrollable sections.

---

Recommendations

Priority	Action
Medium	Replace updateCount % 8 linear steps with math.Sin for smooth indeterminate pulsing
Low	Make progress bar width terminal-aware via tty.GetTerminalWidth()
Low	Explore bubbles/viewport for long-output scrolling (verbose compile results, YAML previews)
Info	bubbles/textarea DynamicHeight is available if multi-line input is ever needed outside huh forms
Info	bubbles/filepicker is production-ready if interactive file selection is added

---

Next Steps

• Evaluate bubbles/viewport for long compile/lint output display
• Consider sinusoidal indeterminate animation (math.Sin-based) for visual polish
• Document the WithoutRenderer() spinner pattern as an architectural decision comment

---

Module summary saved to: scratchpad/mods/bubbles.md

References:

• §24233647833

Generated by Go Fan · ● 336.4K · ◷

• expires on Apr 11, 2026, 8:27 AM UTC

[github-actions[bot]]

💥 WHOOSH! 🦸

KAPOW! The Smoke Test Agent bursts through the wall like a comet from the outer reaches of CI space!

"I have scanned your modules, analyzed your bubbly progress bars, and emerged VICTORIOUS!" — The Agent

🌟 SMOKE TEST AGENT WAS HERE — Run §24239413809 complete! All systems NOMINAL!

BAM! POW! ZZZAP! 🔥

💥 [THE END] — Illustrated by Smoke Claude · ● 306.2K · ◷