Styling with Lipgloss

TUI4J includes a port of Lip Gloss, Charm’s terminal styling library. It provides a fluent Java API for colors, borders, padding, margins, alignment, and multi-column layout — all resolved to ANSI escape sequences at render time.

Creating a style

Every style starts from Style.newStyle(). Methods return this, so the entire style is configured in a single chain and applied by calling render(...).

import com.williamcallahan.tui4j.compat.lipgloss.Style;
import com.williamcallahan.tui4j.compat.lipgloss.color.Color;

Style highlight = Style.newStyle()
    .bold(true)
    .foreground(Color.color("205")); // ANSI-256 hot pink

// Render to a terminal string:
String output = highlight.render("Selected item");

render() accepts one or more strings. Multiple strings are joined with a space before styling is applied.

Style badge = Style.newStyle().foreground(Color.color("#FFFDF5"));
String text = badge.render("[•]", "Espresso"); // "[•] Espresso" with styling

Colors

All colors implement TerminalColor and can be passed to .foreground() and .background().

ANSI-256 and hex colors

Color.color(String) accepts ANSI-256 index strings ("0"–"255") and hex color strings ("#FF5F87").

import com.williamcallahan.tui4j.compat.lipgloss.color.Color;

// ANSI-256 index
Style.newStyle().foreground(Color.color("205"));  // hot pink

// Hex color
Style.newStyle()
    .foreground(Color.color("#FFFDF5"))
    .background(Color.color("#FF5F87"));

Adaptive colors

AdaptiveColor selects between a light and dark variant depending on whether the terminal has a dark background.

import com.williamcallahan.tui4j.compat.lipgloss.color.AdaptiveColor;

Style statusBar = Style.newStyle()
    .foreground(new AdaptiveColor("#343433", "#C1C6B2"))
    .background(new AdaptiveColor("#D9DCCF", "#353533"));

Use AdaptiveColor for any color that should look good in both light and dark terminal themes.

Text attributes

Style.newStyle()
    .bold(true)
    .italic(true)
    .underline(true)
    .faint(true)    // dim/faint
    .blink(true)
    .reverse(true)  // swap foreground and background
    .inline(true);  // collapse newlines — render on a single line

Width and height

Set explicit dimensions to constrain content. Text is wrapped to fit the specified width.

Style.newStyle()
    .width(40)   // cells
    .height(10)  // lines
    .render("Content that wraps at 40 columns");

Cap dimensions without hard-wrapping using maxWidth and maxHeight:

Style.newStyle()
    .maxWidth(80)
    .maxHeight(5)
    .ellipsis("…");

Padding

Padding uses CSS-like shorthand: one value applies to all sides, two values apply to vertical then horizontal, four values apply top → right → bottom → left.

Style.newStyle().padding(1);          // 1 on all sides
Style.newStyle().padding(1, 2);       // 1 top/bottom, 2 left/right
Style.newStyle().padding(1, 2, 1, 2); // top, right, bottom, left

// Or set each side individually:
Style.newStyle()
    .paddingTop(1)
    .paddingRight(2)
    .paddingBottom(1)
    .paddingLeft(2);

Margins

Margins work identically to padding but add space outside any border.

Style.newStyle().margin(1);
Style.newStyle().margin(0, 1);
Style.newStyle().marginTop(1).marginLeft(2);

// Margin background color (fills the margin area):
Style.newStyle()
    .margin(1)
    .marginBackgroundColor(Color.color("#353533"));

Borders

Choose a border style from Borders and apply it with .border().

import com.williamcallahan.tui4j.compat.lipgloss.Borders;

// Full border on all sides:
Style box = Style.newStyle()
    .border(Borders.normalBorder())
    .padding(0, 1);

System.out.println(box.render("Hello"));

Available border styles:

Method	Appearance
`Borders.normalBorder()`	`─ │ ┌ ┐ └ ┘`
`Borders.roundedBorder()`	`─ │ ╭ ╮ ╰ ╯`
`Borders.thickBorder()`	`━ ┃ ┏ ┓ ┗ ┛`
`Borders.doubleBorder()`	`═ ║ ╔ ╗ ╚ ╝`
`Borders.blockBorder()`	Block characters
`Borders.asciiBorder()`	`-	+ + + +`
`Borders.hiddenBorder()`	Invisible (preserves spacing)
`Borders.noBorder()`	No border

Apply borders selectively with boolean side flags:

// Top and bottom only (pass top, right, bottom, left):
Style.newStyle().border(Borders.normalBorder(), true, false, true, false);

Color the border independently of the content:

Style.newStyle()
    .border(Borders.roundedBorder())
    .borderForeground(Color.color("#A550DF")); // all sides purple

Alignment

import com.williamcallahan.tui4j.compat.lipgloss.Position;

// Horizontal alignment (Left, Center, Right):
Style.newStyle()
    .width(40)
    .align(Position.Center);

// Vertical alignment (Top, Center, Bottom):
Style.newStyle()
    .height(10)
    .alignVertical(Position.Center);

// Both at once (horizontal first, then vertical):
Style.newStyle()
    .width(40).height(10)
    .align(Position.Center, Position.Center);

Layout: joining styled blocks

Join combines multiple rendered strings side-by-side or stacked. Pass a Position to control alignment along the cross-axis.

import com.williamcallahan.tui4j.compat.lipgloss.Join;
import com.williamcallahan.tui4j.compat.lipgloss.Position;

String left  = leftPanelStyle.render(leftContent);
String right = rightPanelStyle.render(rightContent);

// Place side by side, aligned at the top:
String row = Join.joinHorizontal(Position.Top, left, right);

// Stack vertically, centered horizontally:
String column = Join.joinVertical(Position.Center, header, body, footer);

Status bar example

This pattern, taken from the Lipgloss examples, builds a multi-segment status bar using Join.joinHorizontal:

import com.williamcallahan.tui4j.compat.lipgloss.*;
import com.williamcallahan.tui4j.compat.lipgloss.color.*;

Style statusNugget = Style.newStyle()
    .foreground(Color.color("#FFFDF5"))
    .padding(0, 1);

Style barStyle = Style.newStyle()
    .foreground(new AdaptiveColor("#343433", "#C1C6B2"))
    .background(new AdaptiveColor("#D9DCCF", "#353533"));

Style statusStyle = barStyle.copy()
    .foreground(Color.color("#FFFDF5"))
    .background(Color.color("#FF5F87"))
    .padding(0, 1);

Style encodingStyle = statusNugget
    .background(Color.color("#A550DF"))
    .alignHorizontal(Position.Right);

String statusKey = statusStyle.render("STATUS");
String encoding  = encodingStyle.render("UTF-8");

String statusVal = barStyle.copy()
    .width(80 - Size.width(statusKey) - Size.width(encoding))
    .render("Ready");

String bar = Join.joinHorizontal(Position.Top, statusKey, statusVal, encoding);
System.out.println(barStyle.width(80).render(bar));

Copying and inheriting styles

Use .copy() to create an independent clone of a style (safe for modification without affecting the original):

Style base = Style.newStyle().padding(0, 1).foreground(Color.color("#FFFDF5"));

Style active   = base.copy().background(Color.color("#FF5F87"));
Style inactive = base.copy().faint(true);

Use .inherit(other) to fill in only the properties that have not been explicitly set on the receiver:

Style child = Style.newStyle()
    .bold(true)
    .inherit(parentStyle); // picks up parent's foreground, padding, etc.

The Elm Architecture

Model, Update, and View pattern.

Messages and commands

Events and side effects in TUI4J.

Get Started

Core Concepts

Components

Guides

Compatibility

Styling with Lipgloss

Creating a style

Colors

ANSI-256 and hex colors

Adaptive colors

Text attributes

Width and height

Padding

Margins

Borders

Alignment

Layout: joining styled blocks

Status bar example

Copying and inheriting styles

The Elm Architecture

Messages and commands

​Creating a style

​Colors

​ANSI-256 and hex colors

​Adaptive colors

​Text attributes

​Width and height

​Padding

​Margins

​Borders

​Alignment

​Layout: joining styled blocks

​Status bar example

​Copying and inheriting styles

The Elm Architecture

Messages and commands

Creating a style

Colors

ANSI-256 and hex colors

Adaptive colors

Text attributes

Width and height

Padding

Margins

Borders

Alignment

Layout: joining styled blocks

Status bar example

Copying and inheriting styles