Lip Gloss v2

The color system has moved from string-based types to standard library integration:

• lipgloss.Color(string) color.Color: This is now a function that returns an image/color.Color. It accepts hex strings or ANSI color indices.
• ANSIColor: Now an alias for ansi.IndexedColor.
• Named ANSI Constants: v2 exports constants for the 16 basic colors: lipgloss.Black, lipgloss.Red, lipgloss.Green, lipgloss.Yellow, lipgloss.Blue, lipgloss.Magenta, lipgloss.Cyan, lipgloss.White, and their Bright variants.
• Adaptive Colors: Instead of the AdaptiveColor type, it is recommended to use the lipgloss.LightDark(hasDark bool) helper, which returns a function to pick colors based on background detection.

// v2 usage
var c color.Color = lipgloss.Color("#ff00ff")

// Using LightDark for adaptive colors
hasDark := lipgloss.HasDarkBackground(os.Stdin, os.Stdout)
lightDark := lipgloss.LightDark(hasDark)
color := lightDark(lipgloss.Color("#0000ff"), lipgloss.Color("#000099"))

Unlike v1, v2 does not detect background color globally. You must explicitly provide the input and output streams to lipgloss.HasDarkBackground(in, out).

Standalone usage:

1. Detect background: hasDark := lipgloss.HasDarkBackground(os.Stdin, os.Stdout).
2. Create a picker: lightDark := lipgloss.LightDark(hasDark).
3. Apply colors: fg := lightDark(lightColor, darkColor).

Bubble Tea usage: To react to terminal theme changes, request the background color in your model's Init() method using tea.RequestBackgroundColor. In your Update() loop, listen for tea.BackgroundColorMsg to update your styles.

// Bubble Tea pattern
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
}

You can render different colors at runtime based on whether the user's terminal has a light or dark background.

Standalone Usage

Use lipgloss.HasDarkBackground(stdin, stdout) to detect the background type, then use lipgloss.LightDark(hasDarkBG) to create a helper function. This helper function accepts two colors: the first for light backgrounds and the second for dark backgrounds.

Integration with Bubble Tea

In a Bubble Tea application, do not query the background manually in Init. Instead:

1. Return tea.RequestBackgroundColor from your Init() method.
2. Listen for the tea.BackgroundColorMsg in your Update() loop.
3. Use msg.IsDark() to determine the background state and update your styles accordingly.

// Standalone
hasDarkBG := lipgloss.HasDarkBackground(os.Stdin, os.Stderr)
lightDark := lipgloss.LightDark(hasDarkBG)

// Returns light color if background is light, dark color if background is dark
myColor := lightDark(lipgloss.Color("#C5ADF9"), lipgloss.Color("#864EFF"))

style := lipgloss.NewStyle().Foreground(myColor)

When migrating from Lip Gloss v1 to v2, several core behaviors and API patterns have changed. Key changes include a new module path, changes to how adaptive colors are handled, and a shift in how terminal background detection and output rendering work.

Key Migration Summary

To migrate from v1 to v2, follow these primary steps:

1. Update Import Paths: Change github.com/charmbracelet/lipgloss to charm.land/lipgloss/v2 and update subpackages (e.g., github.com/charmbracelet/lipgloss/table becomes charm.land/lipgloss/v2/table).
2. Install v2: Run go get charm.land/lipgloss/v2.
3. Update Color Usage: lipgloss.Color is now a function returning image/color.Color instead of a string type. Replace lipgloss.TerminalColor with color.Color from the image/color package.
4. Handle Color Downsampling: In v2, Style.Render() always emits full-fidelity ANSI. You must use Lip Gloss writer functions (like lipgloss.Println) for automatic downsampling, or rely on Bubble Tea v2 which handles this internally.
5. Remove Renderer Logic: The Renderer type and associated functions (like DefaultRenderer) are removed. Style is now a plain value type. Use lipgloss.NewStyle() instead of renderer-based style creation.