Lipgloss - Terminal styling made simple and delightful

Lipgloss is a Rust port of the popular Go library for styling terminal layouts and building Terminal User Interfaces (TUIs). It provides a comprehensive set of tools for creating beautiful, styled terminal output with support for colors, borders, alignment, positioning, and complex layout management.

Features

• Rich styling: Colors (ANSI 16, 256, and true color), bold, italic, underline, strikethrough
• Flexible layouts: Horizontal and vertical joining, precise positioning
• Border system: Multiple built-in border styles with customization options
• Color profiles: Automatic adaptation to terminal capabilities
• Unicode support: Proper handling of wide characters and emojis
• Composable design: Chain styles and combine multiple elements seamlessly

Quick Start

use lipgloss::{Style, Color, rounded_border};

// Create a styled text block
let style = Style::new()
    .foreground(Color("205".to_string()))
    .background(Color("235".to_string()))
    .padding(1, 2, 1, 2)
    .border(rounded_border())
    .border_foreground(Color("63".to_string()));

let rendered = style.render("Hello, Lipgloss!");
println!("{}", rendered);

Theme-Aware Color Best Practices

For applications that work across different terminal themes (light and dark), use the pre-defined [color] constants instead of hardcoded colors:

use lipgloss::{Style, color::{TEXT_PRIMARY, ACCENT_PRIMARY, STATUS_SUCCESS}};

// ✅ Theme-aware (adapts to light/dark backgrounds)
let good_style = Style::new()
    .foreground(TEXT_PRIMARY)         // Readable in any theme
    .border_foreground(ACCENT_PRIMARY); // Consistent brand color

// ❌ Hardcoded (breaks in some themes)
let bad_style = Style::new()
    .foreground("#000000".to_string()) // Invisible on dark backgrounds!
    .border_foreground("#ff0000".to_string()); // Harsh red everywhere

// Status indicators with semantic colors
let success_msg = Style::new()
    .foreground(STATUS_SUCCESS)
    .render("✓ Task completed successfully");

Available color constants for common UI patterns:

• Text: TEXT_PRIMARY, TEXT_MUTED, TEXT_SUBTLE, TEXT_HEADER
• Accents: ACCENT_PRIMARY, ACCENT_SECONDARY, INTERACTIVE
• Status: STATUS_SUCCESS, STATUS_WARNING, STATUS_ERROR, STATUS_INFO
• Surfaces: SURFACE_SUBTLE, SURFACE_ELEVATED
• Lists: LIST_ITEM_PRIMARY, LIST_ENUMERATOR
• Tables: TABLE_HEADER_TEXT, TABLE_ROW_TEXT, TABLE_BORDER

See the theme-showcase example for a comprehensive demonstration.

Core Modules

• [style] - Core styling functionality and the main Style struct
• [color] - Color definitions and terminal color profile management
• [mod@gradient] - Color gradients and 2D color grids for advanced styling
• [border] - Border styles and customization
• [mod@align] - Text alignment utilities
• [position] - Positioning and placement functions
• [join] - Horizontal and vertical layout joining
• [mod@size] - Dimension measurement and calculation
• [whitespace] - Styled whitespace and filler generation
• [renderer] - Terminal rendering and color profile detection

Advanced Usage

Complex layouts with multiple components:

use lipgloss::{Style, Color, join_horizontal, join_vertical, normal_border, CENTER, LEFT, TOP};

let header = Style::new()
    .align_horizontal(CENTER)
    .foreground(Color("86".to_string()))
    .render("Application Title");

let left_panel = Style::new()
    .width(30)
    .padding(1, 2, 1, 2)
    .border(normal_border())
    .render("Left content");

let right_panel = Style::new()
    .width(30)
    .padding(1, 2, 1, 2)
    .border(normal_border())
    .render("Right content");

let body = join_horizontal(TOP, &[&left_panel, &right_panel]);
let layout = join_vertical(LEFT, &[&header, &body]);

println!("{}", layout);

This crate maintains API compatibility with the original Go implementation while following Rust idioms and leveraging Rust's type system for safer terminal styling.