Lipgloss: Declarative Terminal Styling for Go Applications

Introduction

Lipgloss, from the creators at Charmbracelet, is a robust Go library designed to bring elegant and structured styling to your terminal applications. It offers a declarative, CSS-like approach to defining styles, making it intuitive for developers to create visually appealing layouts and text. Whether you're building a simple CLI tool or a complex Terminal User Interface (TUI), Lipgloss provides the tools to make your output shine.

Installation

To integrate Lipgloss into your Go project, simply use the go get command:


go get github.com/charmbracelet/lipgloss

Examples

Lipgloss offers a wide array of styling options, from basic text formatting to complex layout management.

Basic Styling

Define styles with methods like Bold, Foreground, Background, and Padding.


import "github.com/charmbracelet/lipgloss"

var style = lipgloss.NewStyle().
    Bold(true).
    Foreground(lipgloss.Color("#FAFAFA")).
    Background(lipgloss.Color("#7D56F4")).
    PaddingTop(2).
    PaddingLeft(4).
    Width(22)

fmt.Println(style.Render("Hello, kitty"))

Colors

Lipgloss supports various color profiles, automatically degrading colors if the terminal doesn't support the full range.

ANSI 16 colors (4-bit)


lipgloss.Color("5")  // magenta
lipgloss.Color("9")  // red
lipgloss.Color("12") // light blue

ANSI 256 Colors (8-bit)


lipgloss.Color("86")  // aqua
lipgloss.Color("201") // hot pink
lipgloss.Color("202") // orange

True Color (24-bit)


lipgloss.Color("#0000FF") // good ol' 100% blue
lipgloss.Color("#04B575") // a green
lipgloss.Color("#3C3C3C") // a dark gray

Adaptive Colors: Specify colors for light and dark backgrounds.
```
lipgloss.AdaptiveColor{Light: "236", Dark: "248"}
```

Inline Formatting

Apply common ANSI text formatting options.


var style = lipgloss.NewStyle().
    Bold(true).
    Italic(true).
    Faint(true).
    Blink(true).
    Strikethrough(true).
    Underline(true).
    Reverse(true)

Block-Level Formatting

Control spacing with padding and margins, similar to CSS.


// Padding shorthand
lipgloss.NewStyle().Padding(2) // 2 cells on all sides

// Margins shorthand
lipgloss.NewStyle().Margin(2, 4) // 2 cells top/bottom, 4 cells left/right

Borders

Easily add various border styles, colors, and positions.


// Add a purple, rectangular border
var style = lipgloss.NewStyle().
    BorderStyle(lipgloss.NormalBorder()).
    BorderForeground(lipgloss.Color("63"))

// Set a rounded, yellow-on-purple border to the top and left
var anotherStyle = lipgloss.NewStyle().
    BorderStyle(lipgloss.RoundedBorder()).
    BorderForeground(lipgloss.Color("228")).
    BorderBackground(lipgloss.Color("63")).
    BorderTop(true).
    BorderLeft(true)

Joining Paragraphs

Combine text blocks horizontally or vertically with alignment options.


// Horizontally join three paragraphs along their bottom edges
lipgloss.JoinHorizontal(lipgloss.Bottom, paragraphA, paragraphB, paragraphC)

// Vertically join two paragraphs along their center axes
lipgloss.JoinVertical(lipgloss.Center, paragraphA, paragraphB)

Rendering Tables

The lipgloss/table sub-package allows for structured data presentation.


import "github.com/charmbracelet/lipgloss/table"

rows := [][]string{
    {"Chinese", "??", "??"},
    {"Japanese", "?????", "??"},
}

t := table.New().
    Border(lipgloss.NormalBorder()).
    Headers("LANGUAGE", "FORMAL", "INFORMAL").
    Rows(rows...)

fmt.Println(t)

Rendering Lists

Create formatted lists with the lipgloss/list sub-package, supporting nesting and custom enumerators.


import "github.com/charmbracelet/lipgloss/list"

l := list.New("A", "B", "C")
fmt.Println(l)

// Nested list example
l = list.New(
    "A", list.New("Artichoke"),
    "B", list.New("Baking Flour", "Bananas"),
)
fmt.Println(l)

Rendering Trees

Visualize hierarchical data using the lipgloss/tree sub-package.


import "github.com/charmbracelet/lipgloss/tree"

t := tree.Root(".").
    Child("A", "B", "C")
fmt.Println(t)

// Nested tree example
t = tree.Root(".").
    Child("macOS").
    Child(
        tree.New().
            Root("Linux").
            Child("NixOS"),
    )
fmt.Println(t)

Why Use Lipgloss?

Lipgloss simplifies the creation of rich, engaging terminal interfaces. Its declarative API, inspired by web styling, allows developers to focus on the structure and content of their applications rather than the complexities of ANSI escape codes. It automatically handles color degradation, supports adaptive colors for different terminal themes, and provides powerful layout utilities. For those building TUIs with Bubble Tea, Lipgloss is an excellent companion for crafting beautiful views.