# Lip Gloss — Style Terminal Layouts in Go

> A style definition library from Charm for building beautiful terminal user interfaces in Go, with support for colors, borders, padding, and layout.

## Install

Save in your project root:

# Lip Gloss — Style Terminal Layouts in Go

## Quick Use
```bash
go get github.com/charmbracelet/lipgloss
```
```go
package main

import (
    "fmt"
    "github.com/charmbracelet/lipgloss"
)

func main() {
    style := lipgloss.NewStyle().
        Bold(true).
        Foreground(lipgloss.Color("#FAFAFA")).
        Background(lipgloss.Color("#7D56F4")).
        Padding(1, 3)
    fmt.Println(style.Render("Hello, Lip Gloss!"))
}
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-2934c984
Author: AI Open Source