Ansi overview

ANSI terminal styling and colored box rendering.

Provides a complete set of ANSI escape code utilities for styling text in terminal environments. Includes foreground/background colors (standard, bright, 256-color, and RGB), text attributes (bold, italic, underline, etc.), and a renderer that converts annotated boxes into ANSI-escaped strings.

Common tasks

  • Style text: bold, italic, underlined
  • Foreground colors: red, green, blue, colorRGB
  • Background colors: bgRed, bgGreen, bgColorHex
  • Combine styles: combine
  • Render: renderAnnotatedBox

Gotchas

  • Styles are combined additively — later attributes override earlier ones of the same kind
  • truncatePreservingAnsi handles width-truncation without breaking escape sequences

combinators

combine

Combines multiple ANSI style annotations into a single annotation.

Merges multiple ANSI styling annotations using a last-wins strategy for conflicting attributes. This allows you to layer styles like combining color with formatting.

Signature

export declare const combine: (...annotations: AnsiAnnotation[]) => AnsiAnnotation

Example

import * as Box from "effect-boxes/Box"
import * as Ansi from "effect-boxes/Ansi"
 
const styledText = Box.text("Important Warning").pipe(Box.annotate(Ansi.combine(Ansi.red, Ansi.bold, Ansi.underlined)))
console.log(Box.renderPrettySync(styledText))
// Outputs red, bold, underlined text

constructors

bgBlack

Black background color.

Signature

export declare const bgBlack: AnsiAnnotation

bgBlue

Blue background color.

Signature

export declare const bgBlue: AnsiAnnotation

bgBrightBlack

Bright black (gray) background color.

Signature

export declare const bgBrightBlack: AnsiAnnotation

bgBrightBlue

Bright blue background color.

Signature

export declare const bgBrightBlue: AnsiAnnotation

bgBrightCyan

Bright cyan background color.

Signature

export declare const bgBrightCyan: AnsiAnnotation

bgBrightGreen

Bright green background color.

Signature

export declare const bgBrightGreen: AnsiAnnotation

bgBrightMagenta

Bright magenta background color.

Signature

export declare const bgBrightMagenta: AnsiAnnotation

bgBrightRed

Bright red background color.

Signature

export declare const bgBrightRed: AnsiAnnotation

bgBrightWhite

Bright white background color.

Signature

export declare const bgBrightWhite: AnsiAnnotation

bgBrightYellow

Bright yellow background color.

Signature

export declare const bgBrightYellow: AnsiAnnotation

bgColor256

Creates a background color using 256-color palette.

Signature

export declare const bgColor256: (n: number) => AnsiAnnotation

Example

import * as Box from "effect-boxes/Box"
import * as Ansi from "effect-boxes/Ansi"
 
const highlighted = Box.text("Highlighted text").pipe(
  Box.annotate(Ansi.bgColor256(226)) // Bright yellow background
)

bgColorHex

Creates a background color from a hex color string.

Accepts hex strings with or without a leading #, in 3-digit or 6-digit format (e.g. "#ff00ff", "ff00ff", "#f0f", "f0f").

Signature

export declare const bgColorHex: (hex: string) => AnsiAnnotation

Example

import * as Box from "effect-boxes/Box"
import * as Ansi from "effect-boxes/Ansi"
 
const warmBg = Ansi.bgColorHex("#FFE4B5")
const styledText = Box.text("Warm background").pipe(Box.annotate(warmBg))
console.log(Box.renderPrettySync(styledText))

bgColorRGB

Creates a background color using RGB values.

Signature

export declare const bgColorRGB: (r: number, g: number, b: number) => AnsiAnnotation

Example

import * as Box from "effect-boxes/Box"
import * as Ansi from "effect-boxes/Ansi"
 
const softBackground = Ansi.bgColorRGB(240, 240, 240)
const subtleText = Box.text("Soft background").pipe(Box.annotate(softBackground))

bgCyan

Cyan background color.

Signature

export declare const bgCyan: AnsiAnnotation

bgDefault

Default background color (terminal default).

Signature

export declare const bgDefault: AnsiAnnotation

bgGreen

Green background color.

Signature

export declare const bgGreen: AnsiAnnotation

bgMagenta

Magenta background color.

Signature

export declare const bgMagenta: AnsiAnnotation

bgRed

Red background color.

Signature

export declare const bgRed: AnsiAnnotation

bgWhite

White background color.

Signature

export declare const bgWhite: AnsiAnnotation

bgYellow

Yellow background color.

Signature

export declare const bgYellow: AnsiAnnotation

black

Standard black foreground color.

Signature

export declare const black: AnsiAnnotation

blink

Blinking text formatting.

Makes text blink (if supported by terminal).

Signature

export declare const blink: AnsiAnnotation

blue

Standard blue foreground color.

Signature

export declare const blue: AnsiAnnotation

bold

Bold text formatting.

Makes text appear with increased weight/intensity.

Signature

export declare const bold: AnsiAnnotation

brightBlack

Bright black (gray) foreground color.

Signature

export declare const brightBlack: AnsiAnnotation

brightBlue

Bright blue foreground color.

Signature

export declare const brightBlue: AnsiAnnotation

brightCyan

Bright cyan foreground color.

Signature

export declare const brightCyan: AnsiAnnotation

brightGreen

Bright green foreground color.

Signature

export declare const brightGreen: AnsiAnnotation

brightMagenta

Bright magenta foreground color.

Signature

export declare const brightMagenta: AnsiAnnotation

brightRed

Bright red foreground color.

Signature

export declare const brightRed: AnsiAnnotation

brightWhite

Bright white foreground color.

Signature

export declare const brightWhite: AnsiAnnotation

brightYellow

Bright yellow foreground color.

Signature

export declare const brightYellow: AnsiAnnotation

color256

Creates a foreground color using 256-color palette.

Uses the extended 256-color ANSI palette for more color options beyond the basic 8 colors.

Signature

export declare const color256: (n: number) => AnsiAnnotation

Example

import * as Box from "effect-boxes/Box"
import * as Ansi from "effect-boxes/Ansi"
 
const brightOrange = Ansi.color256(208)
const coloredText = Box.text("Bright orange text").pipe(Box.annotate(brightOrange))

colorHex

Creates a foreground color from a hex color string.

Accepts hex strings with or without a leading #, in 3-digit or 6-digit format (e.g. "#ff00ff", "ff00ff", "#f0f", "f0f").

Signature

export declare const colorHex: (hex: string) => AnsiAnnotation

Example

import * as Box from "effect-boxes/Box"
import * as Ansi from "effect-boxes/Ansi"
 
const coral = Ansi.colorHex("#FF6B6B")
const styledText = Box.text("Coral text").pipe(Box.annotate(coral))
console.log(Box.renderPrettySync(styledText))

colorRGB

Creates a foreground color using RGB values.

Provides true color support with full RGB specification. Each component should be between 0-255.

Signature

export declare const colorRGB: (r: number, g: number, b: number) => AnsiAnnotation

Example

import * as Box from "effect-boxes/Box"
import * as Ansi from "effect-boxes/Ansi"
 
const customPurple = Ansi.colorRGB(128, 0, 128)
const styledText = Box.text("Custom purple").pipe(Box.annotate(customPurple))
console.log(Box.renderPrettySync(styledText))

cyan

Standard cyan foreground color.

Signature

export declare const cyan: AnsiAnnotation

dim

Dim text formatting.

Makes text appear with reduced intensity.

Signature

export declare const dim: AnsiAnnotation

fgDefault

Default foreground color (terminal default).

Signature

export declare const fgDefault: AnsiAnnotation

green

Standard green foreground color.

Signature

export declare const green: AnsiAnnotation

hidden

Hidden text formatting.

Makes text invisible (useful for passwords).

Signature

export declare const hidden: AnsiAnnotation

inverse

Inverse text formatting.

Swaps foreground and background colors.

Signature

export declare const inverse: AnsiAnnotation

italic

Italic text formatting.

Makes text appear slanted (if supported by terminal).

Signature

export declare const italic: AnsiAnnotation

magenta

Standard magenta foreground color.

Signature

export declare const magenta: AnsiAnnotation

overline

Overline text formatting.

Adds a line above the text.

Signature

export declare const overline: AnsiAnnotation

red

Standard red foreground color.

Signature

export declare const red: AnsiAnnotation

reset

Reset all formatting.

Clears all ANSI formatting and returns to terminal defaults.

Signature

export declare const reset: AnsiAnnotation

strikethrough

Strikethrough text formatting.

Adds a line through the middle of the text.

Signature

export declare const strikethrough: AnsiAnnotation

underlined

Underlined text formatting.

Adds an underline beneath the text.

Signature

export declare const underlined: AnsiAnnotation

white

Standard white foreground color.

Signature

export declare const white: AnsiAnnotation

yellow

Standard yellow foreground color.

Signature

export declare const yellow: AnsiAnnotation

models

AnsiAnnotation (type alias)

Signature

export type AnsiAnnotation = Annotation<AnsiStyle>

AnsiAttribute (type alias)

Signature

export type AnsiAttribute = {
  readonly _tag: "ForegroundColor" | "BackgroundColor" | "TextAttribute" | "CommandAttribute"
  readonly name: string
  readonly code: string
}

AnsiStyle (type alias)

Signature

export type AnsiStyle = readonly AnsiAttribute[]

utilities

getAnsiEscapeSequence

Extracts ANSI escape sequence from annotation data.

Converts ANSI style data into the raw escape sequence string used by terminals. Styled sequences (colors, text effects) join codes with ';' and end with 'm'. Returns null for non-ANSI data.

Signature

export declare const getAnsiEscapeSequence: (data: AnsiStyle) => string | null

Example

import * as Ansi from "effect-boxes/Ansi"
import * as Annotation from "effect-boxes/Annotation"
 
const redStyle = Annotation.getAnnotationData(Ansi.red)
const escapeSeq = Ansi.getAnsiEscapeSequence(redStyle)
console.log(escapeSeq)
// "\u001b[31m" (ANSI red foreground code)

renderAnnotatedBox

Converts a box into an array of text lines with ANSI annotation support.

Renders a box to text lines while preserving ANSI styling annotations. This is the core function that bridges the Box layout system with terminal ANSI output.

Signature

export declare const renderAnnotatedBox: <A>({ cols, content, rows, annotation }: Box<A>) => string[]

Example

import * as Box from "effect-boxes/Box"
import * as Ansi from "effect-boxes/Ansi"
 
const box = Box.text("Warning").pipe(Box.annotate(Ansi.red))
const lines = Ansi.renderAnnotatedBox(box)
console.log(lines[0])

truncatePreservingAnsi

Truncates a string to a target width while preserving ANSI escape sequences.

Ensures that ANSI codes remain intact while the visible text is cut to fit within the specified width. Useful for displaying colored text in constrained spaces.

Signature

export declare const truncatePreservingAnsi: (text: string, targetWidth: number) => string

Example

import * as Ansi from "effect-boxes/Ansi"
 
const coloredText = "\x1b[31mThis is a long red text\x1b[0m"
const truncated = Ansi.truncatePreservingAnsi(coloredText, 10)
console.log(truncated)
// Outputs: "\x1b[31mThis is a \x1b[0m"