Ansi.ts 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

See

• renderAnnotatedBox — render a styled box to terminal string
• combine — merge multiple styles

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.

Example

```typescript
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

**Signature**

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

Source

constructors

bgBlack

Black background color.

Signature

declare const bgBlack: AnsiAnnotation;

Source

bgBlue

Blue background color.

Signature

declare const bgBlue: AnsiAnnotation;

Source

bgBrightBlack

Bright black (gray) background color.

Signature

declare const bgBrightBlack: AnsiAnnotation;

Source

bgBrightBlue

Bright blue background color.

Signature

declare const bgBrightBlue: AnsiAnnotation;

Source

bgBrightCyan

Bright cyan background color.

Signature

declare const bgBrightCyan: AnsiAnnotation;

Source

bgBrightGreen

Bright green background color.

Signature

declare const bgBrightGreen: AnsiAnnotation;

Source

bgBrightMagenta

Bright magenta background color.

Signature

declare const bgBrightMagenta: AnsiAnnotation;

Source

bgBrightRed

Bright red background color.

Signature

declare const bgBrightRed: AnsiAnnotation;

Source

bgBrightWhite

Bright white background color.

Signature

declare const bgBrightWhite: AnsiAnnotation;

Source

bgBrightYellow

Bright yellow background color.

Signature

declare const bgBrightYellow: AnsiAnnotation;

Source

bgColor256

Creates a background color using 256-color palette.

Example

```typescript
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
)

**Signature**

```ts
declare const bgColor256: (n: number) => AnsiAnnotation

Source

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").

Example

```typescript
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))

**Signature**

```ts
declare const bgColorHex: (hex: string) => AnsiAnnotation

Source

bgColorRGB

Creates a background color using RGB values.

Example

```typescript
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)
)

**Signature**

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

Source

bgCyan

Cyan background color.

Signature

declare const bgCyan: AnsiAnnotation;

Source

bgDefault

Default background color (terminal default).

Signature

declare const bgDefault: AnsiAnnotation;

Source

bgGreen

Green background color.

Signature

declare const bgGreen: AnsiAnnotation;

Source

bgMagenta

Magenta background color.

Signature

declare const bgMagenta: AnsiAnnotation;

Source

bgRed

Red background color.

Signature

declare const bgRed: AnsiAnnotation;

Source

bgWhite

White background color.

Signature

declare const bgWhite: AnsiAnnotation;

Source

bgYellow

Yellow background color.

Signature

declare const bgYellow: AnsiAnnotation;

Source

black

Standard black foreground color.

Signature

declare const black: AnsiAnnotation;

Source

blink

Blinking text formatting.

Makes text blink (if supported by terminal).

Signature

declare const blink: AnsiAnnotation;

Source

blue

Standard blue foreground color.

Signature

declare const blue: AnsiAnnotation;

Source

bold

Bold text formatting.

Makes text appear with increased weight/intensity.

Signature

declare const bold: AnsiAnnotation;

Source

brightBlack

Bright black (gray) foreground color.

Signature

declare const brightBlack: AnsiAnnotation;

Source

brightBlue

Bright blue foreground color.

Signature

declare const brightBlue: AnsiAnnotation;

Source

brightCyan

Bright cyan foreground color.

Signature

declare const brightCyan: AnsiAnnotation;

Source

brightGreen

Bright green foreground color.

Signature

declare const brightGreen: AnsiAnnotation;

Source

brightMagenta

Bright magenta foreground color.

Signature

declare const brightMagenta: AnsiAnnotation;

Source

brightRed

Bright red foreground color.

Signature

declare const brightRed: AnsiAnnotation;

Source

brightWhite

Bright white foreground color.

Signature

declare const brightWhite: AnsiAnnotation;

Source

brightYellow

Bright yellow foreground color.

Signature

declare const brightYellow: AnsiAnnotation;

Source

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.

Example

```typescript
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)
)

**Signature**

```ts
declare const color256: (n: number) => AnsiAnnotation

Source

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").

Example

```typescript
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))

**Signature**

```ts
declare const colorHex: (hex: string) => AnsiAnnotation

Source

colorRGB

Creates a foreground color using RGB values.

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

Example

```typescript
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))

**Signature**

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

Source

cyan

Standard cyan foreground color.

Signature

declare const cyan: AnsiAnnotation;

Source

dim

Dim text formatting.

Makes text appear with reduced intensity.

Signature

declare const dim: AnsiAnnotation;

Source

fgDefault

Default foreground color (terminal default).

Signature

declare const fgDefault: AnsiAnnotation;

Source

green

Standard green foreground color.

Signature

declare const green: AnsiAnnotation;

Source

hidden

Hidden text formatting.

Makes text invisible (useful for passwords).

Signature

declare const hidden: AnsiAnnotation;

Source

inverse

Inverse text formatting.

Swaps foreground and background colors.

Signature

declare const inverse: AnsiAnnotation;

Source

italic

Italic text formatting.

Makes text appear slanted (if supported by terminal).

Signature

declare const italic: AnsiAnnotation;

Source

magenta

Standard magenta foreground color.

Signature

declare const magenta: AnsiAnnotation;

Source

overline

Overline text formatting.

Adds a line above the text.

Signature

declare const overline: AnsiAnnotation;

Source

red

Standard red foreground color.

Signature

declare const red: AnsiAnnotation;

Source

reset

Reset all formatting.

Clears all ANSI formatting and returns to terminal defaults.

Signature

declare const reset: AnsiAnnotation;

Source

strikethrough

Strikethrough text formatting.

Adds a line through the middle of the text.

Signature

declare const strikethrough: AnsiAnnotation;

Source

underlined

Underlined text formatting.

Adds an underline beneath the text.

Signature

declare const underlined: AnsiAnnotation;

Source

white

Standard white foreground color.

Signature

declare const white: AnsiAnnotation;

Source

yellow

Standard yellow foreground color.

Signature

declare const yellow: AnsiAnnotation;

Source

models

AnsiAnnotation (type alias)

Signature

type AnsiAnnotation = Annotation<AnsiStyle>;

Source

AnsiAttribute (type alias)

Signature

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

Source

AnsiStyle (type alias)

Signature

type AnsiStyle = readonly AnsiAttribute[];

Source

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.

Example

```typescript
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)

**Signature**

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

Source

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.

Example

```typescript
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])

**Signature**

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

Source

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.

Example

```typescript
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"

**Signature**

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

Source