Crate lipgloss

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
• gradient - Color gradients and 2D color grids for advanced styling
• border - Border styles and customization
• align - Text alignment utilities
• position - Positioning and placement functions
• join - Horizontal and vertical layout joining
• 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.

Re-exports

pub use blending::blend_1d;

pub use blending::blend_2d;

pub use gradient::bilinear_interpolation_grid;

pub use gradient::gradient;

pub use gradient::gradient_rgb;

pub use utils::get_lines;

pub use utils::get_lines_visible;

pub use utils::new_range;

pub use utils::strip_ansi;

pub use utils::style_ranges;

pub use utils::style_runes;

pub use utils::which_sides_bool;

pub use utils::which_sides_color;

pub use utils::which_sides_int;

pub use utils::width_visible;

pub use utils::NewRange;

pub use utils::Range;

pub use utils::StyleRanges;

pub use utils::StyleRunes;

pub use align::*;

pub use border::*;

pub use color::*;

pub use join::*;

pub use position::*;

pub use renderer::*;

pub use size::*;

pub use style::*;

Modules

align

Text alignment utilities for terminal user interfaces.

blending

Color blending functionality for creating gradients and color transitions.

border

Terminal border drawing and box-drawing character definitions.

color

Color handling and terminal color representation.

gradient

Functions for creating color gradients and grids for terminal styling.

join

Text joining utilities for combining multiple strings with alignment.

position

Positioning and alignment utilities for placing text within boxes.

renderer

Rendering engine with terminal color profile detection and background detection.

security

Memory safety and security utilities for the lipgloss library.

size

String size measurement utilities for terminal display.

style

Terminal text styling with comprehensive formatting capabilities.

utils

Utility functions for text measurement, ANSI handling, and style ranges.

whitespace

Constants

NO_TAB_CONVERSION

Special value for Style::tab_width to disable tab conversion entirely.