API Reference

The Chalk API provides a chainable interface for styling terminal output strings in Node.js applications. Use it to apply colors, background colors, and text decorations (such as bold or underline) to strings printed to the terminal. Chalk automatically detects color support in the current environment and degrades gracefully when the terminal does not support a requested color level.

Chalk's primary interface is property-based and chainable rather than function-parameter-based. The table below documents the key style properties and configuration options available on a chalk instance.

Built-in style properties (chainable)

Every style property and method in a chain returns a Chalk instance until the chain is terminated by calling it as a function with one or more string arguments. At that point, Chalk returns a string containing the original input wrapped in the appropriate ANSI escape codes.

• When chalk.level is 0, the returned string is identical to the input — no escape codes are added. This lets you safely use Chalk in non-TTY environments without conditional logic.
• When multiple strings are passed to the terminal call (e.g., chalk.red('Hello', 'World')), they are concatenated with no separator and returned as a single styled string.
• chalk.visible returns an empty string ('') when chalk.level is 0, because it is specifically designed to suppress output in color-disabled environments.
• new chalk.Instance(options) returns a new, independent Chalk instance that does not share state with the default export.

Chalk is designed to fail silently in most cases (for example, by ignoring unsupported color codes or downgrading color depth). However, the following errors can occur:

Apply a single foreground color

import chalk from 'chalk';

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

Expected output (in a color-capable terminal):

Hello, world!   ← rendered in blue

Chain multiple styles

Chain properties left to right. Each property in the chain is applied to the final string.

import chalk from 'chalk';

console.log(chalk.bold.underline.red('Critical error'));

Expected output:

Critical error   ← bold, underlined, and red

Combine foreground color and background color

import chalk from 'chalk';

console.log(chalk.black.bgYellow('Warning'));

Expected output:

Warning   ← black text on a yellow background

Use with template literals

Template literals let you embed styled fragments inline within a larger string without breaking the surrounding context.

import chalk from 'chalk';

const fileName = 'app.js';
const lineNumber = 42;

console.log(`Error in ${chalk.cyan(fileName)} at line ${chalk.yellow(lineNumber)}`);

Expected output:

Error in app.js at line 42   ← filename in cyan, line number in yellow

Apply a Truecolor (16 million colors) using RGB

Truecolor requires chalk.level >= 3. In auto-detected environments that support it, this is set automatically.

import chalk from 'chalk';

console.log(chalk.rgb(255, 136, 0)('Custom orange text'));

Expected output:

Custom orange text   ← rendered in RGB(255, 136, 0) orange

Apply a Truecolor using a hex value

import chalk from 'chalk';

console.log(chalk.hex('#FF8800')('Hex orange text'));

Expected output:

Hex orange text   ← rendered in #FF8800 orange

Use 256-color ANSI codes

import chalk from 'chalk';

console.log(chalk.ansi256(214)('256-color orange'));

Expected output:

256-color orange   ← rendered in ANSI 256 color code 214

Create an isolated instance with a fixed color level

Useful when writing tests or libraries where you need predictable, environment-independent output.

import chalk from 'chalk';

const chalkForced = new chalk.Instance({ level: 3 });

console.log(chalkForced.green('Always green, regardless of terminal support'));

Expected output:

Always green, regardless of terminal support   ← styled with forced level 3

Disable all styling for non-TTY output

Set chalk.level = 0 to strip all ANSI codes — for example, when writing to a log file.

import chalk from 'chalk';

chalk.level = 0;

console.log(chalk.red('This will be plain text'));

Expected output:

This will be plain text   ← no ANSI codes

Auto-detection of color support By default, Chalk inspects environment variables (NO_COLOR, FORCE_COLOR, TERM, COLORTERM) and the TTY status of process.stdout to determine chalk.level at startup. You do not need to configure this manually for interactive terminals. Setting FORCE_COLOR=1, FORCE_COLOR=2, or FORCE_COLOR=3 in your environment forces Chalk to a specific level, which is useful in CI pipelines.

Modifying chalk.level on the default export is global Changing chalk.level directly on the default export affects all code that shares the same module instance. Use new chalk.Instance({ level }) to create a scoped instance when you need isolated behavior — for example, in a library you are distributing.

chalk.visible behaves differently at level 0 Unlike other style properties, chalk.visible returns an empty string when chalk.level === 0. Use it when you want content to appear only in color-capable terminals.

Nesting styled strings Chalk handles nested styles correctly. Wrapping one styled string inside another restores the outer style after the inner one ends. You do not need to manually manage escape code resets:

console.log(chalk.red(`red ${chalk.bold('bold red')} red again`));

ESM and CommonJS compatibility Chalk's default export supports both import chalk from 'chalk' (ESM) and const chalk = require('chalk') patterns, but check the version you are using — major versions have differing module format defaults. Consult the changelog if you encounter import errors.

Performance considerations Chalk styles are computed at call time. In hot paths such as tight loops logging thousands of lines, consider building styled string templates outside the loop and reusing them to minimize repeated property chain traversal.