lipgloss-v2

name: lipgloss-v2 description: >- Generates, explains, and debugs terminal styling and layout code using Charm's Lip Gloss v2 library for Go. Use when building styled terminal output, TUI layouts, color gradients, bordered boxes, tables, lists, or trees. Covers Style API, adaptive colors, LightDark detection, compositing layers, and all subpackages (list, table, tree). Also handles migration from Lip Gloss v1 to v2. allowed-tools: Read, Write, Edit, Bash(go *) metadata: category: go-cli version: "2.0"

Lip Gloss v2

Lip Gloss v2 (charm.land/lipgloss/v2) provides style definitions for terminal layouts. It is a pure value type library — no global renderer, no hidden state. Colors are downsampled at the output layer.

go get charm.land/lipgloss/v2@v2.0.0-beta.3.0.20251205162909-7869489d8971

Quick Reference

See references/MIGRATION.md for the full migration guide.

Style API

Styles are immutable value types. Chain setters, end with .Render(str).

s := lipgloss.NewStyle().
    Bold(true).
    Foreground(lipgloss.Color("#FF5F87")).
    Background(lipgloss.Color("#1a1a2e")).
    Padding(1, 2).
    Border(lipgloss.RoundedBorder()).
    BorderForeground(lipgloss.Color("#874BFD")).
    Width(40).
    Align(lipgloss.Center)

lipgloss.Println(s.Render("Hello!"))

Text properties

Layout properties

Position constants: lipgloss.Left, lipgloss.Center, lipgloss.Right, lipgloss.Top, lipgloss.Bottom.

Padding & margin

s.Padding(1, 2)          // top/bottom=1, left/right=2
s.Padding(1, 2, 3, 4)    // top, right, bottom, left
s.PaddingTop(1).PaddingLeft(2)
s.PaddingChar('·')       // fill padding with this character

s.Margin(1, 2)
s.MarginChar('·')
s.MarginBackground(color.Color)

Borders

s.Border(lipgloss.RoundedBorder())
s.Border(lipgloss.NormalBorder(), true)       // all sides
s.Border(lipgloss.ThickBorder(), true, false) // top+bottom only
s.BorderForeground(lipgloss.Color("#874BFD"))
s.BorderForegroundBlend(from, to)             // gradient border
s.BorderStyle(lipgloss.NormalBorder()).BorderBottom(true)

Border constructors: NormalBorder(), RoundedBorder(), ThickBorder(), DoubleBorder(), BlockBorder(), HiddenBorder(), ASCIIBorder(), MarkdownBorder(), InnerHalfBlockBorder(), OuterHalfBlockBorder().

Custom border:

b := lipgloss.Border{
    Top: "─", Bottom: "─", Left: "│", Right: "│",
    TopLeft: "╭", TopRight: "╮",
    BottomLeft: "╰", BottomRight: "╯",
}

Style inheritance

base := lipgloss.NewStyle().Padding(0, 1).Foreground(lipgloss.Color("5"))

// Copy and override
active := base.Bold(true).Background(lipgloss.Color("#FF5F87"))

// Inherit (fills only unset props)
child := lipgloss.NewStyle().Inherit(base)

Render helpers

s.Render("text")        // returns styled string
s.String()              // alias for Render with SetString content
s.SetString("content")  // bind content to style

Unset methods

All style properties can be unset:

s.UnsetBold()
s.UnsetForeground()
s.UnsetPadding()
s.UnsetBorder()
// etc.

Color System

color.Color is the standard image/color.Color interface.

import "charm.land/lipgloss/v2"

// Hex or ANSI256
c := lipgloss.Color("#FF5F87")
c := lipgloss.Color("200")

// Named 4-bit ANSI constants
c := lipgloss.Red      // lipgloss.Black/Red/Green/.../BrightWhite

// ANSI256
c := lipgloss.ANSIColor(134)

// NoColor - absence of color styling
c := lipgloss.NoColor{}

Adaptive colors (light/dark terminals)

Standalone:

hasDark := lipgloss.HasDarkBackground(os.Stdin, os.Stdout)
lightDark := lipgloss.LightDark(hasDark)

fg := lightDark(lipgloss.Color("#333333"), lipgloss.Color("#f1f1f1"))
s := lipgloss.NewStyle().Foreground(fg)

Bubble Tea:

func (m model) Init() tea.Cmd {
    return tea.RequestBackgroundColor
}

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.BackgroundColorMsg:
        m.styles = newStyles(msg.IsDark())
    }
    return m, nil
}

func newStyles(isDark bool) styles {
    ld := lipgloss.LightDark(isDark)
    return styles{
        title: lipgloss.NewStyle().Foreground(ld(
            lipgloss.Color("#333333"),
            lipgloss.Color("#f1f1f1"),
        )),
    }
}

Color profile selection (Complete)

import "github.com/charmbracelet/colorprofile"

p := colorprofile.Detect(os.Stdout, os.Environ())
complete := lipgloss.Complete(p)
c := complete(
    lipgloss.Color("5"),       // ANSI fallback
    lipgloss.Color("200"),     // ANSI256 fallback
    lipgloss.Color("#ff34ac"), // TrueColor
)

Color manipulation

lipgloss.Darken(c, 0.2)        // 20% darker
lipgloss.Lighten(c, 0.2)       // 20% lighter
lipgloss.Alpha(c, 0.5)         // 50% alpha
lipgloss.Complementary(c)      // 180° on color wheel

Color gradients

// 1D linear blend across N steps
colors := lipgloss.Blend1D(40, from, to, extra...)

// 2D gradient (angle 0=left→right, 180=right→left)
colors := lipgloss.Blend2D(width, height, 45.0, c1, c2, c3)
// Access: colors[y*width + x]

Layout Functions

// Join side-by-side, aligned at Top/Center/Bottom
row := lipgloss.JoinHorizontal(lipgloss.Top, blockA, blockB, blockC)

// Stack vertically, aligned at Left/Center/Right
col := lipgloss.JoinVertical(lipgloss.Left, blockA, blockB)

// Place content in a box (fills with whitespace)
out := lipgloss.Place(width, height, lipgloss.Center, lipgloss.Center, content,
    lipgloss.WithWhitespaceChars("·"),
    lipgloss.WithWhitespaceStyle(lipgloss.NewStyle().Foreground(subtle)),
)

// One-axis variants
lipgloss.PlaceHorizontal(width, lipgloss.Center, content)
lipgloss.PlaceVertical(height, lipgloss.Center, content)

Printing (Important!)

Always use Lip Gloss writers to ensure correct color downsampling:

lipgloss.Println(s)           // stdout + newline
lipgloss.Print(s)             // stdout
lipgloss.Printf("%s\n", s)    // stdout, formatted
lipgloss.Fprintln(os.Stderr, s)
lipgloss.Sprint(s)            // returns string for stdout profile
lipgloss.Sprintf("...", s)

// Customize default writer
lipgloss.Writer = colorprofile.NewWriter(os.Stderr, os.Environ())

In Bubble Tea, downsampling is automatic — just return strings normally.

Text Utilities

w := lipgloss.Width(str)           // cell width (Unicode-aware)
h := lipgloss.Height(str)          // line count
w, h := lipgloss.Size(str)         // both

wrapped := lipgloss.Wrap(str, 80, "")  // wrap preserving ANSI

// Style specific rune indices
out := lipgloss.StyleRunes(str, []int{0, 1, 2}, matched, unmatched)

// Style character ranges
out := lipgloss.StyleRanges(str,
    lipgloss.NewRange(0, 5, boldStyle),
    lipgloss.NewRange(6, 10, italicStyle),
)

Compositing (Layers)

Compose styled strings at arbitrary positions:

base := lipgloss.NewLayer(document)
modal := lipgloss.NewLayer(floatingBox).X(10).Y(5)
overlay := lipgloss.NewLayer(badge).X(80).Y(2).Z(10)

comp := lipgloss.NewCompositor(base, modal, overlay)
lipgloss.Println(comp.Render())

// Hit testing
hit := comp.Hit(x, y) // returns LayerHit with ID
if !hit.Empty() {
    fmt.Println("Clicked layer:", hit.ID())
}

Canvas

Low-level cell buffer for manual composition:

canvas := lipgloss.NewCanvas(width, height)
canvas.Compose(layer)
result := canvas.Render()

Subpackages

list (charm.land/lipgloss/v2/list)

import "charm.land/lipgloss/v2/list"

l := list.New("Item A", "Item B", "Item C").
    Enumerator(list.Roman).
    EnumeratorStyle(lipgloss.NewStyle().Foreground(lipgloss.Color("99")).MarginRight(1)).
    ItemStyle(lipgloss.NewStyle().Foreground(lipgloss.Color("255")))

// Nested lists
l.Item(
    list.New("Sub A", "Sub B"),
)

// Conditional styling
l.ItemStyleFunc(func(items list.Items, i int) lipgloss.Style {
    if i == selected {
        return selectedStyle
    }
    return normalStyle
})

lipgloss.Println(l)

Built-in enumerators: list.Bullet, list.Dash, list.Roman, list.Arabic, list.Alphabet, list.Asterisk. Custom: func(items list.Items, i int) string.

table (charm.land/lipgloss/v2/table)

import "charm.land/lipgloss/v2/table"

t := table.New().
    Border(lipgloss.ThickBorder()).
    BorderStyle(lipgloss.NewStyle().Foreground(lipgloss.Color("99"))).
    StyleFunc(func(row, col int) lipgloss.Style {
        if row == table.HeaderRow {
            return lipgloss.NewStyle().Bold(true).Align(lipgloss.Center)
        }
        if row%2 == 0 {
            return lipgloss.NewStyle().Foreground(lipgloss.Color("245"))
        }
        return lipgloss.NewStyle().Foreground(lipgloss.Color("241"))
    }).
    Headers("NAME", "LANG", "STARS").
    Rows([][]string{
        {"BubbleTea", "Go", "★★★★★"},
        {"Lipgloss", "Go", "★★★★★"},
    }...)

lipgloss.Println(t)

tree (charm.land/lipgloss/v2/tree)

import "charm.land/lipgloss/v2/tree"

t := tree.New().
    Root("project/").
    Child(
        ".git",
        tree.Root("src/").
            Child("main.go", "util.go"),
        tree.Root("docs/").
            Child("README.md"),
        "go.mod",
    ).
    Enumerator(tree.RoundedEnumerator).
    EnumeratorStyle(lipgloss.NewStyle().Foreground(lipgloss.Color("99"))).
    ItemStyle(lipgloss.NewStyle().Foreground(lipgloss.Color("255")))

lipgloss.Println(t)

Integration with huh v2 Forms

Lip Gloss v2 styles power huh v2 forms. Create custom themes by implementing huh.Theme:

import (
    "charm.land/huh/v2"
    "charm.land/lipgloss/v2"
)

// Create a custom theme
customTheme := huh.ThemeFunc(func(isDark bool) *huh.Styles {
    s := &huh.Styles{}

    // Form container
    s.Form.Base = lipgloss.NewStyle().
        Border(lipgloss.RoundedBorder()).
        BorderForeground(lipgloss.Color("#7D56F4")).
        Padding(2, 4)

    // Focused (active) field styles
    s.Focused.Title = lipgloss.NewStyle().
        Bold(true).
        Foreground(lipgloss.Color("#7D56F4"))

    s.Focused.SelectSelector = lipgloss.NewStyle().
        Foreground(lipgloss.Color("#FF6AD2")).
        SetString("▸ ")

    s.Focused.FocusedButton = lipgloss.NewStyle().
        Background(lipgloss.Color("#FF6AD2")).
        Foreground(lipgloss.Color("#FFFFFF")).
        Padding(0, 3)

    // Blurred (inactive) field styles
    s.Blurred = s.Focused
    s.Blurred.Title = s.Blurred.Title.Foreground(lipgloss.Color("#666666"))

    return s
})

// Apply theme to form
form := huh.NewForm(
    huh.NewGroup(
        huh.NewInput().Title("Name").Value(&name),
        huh.NewConfirm().Title("Proceed?").Value(&ok),
    ),
).WithTheme(customTheme)

huh Style Structure

See references/_examples/huh-theme.go for a complete custom theme example.

Examples Index

See references/_examples/ for runnable examples:

References

• references/API.md — complete API cheat sheet
• references/MIGRATION.md — v1 → v2 migration guide (also suitable for LLM-driven migration)