or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-ansi-styles

ANSI escape codes for styling strings in the terminal

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/ansi-styles@6.2.x

To install, run

npx @tessl/cli install tessl/npm-ansi-styles@6.2.0

index.mddocs/

ANSI Styles

ANSI Styles provides ANSI escape codes for styling strings in the terminal. It offers both basic styling options and advanced color conversion capabilities across 16, 256, and 16 million color modes. Designed as a low-level foundation for higher-level terminal styling libraries like Chalk.

Package Information

  • Package Name: ansi-styles
  • Package Type: npm
  • Language: JavaScript (ES Module with TypeScript definitions)
  • Installation: npm install ansi-styles

Core Imports

import ansiStyles from "ansi-styles";

Named exports:

import { 
  modifierNames, 
  foregroundColorNames, 
  backgroundColorNames, 
  colorNames 
} from "ansi-styles";

For CommonJS:

const ansiStyles = require("ansi-styles").default;
const { modifierNames, foregroundColorNames } = require("ansi-styles");

Basic Usage

import ansiStyles from "ansi-styles";

// Basic styling
console.log(`${ansiStyles.green.open}Hello world!${ansiStyles.green.close}`);
console.log(`${ansiStyles.bold.open}Bold text${ansiStyles.bold.close}`);

// Color conversion and advanced colors
console.log(`${ansiStyles.color.ansi(ansiStyles.rgbToAnsi(199, 20, 250))}Hello World${ansiStyles.color.close}`);
console.log(`${ansiStyles.color.ansi256(ansiStyles.rgbToAnsi256(199, 20, 250))}Hello World${ansiStyles.color.close}`);
console.log(`${ansiStyles.color.ansi16m(...ansiStyles.hexToRgb('#abcdef'))}Hello World${ansiStyles.color.close}`);

Architecture

ANSI Styles is organized around several key concepts:

  • Style Properties: Each style (color, modifier) has open and close string properties containing ANSI escape codes
  • Grouped Access: Styles are available both directly on the main object and grouped by type (modifier, color, bgColor)
  • Color Methods: Advanced color methods available on color and bgColor objects for 256-color and TrueColor support
  • Color Conversion: Standalone conversion functions for transforming between color formats (RGB, HEX, ANSI)
  • Raw Codes: Low-level access to ANSI codes via the codes Map

Capabilities

Text Modifiers

Text modification styles for formatting terminal output.

interface Modifier {
  /** Reset all styling */
  readonly reset: CSPair;
  /** Make text bold */
  readonly bold: CSPair;
  /** Emitting only a small amount of light */
  readonly dim: CSPair;
  /** Make text italic (not widely supported) */
  readonly italic: CSPair;
  /** Make text underline (not widely supported) */
  readonly underline: CSPair;
  /** Make text overline */
  readonly overline: CSPair;
  /** Inverse background and foreground colors */
  readonly inverse: CSPair;
  /** Prints the text, but makes it invisible */
  readonly hidden: CSPair;
  /** Puts a horizontal line through the center of the text (not widely supported) */
  readonly strikethrough: CSPair;
}

Foreground Colors

Foreground text coloring with support for basic and bright variants.

interface ForegroundColor {
  readonly black: CSPair;
  readonly red: CSPair;
  readonly green: CSPair;
  readonly yellow: CSPair;
  readonly blue: CSPair;
  readonly cyan: CSPair;
  readonly magenta: CSPair;
  readonly white: CSPair;
  
  /** Alias for blackBright */
  readonly gray: CSPair;
  /** Alias for blackBright */
  readonly grey: CSPair;
  
  readonly blackBright: CSPair;
  readonly redBright: CSPair;
  readonly greenBright: CSPair;
  readonly yellowBright: CSPair;
  readonly blueBright: CSPair;
  readonly cyanBright: CSPair;
  readonly magentaBright: CSPair;
  readonly whiteBright: CSPair;
}

Background Colors

Background coloring with support for basic and bright variants.

interface BackgroundColor {
  readonly bgBlack: CSPair;
  readonly bgRed: CSPair;
  readonly bgGreen: CSPair;
  readonly bgYellow: CSPair;
  readonly bgBlue: CSPair;
  readonly bgCyan: CSPair;
  readonly bgMagenta: CSPair;
  readonly bgWhite: CSPair;
  
  /** Alias for bgBlackBright */
  readonly bgGray: CSPair;
  /** Alias for bgBlackBright */
  readonly bgGrey: CSPair;
  
  readonly bgBlackBright: CSPair;
  readonly bgRedBright: CSPair;
  readonly bgGreenBright: CSPair;
  readonly bgYellowBright: CSPair;
  readonly bgBlueBright: CSPair;
  readonly bgCyanBright: CSPair;
  readonly bgMagentaBright: CSPair;
  readonly bgWhiteBright: CSPair;
}

Advanced Color Methods

Color object methods for 256-color and TrueColor support.

interface ColorBase {
  /** The ANSI terminal control sequence for ending this color */
  readonly close: string;
  
  /** Convert ANSI 16 color code to escape sequence */
  ansi(code: number): string;
  
  /** Convert ANSI 256 color code to escape sequence */
  ansi256(code: number): string;
  
  /** Convert RGB to TrueColor escape sequence */
  ansi16m(red: number, green: number, blue: number): string;
}

Usage examples:

// Using 16-color mode
console.log(`${ansiStyles.color.ansi(31)}Red text${ansiStyles.color.close}`);

// Using 256-color mode  
console.log(`${ansiStyles.color.ansi256(196)}Bright red${ansiStyles.color.close}`);

// Using TrueColor (16 million colors)
console.log(`${ansiStyles.color.ansi16m(255, 100, 0)}Orange text${ansiStyles.color.close}`);
console.log(`${ansiStyles.bgColor.ansi16m(0, 100, 255)}Blue background${ansiStyles.bgColor.close}`);

Color Conversion Methods

Standalone functions for converting between color formats.

interface ConvertColor {
  /** Convert from RGB color space to ANSI 256 color space */
  rgbToAnsi256(red: number, green: number, blue: number): number;
  
  /** Convert from RGB HEX color space to RGB color space */
  hexToRgb(hex: string): [red: number, green: number, blue: number];
  
  /** Convert from RGB HEX color space to ANSI 256 color space */
  hexToAnsi256(hex: string): number;
  
  /** Convert from ANSI 256 color space to ANSI 16 color space */
  ansi256ToAnsi(code: number): number;
  
  /** Convert from RGB color space to ANSI 16 color space */
  rgbToAnsi(red: number, green: number, blue: number): number;
  
  /** Convert from RGB HEX color space to ANSI 16 color space */
  hexToAnsi(hex: string): number;
}

Usage examples:

// Convert colors and use with color methods
const color256 = ansiStyles.rgbToAnsi256(199, 20, 250);
console.log(`${ansiStyles.color.ansi256(color256)}Purple text${ansiStyles.color.close}`);

const [r, g, b] = ansiStyles.hexToRgb('#C0FFEE');
console.log(`${ansiStyles.color.ansi16m(r, g, b)}Mint green${ansiStyles.color.close}`);

// Chain conversions
const ansi16Color = ansiStyles.ansi256ToAnsi(ansiStyles.hexToAnsi256('#FF0000'));
console.log(`${ansiStyles.color.ansi(ansi16Color)}Red text${ansiStyles.color.close}`);

Style Name Constants

Arrays of style names for validation and enumeration.

/** Array of all modifier style names */
const modifierNames: readonly ModifierName[];

/** Array of all foreground color names */
const foregroundColorNames: readonly ForegroundColorName[];

/** Array of all background color names */
const backgroundColorNames: readonly BackgroundColorName[];

/** Combined array of foreground and background color names */
const colorNames: readonly ColorName[];

Usage examples:

import { modifierNames, foregroundColorNames } from "ansi-styles";

// Validate style names
console.log(modifierNames.includes('bold')); // true
console.log(foregroundColorNames.includes('pink')); // false

// Enumerate available styles
modifierNames.forEach(name => console.log(`Modifier: ${name}`));
foregroundColorNames.forEach(name => console.log(`Color: ${name}`));

Raw Code Access

Low-level access to ANSI escape code mappings.

/** Map of ANSI open codes to close codes */
readonly codes: ReadonlyMap<number, number>;

Usage example:

// Access raw codes
console.log(ansiStyles.codes.get(36)); // 39 (cyan open -> default close)

// Iterate through all codes
for (const [open, close] of ansiStyles.codes) {
  console.log(`Open: ${open}, Close: ${close}`);
}

Style Groups

Non-enumerable style group objects for selective access.

/** All modifier styles grouped together */
readonly modifier: Modifier;

/** All foreground color styles and color methods */
readonly color: ColorBase & ForegroundColor;

/** All background color styles and color methods */
readonly bgColor: ColorBase & BackgroundColor;

Usage examples:

// Access styles via groups
console.log(ansiStyles.modifier.bold.open);
console.log(ansiStyles.color.green.open);
console.log(ansiStyles.bgColor.bgRed.open);

// Use group-specific color methods
console.log(ansiStyles.color.ansi256(196)); // Foreground red
console.log(ansiStyles.bgColor.ansi256(196)); // Background red

Types

/** Style pair with open and close ANSI escape sequences */
interface CSPair {
  /** The ANSI terminal control sequence for starting this style */
  readonly open: string;
  /** The ANSI terminal control sequence for ending this style */
  readonly close: string;
}

/** Basic modifier names */
type ModifierName = keyof Modifier;

/** Basic foreground color names */
type ForegroundColorName = keyof ForegroundColor;

/** Basic background color names */  
type BackgroundColorName = keyof BackgroundColor;

/** Basic color names (combination of foreground and background) */
type ColorName = ForegroundColorName | BackgroundColorName;

Main Export

/** Main ansiStyles object combining all functionality */
declare const ansiStyles: {
  readonly modifier: Modifier;
  readonly color: ColorBase & ForegroundColor;
  readonly bgColor: ColorBase & BackgroundColor;
  readonly codes: ReadonlyMap<number, number>;
} & ForegroundColor & BackgroundColor & Modifier & ConvertColor;

export default ansiStyles;

The main export provides access to all functionality both directly and through organized groups, enabling flexible usage patterns from simple styling to advanced color manipulation.