Lip Gloss
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.
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.
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.
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.
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) oddRowStyle = cellStyle.Foreground(gray) evenRowStyle = cellStyle.Foreground(lightGray) ) t := table.New(). Border(lipgloss.NormalBorder()). BorderStyle(lipgloss.NewStyle().Foreground(purple)). StyleFunc(func(row, col int) lipgloss.Style { switch { case row == table.HeaderRow: return headerStyle case row%2 == 0: return evenRowStyle default: return oddRowStyle } }). Headers("LANGUAGE", "FORMAL", "INFORMAL"). Rows(rows...) // You can also add tables row-by-row t.Row("English", "You look absolutely fabulous.", "How's it going?")
Print the table.
lipgloss.Println(t)
Table Borders
There are helpers to generate tables in markdown or ASCII style:
Markdown Table
table.New().Border(lipgloss.MarkdownBorder()).BorderTop(false).BorderBottom(false)
| LANGUAGE | FORMAL | INFORMAL |
|----------|--------------|-----------|
| Chinese | Nǐn hǎo | Nǐ hǎo |
| French | Bonjour | Salut |
| Russian | Zdravstvuyte | Privet |
| Spanish | Hola | ¿Qué tal? |
ASCII Table
table.New().Border(lipgloss.ASCIIBorder())
+----------+--------------+-----------+
| LANGUAGE | FORMAL | INFORMAL |
+----------+--------------+-----------+
| Chinese | Nǐn hǎo | Nǐ hǎo |
| French | Bonjour | Salut |
| Russian | Zdravstvuyte | Privet |
| Spanish | Hola | ¿Qué tal? |
+----------+--------------+-----------+
For more on tables see the docs and examples.
Rendering Lists
Lip Gloss ships with a list rendering sub-package.
import "charm.land/lipgloss/v2/list"
Define a new list.
l := list.New("A", "B", "C")
Print the list.
lipgloss.Println(l) // • A // • B // • C
Lists have the ability to nest.
l := list.New( "A", list.New("Artichoke"), "B", list.New("Baking Flour", "Bananas", "Barley", "Bean Sprouts"), "C", list.New("Cashew Apple", "Cashews", "Coconut Milk", "Curry Paste", "Currywurst"), "D", list.New("Dill", "Dragonfruit", "Dried Shrimp"), "E", list.New("Eggs"), "F", list.New("Fish Cake", "Furikake"), "J", list.New("Jicama"), "K", list.New("Kohlrabi"), "L", list.New("Leeks", "Lentils", "Licorice Root"), )
Print the list.
lipgloss.Println(l)
Lists can be customized via their enumeration function as well as using
lipgloss.Styles.
enumeratorStyle := lipgloss.NewStyle().Foreground(lipgloss.Color("99")).MarginRight(1) itemStyle := lipgloss.NewStyle().Foreground(lipgloss.Color("212")).MarginRight(1) l := list.New( "Glossier", "Claire's Boutique", "Nyx", "Mac", "Milk", ). Enumerator(list.Roman). EnumeratorStyle(enumeratorStyle). ItemStyle(itemStyle)
Print the list.
In addition to the predefined enumerators (Arabic, Alphabet, Roman, Bullet, Tree),
you may also define your own custom enumerator:
l := list.New("Duck", "Duck", "Duck", "Duck", "Goose", "Duck", "Duck") func DuckDuckGooseEnumerator(l list.Items, i int) string { if l.At(i).Value() == "Goose" { return "Honk →" } return "" } l = l.Enumerator(DuckDuckGooseEnumerator)
Print the list:
If you need, you can also build lists incrementally:
l := list.New() for i := 0; i < repeat; i++ { l.Item("Lip Gloss") }
Rendering Trees
Lip Gloss ships with a tree rendering sub-package.
import "charm.land/lipgloss/v2/tree"
Define a new tree.
t := tree.Root("."). Child("A", "B", "C")
Print the tree.
lipgloss.Println(t) // . // ├── A // ├── B // └── C
Trees have the ability to nest.
t := tree.Root("."). Child("macOS"). Child( tree.New(). Root("Linux"). Child("NixOS"). Child("Arch Linux (btw)"). Child("Void Linux"), ). Child( tree.New(). Root("BSD"). Child("FreeBSD"). Child("OpenBSD"), )
Print the tree.
lipgloss.Println(t)
Trees can be customized via their enumeration function as well as using
lipgloss.Styles.
enumeratorStyle := lipgloss.NewStyle().Foreground(lipgloss.Color("63")).MarginRight(1) rootStyle := lipgloss.NewStyle().Foreground(lipgloss.Color("35")) itemStyle := lipgloss.NewStyle().Foreground(lipgloss.Color("212")) t := tree. Root("⁜ Makeup"). Child( "Glossier", "Fenty Beauty", tree.New().Child( "Gloss Bomb Universal Lip Luminizer", "Hot Cheeks Velour Blushlighter", ), "Nyx", "Mac", "Milk", ). Enumerator(tree.RoundedEnumerator). EnumeratorStyle(enumeratorStyle). RootStyle(rootStyle). ItemStyle(itemStyle)
Print the tree.
The predefined enumerators for trees are DefaultEnumerator and RoundedEnumerator.
If you need, you can also build trees incrementally:
t := tree.New() for i := 0; i < repeat; i++ { t.Child("Lip Gloss") }
Advanced Color Usage
One of the most powerful features of Lip Gloss is the ability to render different colors at runtime depending on the user's terminal and environment, allowing you to present the best possible user experience.
This section shows you how to do exactly that.
Migrating from v1?
The compat package provides AdaptiveColor, CompleteColor, and
CompleteAdaptiveColor for a quicker migration from v1. These work by
looking at stdin and stdout on a global basis:
import "charm.land/lipgloss/v2/compat" color := compat.AdaptiveColor{ Light: lipgloss.Color("#f1f1f1"), Dark: lipgloss.Color("#cccccc"), }
Note that we don't recommend this for new code as it removes the purity from Lip Gloss, computationally speaking, as it removes transparency around when I/O happens, which could cause Lip Gloss to compete for resources (like stdin) with other tools.
Adaptive Colors
You can render different colors at runtime depending on whether the terminal has a light or dark background:
hasDarkBG := lipgloss.HasDarkBackground(os.Stdin, os.Stdout) lightDark := lipgloss.LightDark(hasDarkBG) myColor := lightDark(lipgloss.Color("#D7FFAE"), lipgloss.Color("#D75FEE"))
With Bubble Tea
In Bubble Tea, request the background color, listen for a
BackgroundColorMsg, and respond accordingly:
func (m model) Init() tea.Cmd { // First, send a Cmd to request the terminal background color. return tea.RequestBackgroundColor } func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) { switch msg := msg.(type) { case tea.BackgroundColorMsg: // Great, we have the background color. Now we can set up our styles // against the color. m.styles = newStyles(msg.IsDark()) return m, nil } } func newStyles(bgIsDark bool) styles { // A little ternary function that will return the appropriate color // based on the background color. lightDark := lipgloss.LightDark(bgIsDark) return styles{ myHotStyle: lipgloss.NewStyle().Foreground(lightDark( lipgloss.Color("#f1f1f1"), lipgloss.Color("#333333"), )), } }
Standalone
If you’re not using Bubble Tea you can perform the query manually:
// What's the background color? hasDarkBG := lipgloss.HasDarkBackground(os.Stdin, os.Stderr) // A helper function that will return the appropriate color based on the // background. lightDark := lipgloss.LightDark(hasDarkBG) // A couple colors with light and dark variants. thisColor := lightDark(lipgloss.Color("#C5ADF9"), lipgloss.Color("#864EFF")) thatColor := lightDark(lipgloss.Color("#37CD96"), lipgloss.Color("#22C78A")) a := lipgloss.NewStyle().Foreground(thisColor).Render("this") b := lipgloss.NewStyle().Foreground(thatColor).Render("that") // Render the appropriate colors at runtime: lipgloss.Fprintf(os.Stderr, "my fave colors are %s and %s", a, b)
Complete Colors
In some cases where you may want to specify exact values for each color profile
(ANSI 16, ANSI 156, and TrueColor). For these cases, use the Complete helper:
// You'll need the colorprofile package. import "github.com/charmbracelet/colorprofile" // Get the color profile. profile := colorprofile.Detect(os.Stdout, os.Environ()) // Create a function for rendering the appropriate color based on the profile. var completeColor := lipgloss.Complete(profile) // Now we'll choose the appropriate color at runtime. myColor := completeColor(ansiColor, ansi256Color, trueColor)
Color Downsampling
One of the best things about Lip Gloss is that it can automatically downsample colors to the best available profile, stripping colors (and ANSI) entirely when output is not a TTY.
If you’re using Lip Gloss with Bubble Tea there’s nothing to do here:
downsampling is built into Bubble Tea v2. If you’re not using Bubble Tea, use
the Lip Gloss writer functions, which are a drop-in replacement for the fmt
package:
s := lipgloss.NewStyle() .Foreground(lipgloss.Color("#EB4268")) .Render("Hello!") // Downsample if needed and print to stdout. lipgloss.Println(s) // Render to a variable. downsampled := lipgloss.Sprint(s) // Print to stderr. lipgloss.Fprint(os.Stderr, s)
The full set: Print, Println, Printf, Fprint, Fprintln, Fprintf,
Sprint, Sprintln, Sprintf.
Need more control? Check out Colorprofile, which Lip Gloss uses under the hood.
What about Bubble Tea?
Lip Gloss doesn’t replace Bubble Tea. Rather, it is an excellent Bubble Tea companion. It was designed to make assembling terminal user interface views as simple and fun as possible so that you can focus on building your application instead of concerning yourself with low-level layout details.
In simple terms, you can use Lip Gloss to help build your Bubble Tea views.
Rendering Markdown
For a more document-centric rendering solution with support for things like lists, tables, and syntax-highlighted code have a look at Glamour, the stylesheet-based Markdown renderer.
Contributing
See contributing.
Feedback
We’d love to hear your thoughts on this project. Feel free to drop us a note!
License
Part of Charm.
Charm热爱开源 • Charm loves open source