@0xkahi/cli-dye

A lightweight, dependency-free ANSI styling library for terminal output.

Dye provides reusable modifier chains, named terminal colors, truecolor hexadecimal values, automatic color detection, and ANSI stripping while always returning primitive strings.

Installation

npm install @0xkahi/cli-dye

bun add @0xkahi/cli-dye

Usage

import { dye } from '@0xkahi/cli-dye';

console.log(dye.bold('Important'));
console.log(dye.italic().underline('Styled text'));
console.log(dye.colorize('Success', { fg: 'brightGreen' }));

Modifiers

Dye supports the following modifiers:

• reset
• bold
• dim
• italic
• underline
• inverse
• hidden
• strikethrough

Use a modifier directly:

const message = dye.bold('Hello');

Or call it without text to create a reusable builder:

const heading = dye.bold().underline();

console.log(heading('First heading'));
console.log(heading('Second heading'));

Modifiers can be chained in any order. Repeated modifiers are automatically deduplicated.

Colors

Use colorize() to apply an optional foreground, background, or both:

console.log(dye.colorize('Error', { fg: 'brightWhite', bg: 'red' }));
console.log(dye.colorize('Info', { fg: 'cyan' }));
console.log(dye.colorize('Highlighted', { bg: 'yellow' }));

Named colors

The following foreground and background colors are available:

| Regular | Bright | | --- | --- | | black | brightBlack | | red | brightRed | | green | brightGreen | | yellow | brightYellow | | blue | brightBlue | | magenta | brightMagenta | | cyan | brightCyan | | white | brightWhite | | gray | |

The exact appearance of named colors depends on the user's terminal palette. gray and brightBlack use the same ANSI color code.

Hexadecimal colors

Create truecolor values with dye.hex():

const pink = dye.hex('#ed7892');
const blue = dye.hex('#00f');

console.log(dye.colorize('Truecolor', {
  fg: pink,
  bg: blue,
}));

Both #RGB and #RRGGBB forms are accepted, case-insensitively. Hashless values, invalid digits, and alpha-bearing values throw a TypeError.

Hex colors are emitted directly using terminal 24-bit color sequences. Dye does not convert them to ANSI-256 or ANSI-16 palettes.

Color builders

Calling colorize() with only options creates a reusable builder. Color builders support all modifiers:

const warning = dye
  .colorize({ fg: 'brightYellow' })
  .bold()
  .underline();

console.log(warning('Check your configuration'));
console.log(warning('Connection is unstable'));

Rendered values are always primitive strings—not string-like wrapper objects.

Color output control

Dye detects terminal color support when the module is loaded. The resolved state is exposed through the read-only enabled property:

console.log(dye.enabled);

Override color output when needed:

dye.setEnabled(true);      // Always emit ANSI sequences
dye.setEnabled(false);     // Always return plain text
dye.setEnabled(undefined); // Restore automatic detection

When output is disabled, styling and color functions return the supplied text without adding ANSI sequences.

Dye respects common terminal signals, including TTY support, NO_COLOR, FORCE_COLOR, and TERM=dumb.

Strip ANSI sequences

Use strip() to remove ANSI CSI sequences from a string:

const message = dye.colorize({ fg: 'red' }).bold('Failure');

console.log(dye.strip(message)); // "Failure"

It works with modifier-only output too:

console.log(dye.strip(dye.bold('Hello'))); // "Hello"

strip() also removes supported CSI sequences generated by other ANSI libraries.

TypeScript

Dye includes TypeScript declarations and exports its public color and builder types:

import { dye } from '@0xkahi/cli-dye';
import type {
  DyeColor,
  ColorizeOptions,
  HexColor,
  StandardColor,
  DyeStyler,
} from '@0xkahi/cli-dye';

API

dye.<modifier>(text)

Applies a modifier immediately and returns a string.

dye.<modifier>()

Returns a reusable DyeStyler builder.

dye.colorize(text, options?)

Applies foreground and/or background colors immediately.

dye.colorize(options?)

Returns a reusable color and modifier builder.

dye.hex(value)

Validates and converts #RGB or #RRGGBB into an opaque HexColor.

dye.strip(text)

Removes ANSI CSI escape sequences.

dye.enabled

Reports whether styling output is currently enabled.

dye.setEnabled(value)

Sets a true or false override. Pass undefined to restore automatic detection.