Lip Gloss — Style Terminal Layouts in Go

Introduction

Lip Gloss is a CSS-like style definition library for terminal layouts, created by the Charm team. It brings the declarative styling mental model from the web to terminal applications, making it straightforward to build polished CLI interfaces in Go with consistent padding, margins, borders, and colors.

What Lip Gloss Does

• Defines terminal styles using a composable, chainable Go API
• Supports foreground/background colors in ANSI, 256-color, and TrueColor
• Handles padding, margins, borders, and alignment for block-level layout
• Provides horizontal and vertical joining of styled blocks for complex layouts
• Integrates with Bubble Tea for interactive terminal application development

Architecture Overview

Lip Gloss renders styled content by calculating ANSI escape sequences for each style property. Styles are immutable value types that can be copied and extended. The layout engine measures visible string width (accounting for wide characters and ANSI codes) to compute padding and alignment. Color output is auto-detected based on terminal capabilities, degrading gracefully from TrueColor to 256 to ANSI.

Self-Hosting & Configuration

• Add to your Go project with go get github.com/charmbracelet/lipgloss
• Create styles with lipgloss.NewStyle() and chain methods for each property
• Use lipgloss.Color() for hex/ANSI colors or lipgloss.AdaptiveColor{} for light/dark themes
• Join blocks horizontally with lipgloss.JoinHorizontal() or vertically with lipgloss.JoinVertical()
• Combine with Bubble Tea and Bubble components for full interactive TUI applications

Key Features

• CSS-like mental model: padding, margin, border, and alignment for the terminal
• Adaptive colors that switch between light and dark terminal backgrounds
• Unicode-aware width calculation handles CJK characters and emoji correctly
• Immutable styles that are safe to copy and share across goroutines
• Works standalone or as the styling layer for the Charm TUI ecosystem

Comparison with Similar Tools

• tcell — low-level terminal cell rendering; Lip Gloss is high-level declarative styling
• termenv — color and style primitives; Lip Gloss adds layout, borders, and composition
• pterm — pre-built UI components; Lip Gloss focuses on composable style primitives
• Rich (Python) — similar concept in Python; Lip Gloss is Go-native with a chainable API
• Textual (Python) — full TUI framework; Lip Gloss is a focused styling library, not a framework

FAQ

Q: Can I use Lip Gloss without Bubble Tea? A: Yes. Lip Gloss is a standalone library. You can use it in any Go program that prints to a terminal.

Q: Does Lip Gloss handle terminal color detection? A: Yes. It auto-detects color profile (TrueColor, 256, ANSI, or none) and degrades gracefully.

Q: Is Lip Gloss thread-safe? A: Styles are immutable value types, so they are safe to use across goroutines.

Q: Can I create responsive layouts? A: Yes. Use lipgloss.Width() and lipgloss.Height() with Place() to position content within a given area.

Sources

• https://github.com/charmbracelet/lipgloss
• https://charm.sh/libs/lipgloss