# ansi-sequence-parser

> A parser for ANSI escape sequences

Latest version **1.1.3** (published 2025-02-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install ansi-sequence-parser
pnpm add ansi-sequence-parser
yarn add ansi-sequence-parser
bun add ansi-sequence-parser
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.3 |
| Published | 2025-02-09 |
| First published | 2023-01-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 22.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | blake-mealey |
| Maintainers | bmealey |
| Keywords | ansi, sequences, parser |

## Links

- npm: https://www.npmjs.com/package/ansi-sequence-parser
- Repository: https://github.com/blake-mealey/ansi-sequence-parser
- Homepage: https://github.com/blake-mealey/ansi-sequence-parser#readme
- Issues: https://github.com/blake-mealey/ansi-sequence-parser/issues
- npm.io page: https://npm.io/package/ansi-sequence-parser

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 1.1.3 (latest) — 2025-02-09
- 1.1.2 — 2025-02-08
- 1.1.1 — 2023-07-26
- 1.1.0 — 2023-01-29
- 1.0.0 — 2023-01-29

## README

# `ansi-sequence-parser`

Parse ANSI escape sequences into a readable format for things like generating pretty HTML.

Install with your favourite package manager:

```sh
pnpm install ansi-sequence-parser
yarn add ansi-sequence-parser
npm install ansi-sequence-parser
```

## Parsing

Token format:

```ts
interface ParseToken {
  // The text content of the token
  value: string;
  // The foreground color
  foreground: Color | null;
  // The background color
  background: Color | null;
  // A Set of the applied decorations
  decorations: Set<DecorationType>;
}
```

Parse full input at once:

```ts
import { parseAnsiSequences } from 'ansi-sequence-parser';

const tokens = parseAnsiSequences(input);
```

If you want to parse your input in multiple chunks, make sure to create a parser so that you can maintain
state between chunks:

```ts
import { createAnsiSequenceParser } from 'ansi-sequence-parser';

const parser = createAnsiSequenceParser();

const tokensByLine = input.split(/\r?\n/).map((line) => parser.parse(line));
```

## Colors

Colors format:

```ts
// A named ANSI color, e.g. `magenta` or `brightBlue`
export interface NamedColor {
  type: 'named';
  name: ColorName;
}

// A color-table lookup
export interface TableColor {
  type: 'table';
  index: number;
}

// An RGB color
export interface RgbColor {
  type: 'rgb';
  rgb: [number, number, number];
}

export type Color = NamedColor | TableColor | RgbColor;
```

In order to interpret all of the above color types as a hex code, you can create a color palette:

```ts
import { parseAnsiSequences, createColorPalette } from 'ansi-sequence-parser';

const tokens = parseAnsiSequences(input);
const colorPalette = createColorPalette();

for (const token of tokens) {
  if (token.foreground) {
    const foregroundValue = colorPalette.value(token.foreground);
  }
  if (token.background) {
    const backgroundValue = colorPalette.value(token.background);
  }
}
```

You can also specify a custom named colors map:

```ts
import { parseAnsiSequences, createColorPalette } from 'ansi-sequence-parser';

const tokens = parseAnsiSequences(input);
const colorPalette = createColorPalette({
  black: '#000000',
  red: '#bb0000',
  green: '#00bb00',
  yellow: '#bbbb00',
  blue: '#0000bb',
  magenta: '#ff00ff',
  cyan: '#00bbbb',
  white: '#eeeeee',
  brightBlack: '#555555',
  brightRed: '#ff5555',
  brightGreen: '#00ff00',
  brightYellow: '#ffff55',
  brightBlue: '#5555ff',
  brightMagenta: '#ff55ff',
  brightCyan: '#55ffff',
  brightWhite: '#ffffff',
});
```

If you want to modify the default named colors map, you can import the `defaultNamedColorsMap`:

```ts
import {
  parseAnsiSequences,
  createColorPalette,
  defaultNamedColorsMap,
} from 'ansi-sequence-parser';

const tokens = parseAnsiSequences(input);
const colorPalette = createColorPalette({
  ...defaultNamedColorsMap,
  blue: '#0000cc',
});
```

---
_Source: https://npm.io/package/ansi-sequence-parser · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._