ansi-sequence-parser

1.1.3 verified Sat Apr 25 auth: no javascript

A parser for ANSI escape sequences that tokenizes input into structured objects with foreground/background colors and decorations. Current stable version is 1.1.3. Released with minor features and bug fixes since its initial v1.0.0 in 2023. Key differentiator: it supports incremental parsing via a stateful parser, provides a color palette to interpret named, table, and RGB colors as hex codes, and ships TypeScript types. Suitable for generating pretty HTML or custom rendering from terminal output.

Common errors

error Error: Cannot find module 'ansi-sequence-parser' ↓

cause Package not installed or running in an environment that doesn't support ESM.

fix

Run 'npm install ansi-sequence-parser' and ensure your project uses ESM (type: 'module' in package.json or .mjs extension).

error TypeError: parseAnsiSequences is not a function ↓

cause Incorrect import (maybe default import instead of named).

fix

Use: import { parseAnsiSequences } from 'ansi-sequence-parser'

error TypeError: Cannot read properties of undefined (reading 'value') ↓

cause Calling palette.value() on null/undefined color object.

fix

Check token.foreground or token.background for null before calling palette.value().

Warnings

gotcha The parser uses infinite loop in v1.1.0 and earlier when parsing an unclosed sequence. ↓

fix Upgrade to v1.1.1 or later.

gotcha createColorPalette() without arguments will throw if you try to use custom color indices beyond the default 16-color table. ↓

fix Provide a full custom palette or extend the default with defaultNamedColorsMap.

gotcha The parser does not handle all edge cases; e.g., SGR sequences with multiple parameters separated by semicolons may produce unexpected results if not properly terminated. ↓

fix Always ensure sequences are terminated with a letter (e.g., 'm') to avoid parsing issues.

gotcha The library only supports SGR (Select Graphic Rendition) sequences; other ANSI escape sequences (like cursor movement) are ignored. ↓

fix Pre-process input to remove non-SGR sequences if needed, or use a more complete parser.

Install

npm install ansi-sequence-parser

yarn add ansi-sequence-parser

pnpm add ansi-sequence-parser

Imports

parseAnsiSequences

wrong

const parseAnsiSequences = require('ansi-sequence-parser').parseAnsiSequences

correct

import { parseAnsiSequences } from 'ansi-sequence-parser'

ESM only; package does not provide CJS exports.

createAnsiSequenceParser

wrong

import createAnsiSequenceParser from 'ansi-sequence-parser'

correct

import { createAnsiSequenceParser } from 'ansi-sequence-parser'

Named export, not default.

createColorPalette
wrong
```
import { ColorPalette } from 'ansi-sequence-parser'
```
correct
```
import { createColorPalette } from 'ansi-sequence-parser'
```
ColorPalette is the return type, not a constructor. createColorPalette is the function.
defaultNamedColorsMap
```
import { defaultNamedColorsMap } from 'ansi-sequence-parser'
```
Exported as a plain object, not a function.

Quickstart

Demonstrates parsing ANSI sequences and converting colors to hex using the default color palette.

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

const input = '\x1b[31mHello\x1b[0m \x1b[1;34mWorld\x1b[0m';
const tokens = parseAnsiSequences(input);
const palette = createColorPalette();

for (const token of tokens) {
  const fg = token.foreground ? palette.value(token.foreground) : null;
  const bg = token.background ? palette.value(token.background) : null;
  console.log({ value: token.value, foreground: fg, background: bg, decorations: [...token.decorations] });
}