Guide · Open source

How to use Lip Gloss: styles, colors and borders in Go

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Lip Gloss is an MIT-licensed Go library for defining styles for text in a terminal: colors, bold or underline, padding, margins, alignment and borders. It uses a CSS-like, declarative style model and is built with terminal user interfaces (TUIs) in mind. This guide shows how to install it, build a style, and apply colors, layout and borders so you can print styled output from your own Go program.

Lip Glosscharmbracelet/lipgloss · ★ 12k · MIT Install options & downloads

Quick start

1Install the package. Run go get charm.land/lipgloss/v2 in your Go project.
2Import it. Add import "charm.land/lipgloss/v2" to the file where you style output.
3Create a style. Call lipgloss.NewStyle() and chain rules such as Bold, Foreground and Width.
4Render text. Call style.Render with your string to apply the style.
5Print the result. Use lipgloss.Println or lipgloss.Sprint so colors are downsampled to what the terminal supports.
6Add layout and borders. Use Padding, Margin, Align and Border to shape the block.

Install Lip Gloss

Lip Gloss is a Go package, so you need Go installed. Add the library to your project with the command from the README. The import path is charm.land/lipgloss/v2.

go get charm.land/lipgloss/v2

Create a style and print it

A style is created with lipgloss.NewStyle(). You chain rules onto it, then call Render on a string to apply the style. To print the result, use lipgloss.Println, which also handles color downsampling for you.

Bold, Foreground and Background set text appearance.
PaddingTop, PaddingLeft and Width set block layout.
Print with lipgloss.Println(style.Render(...)).

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

Choose colors

Lip Gloss supports ANSI 16 colors (4-bit), ANSI 256 colors (8-bit) and True Color (24-bit), plus a 1-bit ASCII profile that is black and white only. You can pass a color as a number string for ANSI colors or a hex string for True Color. Named constants exist for the 16 standard ANSI colors.

If some users have terminals without Truecolor, or output such as logs does not support color, Lip Gloss automatically downsamples colors to the best available profile. With Bubble Tea nothing extra is needed. Standalone, use lipgloss.Println or lipgloss.Sprint and their variants.

lipgloss.Color("5") is magenta in the ANSI 16 set.
lipgloss.Color("201") is hot pink in the ANSI 256 set.
lipgloss.Color("#04B575") is a green in True Color.
Utilities include Darken, Lighten, Complementary and Alpha.

c := lipgloss.Color("#EB4268")
dark := lipgloss.Darken(c, 0.5)
light := lipgloss.Lighten(c, 0.35)
green := lipgloss.Complementary(c)
withAlpha := lipgloss.Alpha(c, 0.2)

Add text formatting and hyperlinks

Inline options include Bold, Italic, Faint, Blink, Strikethrough, Underline and Reverse. Underlines can take a style and color through UnderlineStyle and UnderlineColor. Styles can also render clickable hyperlinks in supporting terminals; in unsupported terminals the link simply does not render.

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

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

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

Set padding, margins and alignment

Padding and margins can be set per side or with a CSS-style shorthand: one value for all sides, two for vertical and horizontal, or four for top, right, bottom and left in clockwise order. Padding and margin fill characters can be changed with PaddingChar and MarginChar. Text can be aligned left, right or center, and Width and Height set minimum dimensions.

Padding(2) sets 2 cells on all sides.
Margin(2, 4) sets 2 cells top and bottom, 4 left and right.
Align(lipgloss.Center) centers paragraphs of text.

lipgloss.NewStyle().Padding(1, 4, 2)

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

Draw borders

Set a border with BorderStyle and a color with BorderForeground. Built-in borders include NormalBorder, RoundedBorder, ThickBorder and DoubleBorder. The Border shorthand takes a border and up to four true/false flags for which sides to draw. You can also define a custom Border from your own characters, and pass multiple colors to BorderForegroundBlend for a gradient.

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

What people use it for

Styling headings and status text in a Go command-line program.
Building the visual layout of a Bubble Tea terminal user interface.
Drawing bordered boxes around sections of terminal output.
Printing aligned, colored output that still works in plain logs.

Frequently asked questions

How do I install lipgloss?

Install it with go get charm.land/lipgloss/v2 in a Go project. You need Go installed first, since Lip Gloss is a Go package.

Is lipgloss free to use?

Lip Gloss is released under the MIT licence, as stated in the project's listing. The source does not discuss commercial terms beyond that licence.

Can I use lipgloss outside Go?

No. Lip Gloss is written for Go, so it is only useful in Go projects. Non-Go projects need a library in their own language.

Does lipgloss work with Bubble Tea?

Yes. The README says that with Bubble Tea there is nothing extra to do for color downsampling, and that Lip Gloss is built with TUIs in mind.

Do I need to know CSS to use lipgloss?

No, but the README notes that people familiar with CSS will feel at home, since its margin and padding shorthand follows the CSS format.

What are good alternatives to lipgloss?

The listing names tcell, termenv, tview and gocui as comparable projects. Lip Gloss focuses on declarative styling, while these cover other terminal needs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use Lip Gloss if you write Go command-line programs or terminal user interfaces and want CSS-like styling for colors, layout and borders. Pick something else if your project is not in Go, if you only need plain text output, or if you want an end-user application rather than a library.

Install options & downloads