[go-fan] Go Module Review: charmbracelet/huh

[github-actions[bot]]

🐹 Go Fan Report: charmbracelet/huh — Terminal Forms & Prompts

Module Overview

github.com/charmbracelet/huh is Charmbracelet's terminal forms library built on Bubble Tea. It provides composable form fields — Input, Select, MultiSelect, Confirm, Text (textarea), Note, and FilePicker — grouped into multi-page forms with validation, theming, and accessible fallback modes.

Current version: v0.8.0 (v1 API)
Latest available: v2.0.3 on charm.land/huh/v2 (released 2026-03-10)

Key finding: The other Charm libraries (bubbletea, bubbles, lipgloss) are already on their v2 counterparts under charm.land/* — but huh is still on v0.8.0 (v1). This creates a dual-lipgloss workaround in the codebase today.

---

Current Usage in gh-aw

12 files import huh across the pkg/ directory:

File	Primary Usage
pkg/styles/huh_theme.go	Custom Dracula-inspired theme via huh.ThemeBase()
pkg/console/confirm.go	NewConfirm() for yes/no dialogs
pkg/console/input.go	NewInput() with EchoModePassword for secret entry
pkg/cli/interactive.go	Complex multi-group forms with Select, MultiSelect, Text
pkg/cli/engine_secrets.go	Multiple NewInput() forms for API key/token collection
pkg/cli/add_interactive_engine.go	NewSelect[string]() for AI engine selection
pkg/cli/add_interactive_auth.go	NewInput() with owner/repo format validation
pkg/cli/add_interactive_*.go (×5)	Various interactive wizard steps
pkg/cli/run_interactive.go	Workflow selection and parameter input

Key APIs used: NewForm, NewGroup, NewInput, NewSelect[T], NewMultiSelect[T], NewConfirm, NewText, NewOption, EchoModePassword, WithTheme, WithAccessible (form-level only), RunWithContext, Option[T]

All forms follow a consistent pattern:

form := huh.NewForm(
    huh.NewGroup(field1, field2).Title("...").Description("..."),
).WithTheme(styles.HuhTheme()).WithAccessible(console.IsAccessibleMode())
err := form.RunWithContext(ctx)

---

Research Findings

The Dual-Lipgloss Situation

The most notable finding is this comment in pkg/styles/huh_theme.go:

// huh v0.8.0 depends on charmbracelet/lipgloss v1, not charm.land/lipgloss/v2.
// This file intentionally uses the v1 import to match huh's type expectations.
import "github.com/charmbracelet/lipgloss"

The project needs github.com/charmbracelet/lipgloss (v1) as an indirect dep solely because huh v0.8.0 depends on it — even though the rest of the codebase uses charm.land/lipgloss/v2. Upgrading huh to v2 would clean this up.

v1 → v2 Breaking Changes (relevant to gh-aw)

Change	v1	v2
Import path	github.com/charmbracelet/huh	charm.land/huh/v2
Theme return type	*huh.Theme	huh.ThemeFunc (func(isDark bool) *Styles)
ThemeBase signature	ThemeBase()	ThemeBase(isDark bool)
WithTheme argument	*huh.Theme	huh.Theme interface
Lipgloss dep	github.com/charmbracelet/lipgloss	charm.land/lipgloss/v2
Field WithAccessible()	Available (but project doesn't use it)	Removed

The project already uses form-level WithAccessible() only — no field-level calls — so that breaking change has zero impact.

Recent Updates (v2.x line)

• v2.0.3 (2026-03-10): Fixed select cursor visibility for multiline options; viewport width recomputed on WithWidth
• v2.0.x: New ThemeDracula, ThemeCatppuccin, built-in themes now take isDark bool; ThemeFunc replaces the Theme struct; Model type exported; WithViewHook added

---

Improvement Opportunities

🏃 Quick Wins

1. Extract validation helpers: The project has inline validators scattered across forms (len(s) == 0, len(s) < 10, owner/repo format check). These could live in a shared pkg/console/validate.go, reducing repetition across the 12 files.

2. Form builder helper: Every form call duplicates .WithTheme(styles.HuhTheme()).WithAccessible(console.IsAccessibleMode()). A thin helper that applies these defaults would reduce boilerplate:

   // pkg/console/form.go
   func NewStyledForm(groups ...*huh.Group) *huh.Form {
       return huh.NewForm(groups...).WithTheme(styles.HuhTheme()).WithAccessible(IsAccessibleMode())
   }

✨ Feature Opportunities

1. Upgrade to charm.land/huh/v2: This is the primary recommendation. The migration path is:

   • Update import: github.com/charmbracelet/huh → charm.land/huh/v2
   • Update HuhTheme() return type: *huh.Theme → huh.ThemeFunc
   • Update theme building: huh.ThemeBase() → huh.ThemeBase(isDark), use charm.land/lipgloss/v2 instead of v1
   • Optionally use lipgloss.HasDarkBackground() for isDark detection
   • Drop github.com/charmbracelet/lipgloss from go.mod (no longer needed)
   • The upgrade guide: https://github.com/charmbracelet/huh/blob/main/UPGRADE_GUIDE_V2.md

2. Consider huh.ThemeDracula(isDark): huh v2 now ships a built-in Dracula theme. The project's custom theme in pkg/styles/huh_theme.go is a Dracula-inspired palette — after upgrading, it might be worth checking if huh.ThemeDracula(isDark) matches closely enough to replace the custom theme entirely (or use it as the base with minimal overrides).

3. View Hooks (new in v2): form.WithViewHook(func(v tea.View) tea.View) enables pre-render customization. Could be useful for any full-screen interactive prompts that need alt-screen mode.

📐 Best Practice Alignment

1. Theme function signature: After v2 migration, HuhTheme() should become a huh.ThemeFunc:

   // v2 pattern
   func HuhTheme() huh.ThemeFunc {
       return func(isDark bool) *huh.Styles {
           t := huh.ThemeBase(isDark)
           // customizations...
           return t
       }
   }

   This gives the theme proper light/dark adaptability instead of only responding to lipgloss.AdaptiveColor.

2. isDark detection: Currently the custom theme relies on lipgloss.AdaptiveColor for light/dark switching. With v2, the isDark bool parameter passed to ThemeFunc enables explicit conditional styling, which is cleaner and more testable.

---

Recommendations (Prioritized)

1. [High] Upgrade huh to charm.land/huh/v2 — Unifies all Charm dependencies under charm.land/*, eliminates the dual lipgloss dependency, and aligns with the already-upgraded bubbletea/bubbles/lipgloss v2 stack. The migration checklist is short and all breaking changes have minimal impact on the current codebase.

2. [Medium] Refactor HuhTheme() to ThemeFunc — Part of the v2 upgrade; enables proper isDark-aware adaptive theming.

3. [Low] Evaluate huh.ThemeDracula(isDark) as base — After v2 upgrade, compare the built-in Dracula theme against the custom one; may eliminate pkg/styles/huh_theme.go or greatly simplify it.

4. [Low] Extract form validation helpers — Move inline validators to shared utilities to reduce duplication across 12 call sites.

---

Next Steps

• Open an issue/PR to upgrade huh from v0.8.0 to charm.land/huh/v2 — the upgrade guide covers all required changes
• After migration, remove github.com/charmbracelet/lipgloss from go.mod (it will no longer be needed as a direct dep)
• Run go mod tidy to clean up

---

Module summary saved to: scratchpad/mods/huh.md
Sorted by pushed_at — huh was most recently updated (2026-03-18) among unreviewed direct dependencies

References:

• §23582472622

AI generated by Go Fan · history

• expires on Mar 27, 2026, 7:32 AM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Go Fan.

A newer discussion is available at Discussion #23213.