Termchalk

A modern terminal text styling library for Node.js.

Info

• ESM-first package for modern Node.js projects
• Composable API designed for readability and predictable output
• Supports basic ANSI, 256 colors, and Truecolor

Highlights

• Expressive API
• Highly performant
• No dependencies
• Nested and chainable styles
• 256/Truecolor color support
• Auto-detects color support
• Does not extend String.prototype
• Clean and focused

Install

npm install termchalk

Note: This package is ESM-only.

Usage

import chalk from 'termchalk';

console.log(chalk.blue('Hello world!'));

Termchalk provides a composable API for chaining and nesting styles.

import chalk from 'termchalk';

const log = console.log;

// Combine styled and normal strings
log(chalk.blue('Hello') + ' World' + chalk.red('!'));

// Compose multiple styles using the chainable API
log(chalk.blue.bgRed.bold('Hello world!'));

// Pass in multiple arguments
log(chalk.blue('Hello', 'World!', 'Foo', 'bar', 'biz', 'baz'));

// Nest styles
log(chalk.red('Hello', chalk.underline.bgBlue('world') + '!'));

// Nest styles of the same type even (color, underline, background)
log(chalk.green(
	'I am a green line ' +
	chalk.blue.underline.bold('with a blue substring') +
	' that becomes green again!'
));

// ES2015 template literal
log(`
CPU: ${chalk.red('90%')}
RAM: ${chalk.green('40%')}
DISK: ${chalk.yellow('70%')}
`);

// Use RGB colors in terminal emulators that support it.
log(chalk.rgb(123, 45, 67).underline('Underlined reddish color'));
log(chalk.hex('#DEADED').bold('Bold gray!'));

Easily define your own themes:

import chalk from 'termchalk';

const error = chalk.bold.red;
const warning = chalk.hex('#FFA500'); // Orange color

console.log(error('Error!'));
console.log(warning('Warning!'));

Take advantage of console.log string substitution:

import chalk from 'termchalk';

const name = 'Sindre';
console.log(chalk.green('Hello %s'), name);
//=> 'Hello Sindre'

API

chalk.<style>[.<style>...](string, [string...])

Example: chalk.red.bold.underline('Hello', 'world');

Chain styles and call the last one as a method with string arguments. Order does not matter, and later styles take precedence in case of conflicts. For example, chalk.red.yellow.green is equivalent to chalk.green.

Multiple arguments are separated by spaces.

chalk.level

Specifies the level of color support.

Color support is automatically detected, but you can override it by setting the level property. You should generally do this only in your own application code, as it applies globally to consumers of the same instance.

If you need to change this in a reusable module, create a new instance:

import {Chalk} from 'termchalk';

const customChalk = new Chalk({level: 0});

| Level | Description | | :---: | :--- | | 0 | All colors disabled | | 1 | Basic color support (16 colors) | | 2 | 256 color support | | 3 | Truecolor support (16 million colors) |

supportsColor

Detect whether the terminal supports color. This is handled internally and also exposed for convenience.

Color support can be overridden with --color and --no-color. If CLI flags are unavailable, use FORCE_COLOR=1 (level 1), FORCE_COLOR=2 (level 2), FORCE_COLOR=3 (level 3), or FORCE_COLOR=0 to disable color. FORCE_COLOR overrides other color support checks.

Explicit 256/Truecolor mode can be enabled using the --color=256 and --color=16m flags, respectively.

chalkStderr and supportsColorStderr

chalkStderr contains a separate instance configured with color support detected for stderr instead of stdout. Override rules from supportsColor apply here as well. supportsColorStderr is exposed for convenience.

modifierNames, foregroundColorNames, backgroundColorNames, and colorNames

All supported style names are exposed as arrays. colorNames combines foregroundColorNames and backgroundColorNames.

This is useful when wrapping Termchalk and validating style input:

import {modifierNames, foregroundColorNames} from 'termchalk';

console.log(modifierNames.includes('bold'));
//=> true

console.log(foregroundColorNames.includes('pink'));
//=> false

Styles

Modifiers

• reset - Reset the current style.
• bold - Make the text bold.
• dim - Make the text have lower opacity.
• italic - Make the text italic. (Not widely supported)
• underline - Put a horizontal line below the text. (Not widely supported)
• overline - Put a horizontal line above the text. (Not widely supported)
• inverse - Invert background and foreground colors.
• hidden - Print the text but make it invisible.
• strikethrough - Puts a horizontal line through the center of the text. (Not widely supported)
• visible - Print text only when Termchalk has a color level above zero. Useful for cosmetic output.

Colors

• black
• red
• green
• yellow
• blue
• magenta
• cyan
• white
• blackBright (alias: gray, grey)
• redBright
• greenBright
• yellowBright
• blueBright
• magentaBright
• cyanBright
• whiteBright

Background colors

• bgBlack
• bgRed
• bgGreen
• bgYellow
• bgBlue
• bgMagenta
• bgCyan
• bgWhite
• bgBlackBright (alias: bgGray, bgGrey)
• bgRedBright
• bgGreenBright
• bgYellowBright
• bgBlueBright
• bgMagentaBright
• bgCyanBright
• bgWhiteBright

256 and Truecolor color support

Termchalk supports 256 colors and Truecolor (16 million colors) on compatible terminal applications.

Colors are downsampled from 16 million RGB values to an ANSI format supported by the current terminal (or controlled with {level: n}). For example, at level 1 (basic color support), RGB #FF0000 maps to ANSI red (31).

Examples:

• chalk.hex('#DEADED').underline('Hello, world!')
• chalk.rgb(15, 100, 204).inverse('Hello!')

Background versions of these models are prefixed with bg and the first level of the module capitalized (e.g. hex for foreground colors and bgHex for background colors).

• chalk.bgHex('#DEADED').underline('Hello, world!')
• chalk.bgRgb(15, 100, 204).inverse('Hello!')

The following color models can be used:

• rgb - Example: chalk.rgb(255, 136, 0).bold('Orange!')
• hex - Example: chalk.hex('#FF8800').bold('Orange!')
• ansi256 - Example: chalk.bgAnsi256(194)('Honeydew, more or less')

Browser support

Since Chrome 69, ANSI escape codes are natively supported in the developer console.

Windows

On Windows, prefer Windows Terminal over cmd.exe for better ANSI support.

FAQ

Why not switch to a smaller coloring package?

Smaller packages can be a good fit for some projects. Termchalk prioritizes API ergonomics, broad style support, and a familiar developer experience. If your primary goal is minimal footprint, consider yoctocolors.

But the smaller coloring package has benchmarks showing it is faster

Micro-benchmarks can be misleading because they often measure isolated scenarios that do not represent full application behavior. In real CLI applications, readability and maintainability usually matter more than small differences in style-rendering speed.

Related

• chalk-template - Tagged template literals support for this module
• chalk-cli - CLI for this module
• ansi-styles - ANSI escape codes for styling strings in the terminal
• supports-color - Detect whether a terminal supports color
• strip-ansi - Strip ANSI escape codes
• strip-ansi-stream - Strip ANSI escape codes from a stream
• has-ansi - Check if a string has ANSI escape codes
• ansi-regex - Regular expression for matching ANSI escape codes
• wrap-ansi - Wordwrap a string with ANSI escape codes
• slice-ansi - Slice a string with ANSI escape codes
• color-convert - Converts colors between different models
• chalk-animation - Animate strings in the terminal
• gradient-string - Apply color gradients to strings
• chalk-pipe - Create chalk style schemes with simpler style strings
• terminal-link - Create clickable links in the terminal

(No additional entries at this time.)

Maintainers

• Maintained by project contributors