Lip Gloss

<img src="https://github.com/user-attachments/assets/d13bbe1a-d2b2-4d18-9302-419a0bc3f579" width="350">


<a href="https://github.com/charmbracelet/lipgloss/releases"><img src="https://img.shields.io/github/release/charmbracelet/lipgloss.svg" alt="Latest Release"></a>
<a href="https://pkg.go.dev/charm.land/lipgloss/v2?tab=doc"><img src="https://godoc.org/github.com/golang/gddo?status.svg" alt="GoDoc"></a>
<a href="https://github.com/charmbracelet/lipgloss/actions"><img src="https://github.com/charmbracelet/lipgloss/workflows/build/badge.svg" alt="Build Status"></a>

Style definitions for nice terminal layouts. Built with TUIs in mind.

Lip Gloss takes an expressive, declarative approach to terminal rendering. Users familiar with CSS will feel at home with Lip Gloss.

import "charm.land/lipgloss/v2"

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

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

Installation

go get charm.land/lipgloss/v2

[!TIP]

Upgrading from v1? Check out the upgrade guide, or point your LLM at it and let it go to town.

Colors

Lip Gloss supports the following color profiles:

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 (16,777,216 colors; 24-bit)

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

...as well as a 1-bit ASCII profile, which is black and white only.

There are also named constants for the 16 standard ANSI colors:

lipgloss.Black
lipgloss.Red
lipgloss.Green
lipgloss.Yellow
lipgloss.Blue
lipgloss.Magenta
lipgloss.Cyan
lipgloss.White
lipgloss.BrightBlack
lipgloss.BrightRed
lipgloss.BrightGreen
lipgloss.BrightYellow
lipgloss.BrightBlue
lipgloss.BrightMagenta
lipgloss.BrightCyan
lipgloss.BrightWhite

Automatically Downsampling Colors

Some users don't have Truecolor terminals. Other times, output might not support color at all (for example, in logs). Lip Gloss was designed to handle this gracefully by automatically downsampling colors to the best available profile.

If you're using Lip Gloss with Bubble Tea, there’s nothing to do. If you're using Lip Gloss standalone, just use lipgloss.Println or lipgloss.Sprint (and their variants).

For more, see advanced color usage.

Color Utilities

Lip Gloss ships with a handful of handy tools for working with colors:

c := lipgloss.Color("#EB4268")      // Sriracha sauce color
dark := lipgloss.Darken(c, 0.5)     // dark Sriracha sauce
light := lipgloss.Lighten(c, 0.35)  // light Sriracha sauce
green := lipgloss.Complementary(c)  // greenish Sriracha sauce
withAlpha := lipgloss.Alpha(c, 0.2) // watered down Sriracha sauce

Advanced Color Tooling

Lip Gloss also supports color blending, automatically choosing light or dark variants of colors at runtime, and a lot more. For details, see Advanced Color Usage and [the docs][docs].

Inline Formatting

Lip Gloss supports the usual ANSI text formatting options:

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

Underline Styles

Beyond simple on/off, underlines support multiple styles and custom colors:

s := lipgloss.NewStyle().
    UnderlineStyle(lipgloss.UnderlineCurly).
    UnderlineColor(lipgloss.Color("#FF0000"))

Available styles: UnderlineNone, UnderlineSingle, UnderlineDouble, UnderlineCurly, UnderlineDotted, UnderlineDashed.

Hyperlinks

Styles can render clickable hyperlinks in supporting terminals:

s := lipgloss.NewStyle().
    Foreground(lipgloss.Color("#7B2FBE")).
    Hyperlink("https://charm.land")

lipgloss.Println(s.Render("Visit Charm"))

In unsupported terminals this will degrade gracefully and hyperlinks will simply not render.

Block-Level Formatting

Lip Gloss also supports rules for block-level formatting:

// Padding
var style = lipgloss.NewStyle().
    PaddingTop(2).
    PaddingRight(4).
    PaddingBottom(2).
    PaddingLeft(4)

// Margins
var style = lipgloss.NewStyle().
    MarginTop(2).
    MarginRight(4).
    MarginBottom(2).
    MarginLeft(4)

There is also shorthand syntax for margins and padding, which follows the same format as CSS:

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

// 2 cells on the top and bottom, 4 cells on the left and right
lipgloss.NewStyle().Margin(2, 4)

// 1 cell on the top, 4 cells on the sides, 2 cells on the bottom
lipgloss.NewStyle().Padding(1, 4, 2)

// Clockwise, starting from the top: 2 cells on the top, 4 on the right, 3 on
// the bottom, and 1 on the left
lipgloss.NewStyle().Margin(2, 4, 3, 1)

You can also customize the characters used for padding and margin fill:

s := lipgloss.NewStyle().
    Padding(1, 2).
    PaddingChar('·').
    Margin(1, 2).
    MarginChar('░')

Aligning Text

You can align paragraphs of text to the left, right, or center.

var style = lipgloss.NewStyle().
    Width(24).
    Align(lipgloss.Left).  // align it left
    Align(lipgloss.Right). // no wait, align it right
    Align(lipgloss.Center) // just kidding, align it in the center

Width and Height

Setting a minimum width and height is simple and straightforward.

var style = lipgloss.NewStyle().
    SetString("What’s for lunch?").
    Width(24).
    Height(32).
    Foreground(lipgloss.Color("63"))

Borders

Adding borders is easy:

// 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)

// Make your own border
var myCuteBorder = lipgloss.Border{
    Top:         "._.:*:",
    Bottom:      "._.:*:",
    Left:        "|*",
    Right:       "|*",
    TopLeft:     "*",
    TopRight:    "*",
    BottomLeft:  "*",
    BottomRight: "*",
}

There are also shorthand functions for defining borders, which follow a similar pattern to the margin and padding shorthand functions.

// Add a thick border to the top and bottom
lipgloss.NewStyle().
    Border(lipgloss.ThickBorder(), true, false)

// Add a double border to the top and left sides. Rules are set clockwise
// from top.
lipgloss.NewStyle().
    Border(lipgloss.DoubleBorder(), true, false, false, true)

You can also pass multiple colors to a border for a gradient effect:

s := lipgloss.NewStyle().
    Border(lipgloss.RoundedBorder()).
    BorderForegroundBlend(lipgloss.Color("#FF0000"), lipgloss.Color("#0000FF"))

For more on borders see the docs.

Copying Styles

Just use assignment:

style := lipgloss.NewStyle().Foreground(lipgloss.Color("219"))

copiedStyle := style // this is a true copy

wildStyle := style.Blink(true) // this is also true copy, with blink added

Since Style is a pure value type, assigning a style to another effectively creates a new copy of the style without mutating the original.

Inheritance

Styles can inherit rules from other styles. When inheriting, only unset rules on the receiver are inherited.

var styleA = lipgloss.NewStyle().
    Foreground(lipgloss.Color("229")).
    Background(lipgloss.Color("63"))

// Only the background color will be inherited here, because the foreground
// color will have been already set:
var styleB = lipgloss.NewStyle().
    Foreground(lipgloss.Color("201")).
    Inherit(styleA)

Unsetting Rules

All rules can be unset:

var style = lipgloss.NewStyle().
    Bold(true).                        // make it bold
    UnsetBold().                       // jk don't make it bold
    Background(lipgloss.Color("227")). // yellow background
    UnsetBackground()                  // never mind

When a rule is unset, it won’t be inherited or copied.

Enforcing Rules

Sometimes, such as when developing a component, you want to make sure style definitions respect their intended purpose in the UI. This is where Inline and MaxWidth, and MaxHeight come in:

// Force rendering onto a single line, ignoring margins, padding, and borders.
someStyle.Inline(true).Render("yadda yadda")

// Also limit rendering to five cells
someStyle.Inline(true).MaxWidth(5).Render("yadda yadda")

// Limit rendering to a 5x5 cell block
someStyle.MaxWidth(5).MaxHeight(5).Render("yadda yadda")

Tabs

The tab character (\t) is rendered differently in different terminals (often as 8 spaces, sometimes 4). Because of this inconsistency, Lip Gloss converts tabs to 4 spaces at render time. This behavior can be changed on a per-style basis, however:

style := lipgloss.NewStyle() // tabs will render as 4 spaces, the default
style = style.TabWidth(2)    // render tabs as 2 spaces
style = style.TabWidth(0)    // remove tabs entirely
style = style.TabWidth(lipgloss.NoTabConversion) // leave tabs intact

Wrapping

The Wrap function wraps text while preserving ANSI styles and hyperlinks across line boundaries:

wrapped := lipgloss.Wrap(styledText, 40, " ")

Rendering

Generally, you just call the Render(string...) method on a lipgloss.Style:

style := lipgloss.NewStyle().Bold(true).SetString("Hello,")
lipgloss.Println(style.Render("kitty.")) // Hello, kitty.
lipgloss.Println(style.Render("puppy.")) // Hello, puppy.

But you could also use the Stringer interface:

var style = lipgloss.NewStyle().SetString("你好，猫咪。").Bold(true)
lipgloss.Println(style) // 你好，猫咪。

Utilities

In addition to pure styling, Lip Gloss also ships with some utilities to help assemble your layouts.

Compositing

Lip Gloss includes a powerful, cell-based compositor for rendering layered content:

// Create some layers.
a := lipgloss.NewLayer(pickles).X(4).Y(2).Z(1)
b := lipgloss.NewLayer(bitterMelon).X(22).Y(1)
c := lipgloss.NewLayer(sriracha).X(11).Y(7)

// Composite 'em and render.
output := compositor.Compose(a, b, c).Render()

For a more thorough example, see the canvas example. For reference, including how to detect mouse clicks on layers, see [the docs][docs].

Joining Paragraphs

Horizontally and vertically joining paragraphs is a cinch.

// 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)

// Horizontally join three paragraphs, with the shorter ones aligning 20%
// from the top of the tallest
lipgloss.JoinHorizontal(0.2, paragraphA, paragraphB, paragraphC)

Measuring Width and Height

Sometimes you’ll want to know the width and height of text blocks when building your layouts.

// Render a block of text.
var style = lipgloss.NewStyle().
    Width(40).
    Padding(2)
var block string = style.Render(someLongString)

// Get the actual, physical dimensions of the text block.
width := lipgloss.Width(block)
height := lipgloss.Height(block)

// Here's a shorthand function.
w, h := lipgloss.Size(block)

Blending Colors

You can blend colors in one or two dimensions for gradient effects:

// 1-dimentinoal gradient
colors := lipgloss.Blend1D(10, lipgloss.Color("#FF0000"), lipgloss.Color("#0000FF"))

// 2-dimensional gradient with rotation
colors := lipgloss.Blend2D(80, 24, 45.0, color1, color2, color3)

Placing Text in Whitespace

Sometimes you’ll simply want to place a block of text in whitespace. This is a lightweight alternative to compositing.

// Center a paragraph horizontally in a space 80 cells wide. The height of
// the block returned will be as tall as the input paragraph.
block := lipgloss.PlaceHorizontal(80, lipgloss.Center, fancyStyledParagraph)

// Place a paragraph at the bottom of a space 30 cells tall. The width of
// the text block returned will be as wide as the input paragraph.
block := lipgloss.PlaceVertical(30, lipgloss.Bottom, fancyStyledParagraph)

// Place a paragraph in the bottom right corner of a 30x80 cell space.
block := lipgloss.Place(30, 80, lipgloss.Right, lipgloss.Bottom, fancyStyledParagraph)

You can also style the whitespace. For details, see [the docs][docs].

Rendering Tables

Lip Gloss ships with a table rendering sub-package.

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

Define some rows of data.

rows := [][]string{
    {"Chinese", "您好", "你好"},
    {"Japanese", "こんにちは", "やあ"},
    {"Arabic", "أهلين", "أهلا"},
    {"Russian", "Здравствуйте", "Привет"},
    {"Spanish", "Hola", "¿Qué tal?"},
}

Use the table package to style and render the table.

```go var ( purple = lipgloss.Color("99") gray = lipgloss.Color("245") lightGray = lipgloss.Color("241")

headerStyle  = lipgloss.NewStyle().Foreground(purple).Bold(true).Align(lipgloss.Center)
cellStyle    = lipgloss.NewStyle().Padding(0, 1).Width(14)
oddRowSt