Ansilight is a colorful syntax highlighter for the terminal.
Includes 256 truecolor themes from highlight.js that look the same as in the browser.

The original highlight.js sample, rendered by ansilight.

Features

• 192 languages via highlight.js
• 256 truecolor themes ported from highlight.js
• Supports compound and nested style scopes, e.g. variable.constant and meta keyword
• Configurable code block: background, padding, width
• Detects color scheme: light / dark
• Resolves theme based on detected scheme
• Automatically detects color support with graceful fallback

Install

npm install ansilight

Requires Node.js 18+. This package is ESM only.

Quick Start

Reproduces the screenshot above using the bundled atom-one-dark theme.

import ansilight from 'ansilight';
import theme from 'ansilight/themes/atom-one-dark';

const code =
`class MyClass {
  public static myValue: string;
  constructor(init: string) {
    this.myValue = init;
  }
}
import fs = require("fs");
module MyModule {
  export interface MyInterface extends Other {
    myProperty: any;
  }
}
declare magicNumber number;
myArray.forEach(() => { }); // fat arrow syntax`;

const output = ansilight(code, {
  lang: 'typescript', // optional, auto-detected if omitted
  theme,              // optional, uses 'default' theme if omitted
});

console.log(output);

More examples

Color support

Color detection is handled by Ansis.

• Auto-detection with fallback: Truecolor → 256 → 16 → no color
• Environment variables: NO_COLOR, FORCE_COLOR, COLORTERM
• CLI flags: --no-color, --color

API

ansilight(code, [options])

Highlights source code and returns a string with ANSI escape sequences.

Arguments:

• code - source code to highlight
• options - highlighting and output options

Options

Option	Type	Default	Description
lang	string	auto-detect	Language name supported by highlight.js
theme	object	bundled default theme	ANSI theme object
background	string | false	theme background	Background color as a HEX value, or false to disable background
padding	number | string	0, or "0 1" when background is enabled	CSS-like padding shorthand
width	number | "content"	"content"	Visible background width, excluding padding

detectColorScheme([options])

Detects the terminal color scheme and returns 'dark', 'light', or undefined.

Detection is asynchronous and should be used once at application startup. If the terminal color scheme cannot be detected, COLORFGBG is used as a fallback hint.

import { detectColorScheme } from 'ansilight';

const scheme = await detectColorScheme({
  timeout: 100,
  fallback: null,
});

Options:

• timeout - timeout for a terminal response in ms. Default: 100.
  The response usually takes about 5-6 ms.
• fallback - value returned when color scheme cannot be detected. Default: undefined.
  • 'dark' or 'light' to force a default color scheme when detection fails
  • omit fallback to return undefined when detection fails

See the Detect color scheme example below.

resolveTheme(themes, [options])

Resolves a light or dark theme for the current terminal.

resolveTheme() uses detectColorScheme() internally and returns one of the provided themes. If the color scheme cannot be detected, the dark theme is used as fallback by default.

import { resolveTheme } from 'ansilight';
import light from 'ansilight/themes/github';
import dark from 'ansilight/themes/github-dark';

const theme = await resolveTheme({
  light,
  dark,
}, {
  timeout: 100,
  fallback: 'dark',
});

Arguments:

• themes - theme map keyed by color scheme, currently supports light and dark

Options:

• fallback - theme key used when color scheme cannot be detected. Default: dark.
• timeout - timeout for a terminal response in ms. Default: 100.

See the Resolve theme example below.

Themes

The themes was ported from highlight.js CSS styles.

The npm package bundles 6 popular themes. All 256 themes are in the GitHub repository and can be copied into any project.

Bundled themes

The npm package includes:

• default (light, built-in)
• dark (dark version of default)
• atom-one-light
• atom-one-dark
• github (light)
• github-dark

Import any bundled theme from the package:

import ansilight from 'ansilight';
import theme from 'ansilight/themes/github-dark';

console.log(ansilight(code, { theme }));

Other themes

The GitHub repository contains all 256 themes in themes/.

Copy any theme, e.g. themes/stackoverflow-light.js, into your project and import locally:

import ansilight from 'ansilight';
import theme from './stackoverflow-light.js';

console.log(ansilight(code, { theme }));

Theme gallery

Screenshots are captured in iTerm.

Click a theme name to view its source.
Click on an image to view full size.

Theme light	Theme dark
default ✓ bundled	dark ✓ bundled
atom-one-light ✓ bundled	atom-one-dark ✓ bundled
github ✓ bundled	github-dark ✓ bundled
vs	vs2015
base16-ia-light	base16-ia-dark
stackoverflow-light	stackoverflow-dark

See the full theme gallery with all 256 themes.

Examples

Option background

Use background to keep the theme background, override it with a custom color, or disable it completely.

import ansilight from 'ansilight';
import theme from 'ansilight/themes/atom-one-dark';

const code =
`function greet(name) {
  return "Hello, " + name + "!";
}`;

console.log(ansilight(code, {
  lang: 'javascript',
  // use theme background
  theme,
}), '\n');

console.log(ansilight(code, {
  lang: 'javascript',
  background: '#143757', // override theme background
  theme,
}), '\n');

console.log(ansilight(code, {
  lang: 'javascript',
  background: false, // disable background
  theme,
}), '\n');

Option width

Use width to control the visible background width. If the highlighted code is wider, the block expands to fit the content.

import ansilight from 'ansilight';
import theme from 'ansilight/themes/atom-one-dark';

const code =
`type User = {
  id: number;
  name: string;
};`;

console.log(ansilight(code, {
  lang: 'typescript',
  // use content width
  theme,
}), '\n');

console.log(ansilight(code, {
  lang: 'typescript',
  width: 40, // set minimum background width
  theme,
}), '\n');

Option padding

Use padding to add space inside the background block. The value uses CSS-like shorthand.

import ansilight from 'ansilight';
import theme from 'ansilight/themes/atom-one-dark';

const code =
`type User = {
  id: number;
  name: string;
};`;

console.log(ansilight(code, {
  lang: 'typescript',
  // default padding
  theme,
}), '\n');

console.log(ansilight(code, {
  lang: 'typescript',
  padding: 1, // same padding on all sides
  theme,
}), '\n');

console.log(ansilight(code, {
  lang: 'typescript',
  padding: '1 4', // vertical and horizontal padding
  theme,
}), '\n');

Detect color scheme

Use detectColorScheme() to choose a light or dark theme for the current terminal. This example disables the theme background so the selected theme is rendered over the real terminal background.

import ansilight, { detectColorScheme } from 'ansilight';
import light from 'ansilight/themes/github';
import dark from 'ansilight/themes/github-dark';

const code =
`type User = {
  id: number;
  name: string;
  email?: string;
};`;

// Resolve theme by terminal color scheme.
const theme = await detectColorScheme() === 'light'
  ? light // light terminal background
  : dark; // dark terminal background or undetected

const output = ansilight(code, {
  lang: 'typescript',
  background: false, // keep terminal background visible (theme background is off)
  theme,
});

console.log(output);

Resolve theme

Use resolveTheme() to choose a light or dark theme for the current terminal. It uses detectColorScheme() internally and falls back to the dark theme when the color scheme is not detected.

import ansilight, { resolveTheme } from 'ansilight';
import light from 'ansilight/themes/github';
import dark from 'ansilight/themes/github-dark';

const code =
`type User = {
  id: number;
  name: string;
  email?: string;
};`;

// Resolve theme by terminal color scheme.
const theme = await resolveTheme({ light, dark });

const output = ansilight(code, {
  lang: 'typescript',
  background: false, // keep terminal background visible (theme background is off)
  theme,
});

console.log(output);

Light theme on a light terminal background:

Dark theme on a dark terminal background:

Changelog

See CHANGELOG.md.

License

ISC