Lipgloss — Style Definitions for Terminal Layouts in Go

Introduction

Lipgloss is a Go library from Charm that brings CSS-like styling to terminal applications. Instead of manually concatenating ANSI escape codes, you define styles declaratively and apply them to strings. It pairs naturally with Bubble Tea and other Charm libraries to build polished terminal user interfaces.

What Lipgloss Does

• Applies foreground and background colors using ANSI, 256-color, and true-color palettes
• Adds padding, margin, borders, and alignment to terminal-rendered text blocks
• Supports adaptive color profiles that degrade gracefully on limited terminals
• Provides table rendering with configurable column widths and styles
• Composes styles through inheritance and inline overrides

Architecture Overview

Lipgloss works by building a Style struct that stores rendering properties like color, bold, italic, padding, and border. When Render is called, it measures the text, applies padding and margins, wraps borders around the content, and emits the appropriate ANSI escape sequences. The library detects the terminal color profile at runtime and maps colors to the best available representation.

Self-Hosting & Configuration

• Add to your Go module with go get and import the package
• Detect terminal capabilities automatically or set a color profile manually
• Define reusable styles as package-level variables for consistency across your UI
• Use lipgloss.JoinHorizontal and JoinVertical to compose multi-block layouts
• Combine with Bubble Tea for interactive TUI applications with styled components

Key Features

• Declarative CSS-like API that chains padding, margin, border, and color methods
• Automatic color profile detection for ANSI, 256-color, and true-color terminals
• Built-in table component with customizable headers, rows, and borders
• Responsive width handling with MaxWidth and word wrapping
• Works on Windows, macOS, and Linux without platform-specific code

Comparison with Similar Tools

• termenv — lower-level terminal color library from the same Charm team; Lipgloss builds on top of it
• color (fatih/color) — simple color output for Go, but lacks layout, padding, and border features
• tcell — full terminal screen manipulation library, more complex than Lipgloss for styling tasks
• Rich (Python) — similar concept for Python terminals with tables, panels, and markdown rendering

FAQ

Q: Does Lipgloss work on Windows? A: Yes. It supports Windows Terminal, PowerShell, and cmd.exe with automatic color profile detection.

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

Q: How does Lipgloss handle wide characters and emoji? A: It uses the go-runewidth library to correctly measure character widths, including CJK characters and emoji.

Q: Does it support nested styles? A: Yes. You can nest styled strings by rendering inner content first and passing the result to an outer style.

Sources

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