lipgloss

Lipgloss is a Go library from Charm for styling terminal output with an expressive, declarative API modeled on CSS. Instead of manually concatenating ANSI escape codes, developers chain methods on a Style value — Bold, Foreground, Padding, Border, Width — and call Render to produce correctly formatted terminal text.

Beyond simple text styling, Lipgloss ships layout primitives for joining and aligning blocks of text horizontally and vertically, a cell-based compositor for layering positioned content (with mouse hit-detection for interactive layers), and companion subpackages (table, list, tree) for structured terminal output. It automatically downsamples colors to match the terminal’s actual color profile, so the same style code renders correctly whether the terminal supports true color, 256 colors, ANSI 16, or no color at all.

Lipgloss is a foundational piece of the Charm terminal UI ecosystem, commonly paired with Bubble Tea for building full interactive TUI applications, but it works equally well standalone for CLI tools that just need attractive, portable formatted output.

What You Get

• A fluent Style builder covering color (4-bit, 8-bit, and 24-bit true color), bold/italic/underline/strikethrough formatting, and clickable terminal hyperlinks
• CSS-style shorthand for padding, margins, and borders, including custom border character sets and multi-color gradient borders
• Layout utilities for joining and aligning multi-line text blocks horizontally or vertically along configurable axes
• A cell-based compositor (layer.go, canvas.go) for layering positioned content with z-index ordering and mouse click detection
• Companion table, list, and tree subpackages for rendering structured data without hand-rolled formatting
• Automatic color profile detection and downsampling so the same style code works across true-color, 256-color, ANSI, and no-color terminals

Common Use Cases

• Styling output for standalone CLI tools so status messages, headers, and tables look polished without manual ANSI code juggling
• Building the visual layer of interactive terminal UIs, typically alongside Bubble Tea, for panels, dialogs, and layouts
• Rendering structured data — configuration summaries, diffs, comparison tables — with the table and tree subpackages
• Producing terminal output that degrades gracefully in CI logs or non-color terminals via automatic profile downsampling
• Compositing layered terminal “canvases” for dashboards or games that need precisely positioned, z-ordered content

Under The Hood

Architecture Lipgloss centers on Style, an immutable value type in style.go whose properties are packed into a propKey bitmask, so styles can be copied, inherited, and partially overridden (Inherit, UnsetX) without pointer aliasing bugs. Rendering fans out through platform-specific ANSI handling (ansi_unix.go/ansi_windows.go) and the github.com/charmbracelet/x/ansi package, while layout concerns are cleanly separated into join.go, align.go, and position.go. A separate compositing layer (layer.go, canvas.go) provides z-indexed, positioned content layering with mouse-click hit testing, and the table, list, and tree directories are self-contained subpackages that build on the core Style API rather than reaching into its internals — a modular structure where each concern (styling, layout, compositing, structured rendering) can be understood and changed independently.

Tech Stack Written in pure Go (module charm.land/lipgloss/v2, targeting Go 1.25) with a deliberately small dependency set: charmbracelet/x/ansi and charmbracelet/colorprofile for terminal capability detection and ANSI sequence generation, charmbracelet/ultraviolet and x/term/x/termios for terminal I/O, lucasb-eyer/go-colorful for color-space math (blending, darkening/lightening), and clipperhouse/displaywidth/rivo/uniseg for correct Unicode cell-width measurement. No web framework or runtime dependencies — this is a leaf library meant to be imported directly.

Code Quality Test files sit alongside nearly every source file (style_test.go, borders_test.go, table_test.go, tree_test.go, and more, totaling over 2,000 lines of tests), several using golden-file comparisons via charmbracelet/x/exp/golden. CI runs a dedicated coverage workflow with the race detector and reports to Coveralls, plus separate build and lint workflows and automated dependabot-sync, indicating an actively maintained quality gate rather than ad hoc testing.

What Makes It Unique Few terminal libraries commit as fully to a CSS-inspired mental model — padding/margin shorthand syntax, inheritance with explicit unset semantics, and copy-by-assignment value styles that behave like CSS classes rather than mutable builders. The automatic color-profile downsampling removes a whole class of “looks broken in some terminals” bugs, and the cell-based compositor with mouse-aware layers goes beyond simple text styling into genuine terminal UI layout, which is why it underpins much of the wider Charm TUI ecosystem.