blipgloss

Blipgloss uses a declarative, chainable API to define terminal styles. You create a style using NewStyle(), apply various properties, and then call .Render(string) to get the styled output.

import { NewStyle } from 'blipgloss'

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

console.log(style.Render("Hello, bun."))

Install the package using bun add. Because it uses a binary, you must also mark it as a trusted dependency to ensure the correct binary is downloaded.

bun add blipgloss

bun pm trust blipgloss

The BlipglossColor type allows you to specify colors in multiple formats, providing compatibility across different terminal capabilities:

• String: A simple color string (e.g., hex code or name).
• AdaptiveColor: Provides different colors for light and dark terminal themes.
  • { Light: string; Dark: string; }
• CompleteColor: Provides specific colors for different terminal levels.
  • { True: string; ANSI256: string; ANSI: string; }
• CompleteAdaptiveColor: Combines adaptive themes with multiple color levels.
  • { Light: CompleteColor; Dark: CompleteColor; }

import { NewStyle, type BlipglossColor } from 'blipgloss';

const adaptive: BlipglossColor = {
  Light: { True: '#000000', ANSI256: '0', ANSI: '0' },
  Dark: { True: '#ffffff', ANSI256: '255', ANSI: '15' }
};

const style = NewStyle().Foreground(adaptive);

Use the following methods on a style instance to apply standard ANSI text formatting:

• .Bold(boolean)
• .Italic(boolean)
• `.Faint(boolean)
• `.Blink(boolean)
• `.Strikethrough(boolean)
• `.Underline(boolean)
• `.Reverse(boolean)

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

You can add borders to styles using .BorderStyle().

Border Styles

• Border.Normal: A standard rectangular border.
• Border.Rounded: A rounded border.
• Custom Border: Pass an object defining characters for Top, Bottom, Left, Right, TopLeft, TopRight, BottomLeft, and BottomRight.

Border Properties

• .BorderForeground(color)
• .BorderBackground(color)
• .BorderTop(boolean), .BorderLeft(boolean), etc., to enable specific sides.

import { NewStyle, Border } from 'blipgloss'

// Standard border
const style = NewStyle()
  .BorderStyle(Border.Normal)
  .BorderForeground("63")

// Custom border
const custom = NewStyle()
  .BorderStyle({
    Top: "._.:*:",
    Bottom: "._.:*:",
    Left: "|*",
    Right: "|*",
    TopLeft: "*",
    TopRight: "*",
    BottomLeft: "*",
    BottomRight: "*",
  })

Blipgloss supports CSS-like rules for spacing and alignment.

Padding and Margins

You can set individual sides (e.g., .PaddingTop(n)) or use shorthand syntax:

• .Padding(n): Applies n cells to all sides.
• .Margin(top, right): Applies n cells to top/bottom and m cells to left/right.
• .Padding(top, right, bottom): Applies specific values to three sides.
• .Margin(top, right, bottom, left): Applies specific values to all four sides (clockwise).

Alignment

Align text within a defined width using the Position enum:

• Position.Left
• Position.Right
• Position.Center

import { Position, NewStyle } from 'blipgloss'

// Alignment example
const style = NewStyle()
  .Width(24)
  .Align(Position.Center)

Copying Styles

To avoid mutating an existing style, use .Copy(). This performs a true, dereferenced copy of the underlying data structure.

Unsetting Rules

Every rule can be removed using an Unset method (e.g., .UnsetBold(), .UnsetBackground()).

Enforcing Constraints

Use these methods to ensure components respect UI boundaries:

• .Inline(boolean): Forces rendering onto a single line, ignoring margins, padding, and borders.
• .MaxWidth(n): Limits the width to n cells.
• .MaxHeight(n): Limits the height to n cells.

// Copying
const wildStyle = style.Copy().Blink(true)

// Enforcing
someStyle.Inline(true).MaxWidth(5).Render("text")

Use SetIntValue to update style properties that require an integer, such as Padding or Margin.

Parameters:

• fieldPtr: The unique ID of the style.
• keyPtr: The name of the method to call (e.g., "Padding").
• value: The integer value.

Note: This operation updates the style in-place within the internal styleMap.

// Set padding to 2
SetIntValue(styleId, "Padding", 2)

Use HasDarkBackground() to detect if the user's terminal is currently using a dark theme. This is useful for selecting appropriate AdaptiveColor values.

import { HasDarkBackground } from 'blipgloss';

if (HasDarkBackground()) {
  console.log("User is in dark mode");
}

Use NewStyle to create a new lipgloss.Style instance. It returns a unique string ID (a *C.char) that you must use as a key for all subsequent operations on that style (e.g., setting colors, borders, or rendering text).

// Returns a unique ID for a new style
styleId = NewStyle()