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

[github-actions[bot]]

Module Overview

Lip Gloss is a CSS-inspired terminal styling library from the Charm team. It provides a declarative, chainable API for colors, borders, padding, margins, alignment, and layout composition — the design layer for Bubble Tea TUIs. This is one of the most actively maintained modules in gh-aw's dependency tree, with v2.0.2 released on 2026-03-11.

The module went through a major migration: v1 lived at github.com/charmbracelet/lipgloss, while v2 moved to charm.land/lipgloss/v2 — a new import path with significant API improvements.

---

Current Usage in gh-aw

The project uses both lipgloss versions simultaneously:

Version	Import Path	Files
v2 (primary)	charm.land/lipgloss/v2	pkg/styles/theme.go, pkg/console/console.go, pkg/console/banner.go, pkg/console/list.go
v1 (legacy compat)	github.com/charmbracelet/lipgloss	pkg/styles/huh_theme.go only

• Files: 5 Go files (plus 1 test)
• Import Count: 6 imports (5 v2, 1 v1)
• Key APIs Used: NewStyle(), compat.AdaptiveColor, charm.land/lipgloss/v2/table, JoinVertical, RoundedBorder(), DoubleBorder(), Border(), Foreground(), Background(), Bold(), Italic()

The split is intentional: pkg/styles/huh_theme.go documents clearly that huh v0.8.0 depends on the v1 type system (lipgloss.AdaptiveColor, lipgloss.HiddenBorder()), so it cannot yet be migrated to v2.

---

Research Findings

Recent Updates (v2.0.2 — 2026-03-11)

• Table fix: Rewrote the visible-rows calculation algorithm to correctly account for content wrapping, fixing height/overflow bugs with wrapped table content. This is relevant since pkg/console/console.go uses charm.land/lipgloss/v2/table for RenderTable.

Best Practices from Maintainers

1. v2 Style is a pure value type — no renderer pointer, no global state, safe for package-level variables and concurrent use.
2. Color downsampling is at the output layer — Style.Render() always emits full ANSI; use lipgloss.Println/lipgloss.Fprint for automatic downsampling to terminal capability.
3. LightDark is the idiomatic v2 color adaptation — compat.AdaptiveColor works but reads global I/O; LightDark(isDark)(light, dark) is more explicit.
4. Define styles as package-level var — since Style is a value type, allocation is cheap but avoids repeated construction.

---

Improvement Opportunities

🏃 Quick Wins

1. Hoist inline styles in pkg/console/list.go

In itemDelegate.Render(), three styles are created fresh on every item render frame:

// pkg/console/list.go:92-103 — called on every render
selectedStyle := lipgloss.NewStyle().Foreground(styles.ColorSuccess).Bold(true)
titleStyle    := lipgloss.NewStyle().Foreground(styles.ColorForeground)
descStyle     := lipgloss.NewStyle().Foreground(styles.ColorComment).Italic(true)

Since Style is a value type in v2, these are safe to define as package-level var (like the pattern already used in pkg/styles/theme.go), avoiding per-frame allocation.

2. Consider lipgloss.Fprint/lipgloss.Fprintln for styled stderr output

pkg/console/console.go uses the manual applyStyle(style, text) + isTTY() guard pattern. In v2, using lipgloss.Fprint(os.Stderr, ...) would handle automatic color downsampling at the writer level, removing the need for the TTY check inside applyStyle.

View current vs. v2-idiomatic pattern

// Current: manual TTY check + fmt.Fprintln
func applyStyle(style lipgloss.Style, text string) string {
    if isTTY() {
        return style.Render(text)
    }
    return text
}
// ...
fmt.Fprintln(os.Stderr, plan) // in RenderComposedSections

// v2-idiomatic: lipgloss writer handles downsampling
lipgloss.SetDefaultOutput(colorprofile.NewWriter(os.Stderr, os.Environ()))
lipgloss.Fprintln(os.Stderr, plan) // auto-strips ANSI in non-TTY

This is a nice-to-have refactor, not a bug — the current approach is correct and safe.

---

✨ Feature Opportunities

1. Clickable hyperlinks for file paths

v2 adds lipgloss.NewStyle().Hyperlink(url) support. File paths in FormatError could render as terminal hyperlinks in supporting terminals (VS Code, iTerm2, modern terminals):

// Could turn file paths into clickable links
pathStyle := lipgloss.NewStyle().
    Foreground(styles.ColorPurple).
    Bold(true).
    Hyperlink("(redacted) + absolutePath)

2. Richer underline styles in ListHeader

v2 offers UnderlineStyle(lipgloss.UnderlineCurly), UnderlineDouble, UnderlineDotted, etc. The ListHeader style in theme.go uses basic Underline(true):

// Current
var ListHeader = lipgloss.NewStyle().Bold(true).Underline(true).Foreground(ColorSuccess)

// v2 alternative with curly underline for visual distinction
var ListHeader = lipgloss.NewStyle().Bold(true).UnderlineStyle(lipgloss.UnderlineCurly).Foreground(ColorSuccess)

3. Gradient error box border

v2 adds BorderForegroundBlend(...color.Color) for gradient border colors, which could make the ErrorBox in theme.go more visually impactful.

---

📐 Best Practice Alignment

1. compat.AdaptiveColor vs LightDark

The project uses compat.AdaptiveColor across all of theme.go. While this works, the v2 upgrade guide notes that compat "reads stdin/stdout globally" which "removes transparency around when I/O happens." For new code, LightDark(isDark)(light, dark) is preferred. The existing usage is fine — this is a future migration consideration.

2. Tracking huh v1→v2 migration

The huh_theme.go v1 dependency will become removable once github.com/charmbracelet/huh updates to charm.land/lipgloss/v2. This should be tracked — it will simplify the go.mod by removing the github.com/charmbracelet/lipgloss direct dependency.

---

🔧 General Improvements

The project's lipgloss usage is well-structured overall:

• Clean separation between color definitions (pkg/styles/) and usage (pkg/console/)
• Good use of named semantic styles (Error, Warning, Success, Info, FilePath, etc.)
• Consistent Dracula-inspired dark theme with proper light-mode counterparts
• The v1/v2 coexistence is handled correctly with a clear comment explaining why

---

Recommendations

Priority	Action	File
Medium	Hoist selectedStyle, titleStyle, descStyle to package-level in list.go	pkg/console/list.go:92-103
Low	Track huh migration to lipgloss v2 to remove the v1 direct dependency	pkg/styles/huh_theme.go
Low	Explore Hyperlink() for file path rendering in error output	pkg/console/console.go
Low	Consider switching from compat.AdaptiveColor to LightDark for new styles	pkg/styles/theme.go

Next Steps

• Watch for github.com/charmbracelet/huh releasing a version that depends on charm.land/lipgloss/v2 — at that point huh_theme.go can be migrated and the v1 dep removed
• The table wrapping fix in v2.0.2 is already captured since charm.land/lipgloss/v2 v2.0.2 is already in go.mod

---

Module summary saved to: scratchpad/mods/charmbracelet-lipgloss.md
Workflow run: §23477800939

AI generated by Go Fan · history

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

[github-actions[bot]]

This discussion has been marked as outdated by Go Fan.

A newer discussion is available at Discussion #22839.