Fancy-ANSI is a small JavaScript library for converting ANSI to beautiful, browser-safe HTML

Demo: https://www.kubetail.com/demo
Preview: https://kubetail-org.github.io/fancy-ansi/

While adding ANSI markup support to kubetail we tested out several popular popular ANSI-to-html conversion libraries (e.g. ansi-html-community, ansi-to-html, ansi_up) and ran into a few problems:

• Failure to parse some of our users' ANSI markup
• Use of hard-coded styles that made customization more difficult
• Lack of support for CSS variables

To solve these problems and make something that integrated nicely into our frontend stack (Tailwind, React) we created Fancy-ANSI. The library is designed to be small (~4 kb gzipped), performant, easy-to-use and safe from XSS attacks. It has the following features:

• Supports easy customization using CSS variables
• Supports almost all SGR codes
• Supports OSC 8 hyperlinks (opt-in)
• Includes a Tailwind plugin (v3 and v4) that enables support for easy theming
• Includes a React component for easy use in a React environment
• Includes useful utilities like hasAnsi() and stripAnsi() that come in handy when working with ANSI
• Includes popular color palettes that can be swapped in easily

Try it out and let us know what you think! If you notice any bugs or have any feature requests just create a GitHub Issue.

Install the library using your favorite package manager:

# npm
npm install fancy-ansi

# yarn
yarn add fancy-ansi

# pnpm
pnpm add fancy-ansi

Now you can use it in your code with React:

// ExampleComponent.jsx
import { AnsiHtml } from 'fancy-ansi/react';

export const ExampleComponent = () => {
  const text = '\x1b[34mhello \x1b[33mworld\x1b[0m';
  return <AnsiHtml className="font-mono whitespace-pre text-sm" text={text} />;
};

Or with Vanilla-JS:

// example.ts
import { FancyAnsi } from 'fancy-ansi';

const fancyAnsi = new FancyAnsi();

export function addElementWithAnsi() {
  const el = document.createElement('div');
  el.innerHTML = fancyAnsi.toHtml('\x1b[34mhello \x1b[33mworld\x1b[0m');
  document.body.append(el);
}

The HTML rendered is browser-safe and ready with some sensible color choices that can be customized easily (see below).

You can configure Fancy-ANSI using CSS variables. For example, to invert blacks in dark mode you can change the value of black when the document has a "dark" class:

:root {
  --ansi-black: #000;
}

.dark {
  --ansi-black: #FFF;
}

The full list of supported variables can be found in the SGR Parameters section below.

Terminals render OSC 8 hyperlinks as clickable links. Tools such as ls --hyperlink, gcc, systemd and cargo emit them. By default, Fancy-ANSI renders only the link text. To render links as <a> tags, enable the hyperlinks option:

import { FancyAnsi } from 'fancy-ansi';

const fancyAnsi = new FancyAnsi({ hyperlinks: true });

fancyAnsi.toHtml('see \x1b]8;;https://example.com\x1b\\link text\x1b]8;;\x1b\\ after');
// => 'see <a href="https://example.com" rel="noopener noreferrer nofollow">link text</a> after'

With React, use the hyperlinks prop:

<AnsiHtml hyperlinks text={text} />

Only http: and https: URLs become links. Other URLs, such as javascript: or data:, render as plain text. Links always get rel="noopener noreferrer nofollow". To set target or class, pass an options object instead of true:

const fancyAnsi = new FancyAnsi({
  hyperlinks: { target: '_blank', className: 'ansi-link' },
});

fancyAnsi.toHtml('\x1b]8;;https://example.com\x07link\x1b]8;;\x07');
// => '<a href="https://example.com" rel="noopener noreferrer nofollow" target="_blank" class="ansi-link">link</a>'

Links have no inline styles, so your page's CSS decides how they look. SGR codes inside a link still apply.

Enable this only if you trust the input. The URL comes from the input, so link text can show one URL while the link points to another. If you render output you don't control, such as logs, leave this option off.

toHtml() output can be many times the size of its input. Each run of text after an SGR sequence gets a new <span> with the full style, even when the style did not change. A 5-byte input such as \x1b[1mx can emit hundreds of bytes.

Conversion is fast, but inserting a large result into the DOM can freeze the page. If you render input you don't control, cap its length per call. If you render logs, convert one line at a time.

Extended colors:

The Fancy-ANSI Tailwind plugin adds a utility for each built-in palette. To use the plugin with Tailwind v4, import it in your css after Tailwind:

/* index.css */
@import "tailwindcss";
@import "fancy-ansi/plugin";

Each ansi-{palette} utility sets the --ansi-{color} variables to that palette. The palettes are xtermjs, vga, vscode, windows10, terminalapp, putty, xterm, ubuntu and eclipse. Utilities work with variants, so you can use one palette in light mode and another in dark mode:

<html class="ansi-vscode dark:ansi-xtermjs">

You can also apply them in your css:

:root {
  @apply ansi-vscode dark:ansi-xtermjs;
}

Individual palette colors are available as theme variables named --ansi-{palette}-{color} (e.g. var(--ansi-vscode-red)).

With Tailwind v3, add the plugin to your tailwind.config.js file:

// tailwind.config.js
module.exports = {
  plugins: [
    require('fancy-ansi/plugin')
  ]
}

The palettes are available through the theme() function as ansi.colors.{palette}.{color}:

:root {
  --ansi-red: theme(ansi.colors.vscode.red);
}

Fancy-ANSI has a convenient React component that you can import from the fancy-ansi/react module:

// ExampleComponent.jsx
import { AnsiHtml } from 'fancy-ansi/react';

export const ExampleComponent = () => {
  const text = '\x1b[34mhello \x1b[33mworld\x1b[0m';
  return <AnsiHtml className="font-mono whitespace-pre text-sm" text={text} />;
};

You can see some example implementations in the examples/ directory:

• Vite - React
• Next.js

FancyAnsi

  constructor(options)
    * @param {Object} [options]
    * @param {boolean|Object} [options.hyperlinks] - Render OSC 8 hyperlinks as <a> tags (http(s) URLs only)
    * @param {string} [options.hyperlinks.target] - Value of the `target` attribute
    * @param {string} [options.hyperlinks.className] - Value of the `class` attribute

  toHtml(input)
    * @param {string} input - The input string
    * @returns {string} Browser-safe HTML string containing stylized ANSI content
    * Output can be up to 95x the input length (see "Output size")

Example:

  import { FancyAnsi } from 'fancy-ansi';

  const fancyAnsi = new FancyAnsi();
  fancyAnsi.toHtml('\x1b[1mThis is in bold.\x1b[0m');

hasAnsi(input)

  * @param {string} input - The input string
  * @returns {boolean} Boolean indicating whether or not input string contains ANSI markup

Example:

  import { hasAnsi } from 'fancy-ansi';

  if (hasAnsi('\x1b[1mThis is in bold.\x1b[0m')) {
    console.log('string has ansi');
  } else {
    console.log('string doesn\'t have ansi');
  }

stripAnsi(input)

  * @param {string} input - The input string
  * @returns {string} Content of input string with ANSI markup removed

Example:

  import { stripAnsi } from 'fancy-ansi';

  const withoutAnsi = stripAnsi('\x1b[1mThis is in bold.\x1b[0m');
  console.log(`string without ansi: ${withoutAnsi}`);

stripAnsi() is not a terminal sanitizer. It uses ansi-regex, not the toHtml() parser, so the two can disagree on what a sequence is. Its output can still contain a lone ESC, the tail of an unterminated OSC sequence, and C0 characters such as \r and \b. Don't write its output to a terminal as if it were clean.

stripAnsi('x\x1bP1$r\x1b');      // => 'x1$r\x1b'  (lone ESC left)
stripAnsi('a\x1b]8;;http://x');  // => 'attp://x'  (head of unterminated OSC stripped)
stripAnsi('\x9b31mred');         // => 'red', while toHtml() keeps '\x9b31mred' as text

`fancy-ansi/colors` module

Example:

  import { xtermjs, terminalapp } from 'fancy-ansi/colors';

  console.log(`xterm.js red: ${xtermjs.red}`);
  console.log(`Terminal.app red: ${terminalapp.red}`);

Available palettes:

  * eclipse
  * putty
  * terminalapp
  * ubuntu
  * vga
  * vscode
  * windows10
  * xterm
  * xtermjs

To develop Fancy-ANSI, first clone the repository then install the dependencies:

git clone git@github.com:kubetail-org/fancy-ansi.git
cd fancy-ansi
pnpm install

Fancy-ANSI uses vite for development. To run run the vite dev server, use the dev command:

pnpm dev

Now you can access the demo page and see your changes at http://localhost:5173/.

Fancy-ANSI uses jest for testing (via vitest). To run the tests, use the test command:

pnpm test

The test files are colocated with the source code in the src/ directory, with the filename format {name}.test.(ts|tsx).

To check test coverage, use the coverage command. It fails if coverage drops below 100%:

pnpm coverage

To build Fancy-ANSI for production, run the build command:

pnpm build

The production files will be located in the dist/ directory.

Report vulnerabilities privately through GitHub private vulnerability reporting. See SECURITY.md for the supported versions.

• The ANSI parsing code is from ansi_up
• has/strip methods use Chalk's ansi-regex
• Fancy Nancy