ansis

Make terminals a little more colorful 🌈

[ANSI S]tyles

ANSI color library for use in terminals, CI environments, and Chromium-based browsers.
Ansis is focused on small size and speed while providing rich functionality and handling edge cases.

// Named imports - for cleaner, more readable code
import { red, cyan, bold, hex, rgb } from 'ansis';

// Clean chained syntax with template literals - no extra parentheses
console.log(bold.bgRed` FAIL `);

// Nested templates - no string concatenation needed
console.log(red`✖ Error: ${cyan`file.js`} not found`);

// Truecolor: hex and rgb
console.log(hex('#FF75D1').bold`Pink`);
console.log(rgb(224, 17, 95).italic`Ruby`);

🔗 Shortcuts

🚀 Getting Started 📌 Ansis vs styleText() 🔄 Migrating from ⚖️ Alternatives ✅ Compare features

💻 CLI Environment 🧪 CLI Testing ⚙️ Compatibility 🔧Troubleshooting

🔔 Upgrading to v4 · New features · Breaking changes

⭐️ Star History

✨ Highlights

🎨 Colors - 16 · 256 · Truecolor (hex/rgb) · Named colors (orange, pink ...)
✍️ Syntax - Chained · Template literals · Nested templates
⚙️ Works  - ESM · CJS · TS · Node 10+ · Bun · Deno · CI · Chromium browsers
🧠 Smart  - Auto color detection · Fallback (truecolor → 256 → 16 → b&w) · NO_COLOR · FORCE_COLOR
📦 Tiny   - 5.8 kB · Drop-in replacement for Chalk (44 kB)

⚡ Performance

Ansis is the fastest when using 2 or more styles, which is the common real-world use case.

📊 Full benchmarks →

💡 Features

🎨 Colors & Styles

• ANSI styles: dim bold italic underline strikethrough …
• ANSI 16 colors: red redBright bgRed bgRedBright …
• ANSI 256 colors: fg(n) bg(n)
• Truecolor: hex('#FF75D1') rgb(224, 17, 95) bgHex() bgRgb()
• Named truecolors: orange() bgPink() … - via extend()

✍️ Syntax

• Chained styles: red.bold.underline - no nested calls like red(bold(underline()))
• Template literals: red`text` - no parentheses
• Nested templates: red`Error: ${cyan`file.js`} not found` - no string concatenations

🛠️ Utilities

• Strip ANSI codes: ansis.strip(red('text')) → plain 'text'
• Hyperlink: blue.link('https://...', 'Click here'), link('https://...')
• Raw escape codes: open / close - `${red.open}Error${red.close} file not found`

💻 Environment

• Auto color detection + Fallback: Truecolor → 256 → 16 → b&w
• ENV variables: NO_COLOR FORCE_COLOR TERM COLORTERM
• CLI flags: --no-color --color
• CLI testing: force color levels in tests

⚙️ Compatibility

• ESM · CJS · TypeScript · Bun · Deno · Next.js · CI (GitHub and others)
• Chromium browsers: Chrome · Edge · Opera · Brave · Vivaldi
• Drop-in replacement for chalk ansi-colors colorette and others

🎯 You might also like

• ansilight - Truecolor syntax highlighter for the terminal with 256 highlight.js themes
• flaget - CLI argument parsing. A smaller (5 kB) and faster alternative to yargs-parser (85 kB)

⚖️ Alternatives

chalk, picocolors, colorette, kleur, ansi-colors, kolorist, cli-color, colors-cli, colors.js, tinyrainbow

Since Node.js 22 supports ANSI styling natively via util.styleText(), it is recommended for simple use cases where 16 colors are enough and top performance is not critical. See styleText() limitations.

✅ Compare features 📊 Benchmarks 🧩 Handling edge cases

Install

npm install ansis

For Node.js 10–12+ use special build npm install ansis@node10

Usage

ESM

import ansis, { red, bold, fg, hex, rgb } from 'ansis';

CJS

const ansis = require('ansis');
const { red, bold, fg, hex, rgb } = require('ansis');

Chained syntax

All colors, styles and functions are chainable. Each color or style can be combined in any order.

import { red, bold, hex } from 'ansis';

red.bold`text`;
hex('#FF75D1').bgCyan.bold`text`;
bold.hex('#FF75D1').bgCyan`text`;

Template literals

Omit parentheses to keep your code clean:

import { red, yellow, green } from 'ansis';

red`Error`; // no parentheses
red`Red ${yellow`Yellow ${green`Green`} Yellow`} Red`; // deep nested templates

Escape sequences work exactly as in regular strings:

red`Hello\nWorld`; // two lines in red
red`prev\\next`;   // one line: prev\next

↑ top

ANSI Styles

dim bold italic underline strikethrough inverse visible hidden reset

ANSI 16 colors

There are 16 basic colors: 8 standard and 8 bright variants.

Example	Color	Background	Bright Example	Bright Color	Bright Background
	black	bgBlack		gray	bgGray
	red	bgRed		redBright	bgRedBright
	green	bgGreen		greenBright	bgGreenBright
	yellow	bgYellow		yellowBright	bgYellowBright
	blue	bgBlue		blueBright	bgBlueBright
	magenta	bgMagenta		magentaBright	bgMagentaBright
	cyan	bgCyan		cyanBright	bgCyanBright
	white	bgWhite		whiteBright	bgWhiteBright

ANSI 256 colors

• Foreground: fg(code) - chalk.ansi256(code) equivalent
• Background: bg(code) - chalk.bgAnsi256(code) equivalent

import { bold, fg, bg } from 'ansis';

fg(96)`Bright Cyan`;
bg(105).fg(96)`Cyan text on magenta background`;
bold.fg(96).underline`Bold underline Bright Cyan`;

256 color codes

See ANSI color codes.

Fallback

If a terminal supports only 16 colors then ANSI 256 colors will be interpolated into base 16 colors.

Truecolor

• Foreground: hex() rgb()
• Background: bgHex() bgRgb()

import { bold, hex, rgb, bgHex } from 'ansis';

hex('#E0115F').bold`Bold Ruby`;
rgb(224, 17, 95).italic`Italic Ruby`;
bold.hex('#E0115F').bgHex('#96C')`Ruby text on amethyst background`;

See also named truecolors.

Fallback

Ansis automatically interpolates to the best available color level.

Truecolor → 256 colors → 16 colors → no colors (b&w)

↑ top

Named truecolors

Register any hex color as a named style via extend(). Background methods bg* are generated automatically.

import { Ansis } from 'ansis';

const myTheme = {
  orange: '#ffa500',
  pink:   '#ffc0cb',
};

const color = new Ansis().extend(myTheme);

color.orange.bold`orange bold`;       // extended first in chain
color.bgOrange`orange background`;    // auto-generated bg tag
color.pink`pink foreground`;
color.bgPink`pink background`;        // auto-generated bg tag
color.red`built-in red still works`;  // built-in remains intact

Example: extend with CSS color names

import { Ansis } from 'ansis';
import colorNames from 'css-color-names'; // { pink: '#ffc0cb', orange: '#ffa500', ... }

const color = new Ansis().extend(colorNames);

color.pink('Pink foreground');
color.bgPink('Pink background'); // auto-generated bg

Hyperlink

OSC 8 hyperlinks are now supported by many terminal emulators.

Use link(url, text?) to create a terminal hyperlink. If text is omitted, the URL itself is used as the visible label.

• link(url, text) - link URL + optional link text
• link(url) - URL as both target and text

import { blue, link } from 'ansis';

link('https://example.com'); //  URL and text are the same
blue.underline.link('https://example.com', 'Click here');

blue.underline.link(...); // ✅
blue.link(...).underline; // ❌

↑ top

Color support

Ansis automatically detects the supported color level:

• 0 – No color
• 1 – Basic ANSI (16 colors)
• 2 – Extended ANSI (256 colors)
• 3 – Truecolor (16 million colors)

Check the detected level at runtime:

import ansis from 'ansis';

console.log(ansis.level);         // 0 | 1 | 2 | 3
console.log(ansis.isSupported()); // true -> level > 0 (at least 16 colors supported)

Create an Ansis instance directly when you need to override color detection:

import { Ansis } from 'ansis';

const noColor    = new Ansis(0);  // always plain text, no ANSI codes
const basicColor = new Ansis(1);  // 16 colors; hex/rgb fall back to nearest
const autoColor  = new Ansis();   // auto-detect using globalThis

console.log(noColor.red`foo`);                  // plain text, no ANSI codes
console.log(basicColor.hex('#FFAB40')`Orange`); // falls back to yellowBright

The constructor also accepts a mock globalThis object to control auto-detection in custom runtimes:

const color = new Ansis({
  process: {
    env: { FORCE_COLOR: '1' }, // COLORTERM, TERM, CI, NO_COLOR, FORCE_COLOR
    argv: ['node', 'app.js'],  // --no-color, --color
    stdout: { isTTY: false },
    platform: 'linux',
  },
});

console.log(color.level); // 1

import { Ansis } from 'ansis';

/**
 * @param  {boolean} noColors Disable colors for non-terminal output.
 * @return {Ansis} Default or custom instance
 */
function safeAnsis(noColors) {
  return noColors
    ? new Ansis(0) // disable colors
    : new Ansis(); // auto/detect color support
}

// handle a special CLI flag to disable colors
const ansis = safeAnsis(process.argv.includes('--save-to-log'))

Auto-detection

Ansis detects color support from the runtime environment in this order:

1. Chromium browser-like runtimes

   • detected first -> truecolor

2. Dumb terminal

   • TERM=dumb -> no colors

3. COLORTERM

   • truecolor or 24bit -> truecolor
   • ansi256 -> 256 colors
   • ansi -> 16 colors

4. CI environment (not TTY)

   • GitHub Actions -> truecolor
   • other CI environments -> 16 colors

5. Windows

   • Windows terminals since Windows 10 build 14931 (released 2016) -> truecolor

6. 256-color terminals

   • known 256-color terminals -> 256 colors

7. Fallback

   • unknown terminals -> 16 colors

Colors are enabled only for a TTY, CI, and the PM2 and Next.js runtimes. Output to a pipe or a file has no colors, even when COLORTERM is set. To explicitly enable colors in non-TTY environments, use FORCE_COLOR.

Environment & CLI options

Ansis detects color support automatically, but you can override it with environment variables and CLI flags.

Environment variables

NO_COLOR

Set to any non-empty value (1, true) to disable color output (see no-color.org):

NO_COLOR=1 node app.js

FORCE_COLOR

Force or override color support via environment variable (see force-color.org).

TERM

TERM identifies the current terminal type and is used during auto-detection.

Examples of TERM values with 256-color support: screen-256color, xterm-256color, rxvt-256color, putty-256color, mintty-256color, linux-256color, tmux-256color, ansi-256color.

TERM=dumb has higher priority than COLORTERM, CI detection, PM2, Next.js edge runtime, and platform-specific defaults. To explicitly override auto-detection, use FORCE_COLOR.

COLORTERM

COLORTERM hints at how many colors a terminal can show. It does not turn colors on by itself. Ansis uses it to choose the color level when color output is supported.

Some terminals (iTerm, VS Code, xterm-kitty, KDE Konsole, and others) set COLORTERM=truecolor in addition to a TERM value that only advertises 256-color support, for example TERM=xterm-256color.

CLI flags

Pass --no-color or --color directly to your script:

./app.js              # auto-detect
./app.js --no-color   # disable colors
./app.js --color      # enable colors (useful when piping output)

Quick reference

node app.js                             # auto-detect
node app.js > log.txt                   # no colors (non-TTY)

NO_COLOR=1 node app.js                  # force off
FORCE_COLOR=0 node app.js               # force off

FORCE_COLOR=1 node app.js > log.txt     # force 16 colors
FORCE_COLOR=2 node app.js > log.txt     # force 256 colors
FORCE_COLOR=3 node app.js > log.txt     # force truecolor
FORCE_COLOR=true node app.js > log.txt  # detect the level, fallback to 16 colors

node app.js --no-color                  # disable via flag
node app.js --color > log.txt           # detect the level via flag, fallback to 16 colors

↑ top

Edge cases

Break style at New Line

Ansis and Chalk add a style break at each new line to correctly display multi-line text.
However, Picocolors doesn’t handle this case.

ansis.bgRed('\n ERROR \n') + ansis.cyan('The file not found!') // ✅
chalk.bgRed('\n ERROR \n') + chalk.cyan('The file not found!') // ✅
pico.bgRed('\n ERROR \n') + pico.cyan('The file not found!')   // ❌

Nested template strings

Only Ansis handles this very useful use case.

ansis.red`R ${ansis.green`G ${ansis.blue`B`} G`} R` // ✅
chalk.red`R ${chalk.green`G ${chalk.blue`B`} G`} R` // ❌
pico.red`R ${pico.green`G ${pico.blue`B`} G`} R`    // ❌

Handling arguments

Compare how different libraries handle various input arguments in their functions.

ansis.red()          // ✅ ''
chalk.red()          // ✅ ''
pico.red()           // ❌ \e[31mundefined\e[39m

ansis.red(undefined) // ✅ ''
chalk.red(undefined) // ❌ \e[31mundefined\e[39m
pico.red(undefined)  // ❌ \e[31mundefined\e[39m

ansis.red(null)      // ✅ ''
chalk.red(null)      // ❌ \e[31mnull\e[39m
pico.red(null)       // ❌ \e[31mnull\e[39m

ansis.red('')        // ✅ ''
chalk.red('')        // ✅ ''
pico.red('')         // ❌ \e[31m\e[39m

ansis.reset()        // ✅ \e[0m
chalk.reset()        // ❌ ''
pico.reset()         // ❌ \e[0mundefined\e[0m

Legend:

• ✅'' - Returns an empty string without ANSI escape codes. This is the correct and expected behavior.
• ✅\e[0m - Returns the reset escape code.
• ❌'ESC' - Returns an empty string containing ANSI escape codes, e.g., \e[31m\e[39m.
• ❌'undefined' - Returns the styled string undefined.
• ❌'null' - Returns the styled string null.
• ❌[object] - Returns an object of the library instance.
• ❌- - The feature is not supported.
• ❌Error - Causes a fatal error.

Other arguments are correctly handled by all libraries:

c.red(0)       // '0' in red
c.red(false)   // 'false' in red
c.red(true)    // 'true' in red
c.red(5/'1px') // 'NaN' in red
c.red(1/0)     // 'Infinity' in red

↑ top

Ansis vs styleText()

Since Node v22, the built-in util.styleText() has been officially introduced, supporting standard modifiers - the basic 16 colors and styles.

Where it works

Ansis

✅ Node v10+
✅ Chromium-based browsers and Safari
⚠️ Firefox DevTools don’t render ANSI escape sequences

styleText

✅ Node v22+ (native)
❌ No browser support (Node only)

Performance

In practical benchmarks, styleText() is 100x slower than Ansis:

ansis.red('text');        // 59.646.465 ops/sec
styleText('red', 'text'); //    579.832 ops/sec

See full benchmarks.

Color support detection

Ansis

• Auto-detects terminal, TTY, CI and browser color support with automatic fallback
• Supports NO_COLOR FORCE_COLOR COLORTERM --no-color --color
• ansis.level returns the detected color level

styleText

• Auto-detects terminal color support
• Supports only NO_COLOR FORCE_COLOR NODE_DISABLE_COLORS

Simple styling

import { green } from 'ansis';
import { styleText } from 'node:util';

green`Success!`; // ansis
styleText('green', 'Success!');

green.bold`Success!`; // ansis
styleText(['green', 'bold'], 'Success!');

Nested styling

import { red, cyan } from 'ansis';
import { styleText } from 'node:util';

red`Error: ${cyan.bold`file.js`} not found!`; // ansis
styleText('red', `Error: ${styleText(['cyan', 'bold'], 'file.js')} not found!`);

Truecolor

Ansis: hex() rgb()

styleText: Limited to 16 ANSI colors.

↑ top

Compatibility

Check the minimum version of your tool required for compatibility with the latest Ansis.

Supports:

• CJS: CommonJS module support.
• ESM: ECMAScript module support.
• FAUX: Fake or non-standard approach to module resolution (seen in swc).

Browser Compatibility for ANSI Codes

⭐️ Star History

If you find this useful, please ⭐️ the repo.

↑ top

License

ISC