Using Ansi

The Ansi module provides terminal styling — colors, backgrounds, and text effects like bold and underline. It works through the annotation system, attaching AnsiStyle data to boxes that renderers convert into ANSI escape sequences.

Text Colors

import * as Box from "effect-boxes/Box"
import * as Ansi from "effect-boxes/Ansi"
import { pipe } from "effect"
 
const red = pipe(Box.text("Red text"), Box.annotate(Ansi.red))
const green = pipe(Box.text("Green text"), Box.annotate(Ansi.green))
const blue = pipe(Box.text("Blue text"), Box.annotate(Ansi.blue))

Red text
Green text
Blue text
Yellow text
Magenta text
Cyan text

Available standard colors: black, red, green, yellow, blue, magenta, cyan, white. Each also has a bright variant: brightRed, brightGreen, etc.

Background Colors

const warning = pipe(
  Box.text(" Warning "),
  Box.annotate(Ansi.combine(Ansi.black, Ansi.bgYellow))
)
 
const error = pipe(
  Box.text(" Error   "),
  Box.annotate(Ansi.combine(Ansi.white, Ansi.bgRed))
)

 Warning 
 Error   
 Info

Background colors follow the same naming: bgBlack, bgRed, bgGreen, bgYellow, bgBlue, bgMagenta, bgCyan, bgWhite, plus bright variants.

Text Effects

const bold = pipe(Box.text("Bold text"), Box.annotate(Ansi.bold))
const dim = pipe(Box.text("Dim text"), Box.annotate(Ansi.dim))
const italic = pipe(Box.text("Italic text"), Box.annotate(Ansi.italic))
const underlined = pipe(Box.text("Underlined text"), Box.annotate(Ansi.underlined))
const strikethrough = pipe(Box.text("Strikethrough text"), Box.annotate(Ansi.strikethrough))

Bold text
Dim text
Italic text
Underlined text
Strikethrough text

Combining Styles

Use Ansi.combine to merge multiple styles into one annotation. Conflicts resolve with a last-wins strategy:

const critical = pipe(
  Box.text(" CRITICAL "),
  Box.annotate(Ansi.combine(Ansi.bold, Ansi.white, Ansi.bgRed))
)
 
const success = pipe(
  Box.text(" SUCCESS  "),
  Box.annotate(Ansi.combine(Ansi.bold, Ansi.white, Ansi.bgGreen))
)
 
const pending = pipe(
  Box.text(" PENDING  "),
  Box.annotate(Ansi.combine(Ansi.bold, Ansi.underlined, Ansi.yellow))
)

 CRITICAL 
 SUCCESS  
 PENDING

Extended Colors

256-Color Palette

Use Ansi.color256(n) and Ansi.bgColor256(n) for the extended 256-color palette (0-255):

const purple = pipe(Box.text("Purple"), Box.annotate(Ansi.color256(129)))
const teal = pipe(Box.text("Teal"), Box.annotate(Ansi.bgColor256(30)))

True Color (RGB)

For full 24-bit color, use Ansi.colorRGB(r, g, b) and Ansi.bgColorRGB(r, g, b):

const orange = pipe(
  Box.text("Orange text"),
  Box.annotate(Ansi.colorRGB(255, 165, 0))
)
 
const custom = pipe(
  Box.text("Custom teal"),
  Box.annotate(Ansi.colorRGB(0, 200, 180))
)

Orange text
Custom teal
 Gradient background

Hex Colors

Shorthand for RGB using hex strings:

const hexFg = pipe(Box.text("Hex foreground"), Box.annotate(Ansi.colorHex("#ff6600")))
const hexBg = pipe(
  Box.text(" Hex background "),
  Box.annotate(Ansi.combine(Ansi.white, Ansi.bgColorHex("#333333")))
)

Hex foreground
 Hex background

Rendering

ANSI annotations are only visible when rendered with renderPrettySync or the AnsiRendererLive layer. Plain rendering strips all styling:

const styled = pipe(Box.text("Hello"), Box.annotate(Ansi.red))
 
Box.renderPrettySync(styled) // "\x1b[31mHello\x1b[0m\n"
Box.renderPlainSync(styled)  // "Hello\n"

See the Rendering guide for more on renderer selection.