// 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

💡 Features

⚖️ Alternatives

Install

npm install ansis

Usage

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

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

Chained syntax

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

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

Template literals

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

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

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

↑ top

ANSI Styles

ANSI 16 colors

ANSI 256 colors

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

Fallback

Truecolor

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`;

Fallback

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

↑ top

Named truecolors

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

Warning

For extended styles, create a new Ansis instance and call extend() on it.

Tip

For all CSS named colors use css-color-names package.

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

Tip

Need help picking a color name? Try the Name that Color tool - paste a hex and get its closest color name.

Hyperlink

import { blue, link } from 'ansis';

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

Important

Call link() last in the chain:

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

Warning

In unsupported terminals text is shown without a link.

↑ top

Color support

import ansis from 'ansis';

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

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

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

Auto-detection

Environment & CLI options

Note

Priority order, from lowest to highest:

1. auto-detection
2. NO_COLOR
3. CLI color flags
4. FORCE_COLOR

Environment variables

NO_COLOR

NO_COLOR=1 node app.js

FORCE_COLOR

Important

Ansis differs from the original force-color.org rule in a few cases:

• FORCE_COLOR=0 disables colors.
  This matches Node.js, but the original force-color.org rule enables colors when the value is a non-empty string, regardless of the actual value.

• FORCE_COLOR=true and an empty value enable colors.
  This matches Node.js, but the original force-color.org rule ignores an empty string.

TERM

COLORTERM

CLI flags

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

Note

If multiple CLI color flags are present, the last one wins:

• --color --no-color -> --no-color
• --no-color --color -> --color

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.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

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

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:

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()

Where it works

Performance

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

Color support detection

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

↑ top

Compatibility

Browser Compatibility for ANSI Codes

Warning

Firefox doesn't natively support ANSI codes in the developer console.

⭐️ Star History

↑ top

License