Core Concepts

This page explains the mental model behind Chalk before you write a single line of code. Understanding how styles compose, how chaining works, how nesting resets correctly, and how Chalk decides whether to emit color at all will help you use the library confidently and avoid surprises in CI pipelines, log files, or restricted terminal environments. None of these mechanics require you to learn ANSI escape codes directly — Chalk handles all of that for you.

Styles Are Composable Functions That Return Strings

At its core, Chalk exposes a single chainable builder object — the default chalk export — whose properties are style methods. When you call a style method with a string argument, you get back a plain JavaScript string wrapped in the appropriate ANSI escape codes. That string can be passed directly to console.log, concatenated with other strings, or stored in a variable for later use.

Because the result is always a plain string, you never need to "unwrap" anything. You can assign a partially-applied chain to a variable and reuse it as a theme:

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

Calling error('Something went wrong') later produces the same result as calling chalk.bold.red('Something went wrong') inline. There is no mutable state attached to the styled string itself.

Important: Chalk does not extend String.prototype. Styled strings are ordinary JavaScript strings — they carry no special methods or Chalk-specific properties.

ANSI Escape Codes

When a terminal displays colored or styled text, it is interpreting special sequences of characters — ANSI escape codes — embedded in the string. These sequences begin with the ESC character (\u001B) followed by additional bytes that instruct the terminal to switch colors, apply bold, reset styling, and so on. They are never displayed literally; the terminal consumes them as control instructions.

Chalk generates all of these codes for you automatically based on the style methods you chain. You never need to write or know the raw sequences. However, understanding that they exist explains two important behaviors:

• Why styled strings look longer in a debugger — the extra characters are the escape sequences.
• Why ANSI codes do not render in browser consoles — browser DevTools do not speak the terminal ANSI protocol, so the raw escape characters appear as literal text. Chalk is designed exclusively for Node.js terminal environments.

Chaining: Applying Multiple Styles at Once

Chalk's API is a fluent, chainable builder. You stack style property accesses one after another, and each access returns a new builder that includes all styles accumulated so far. The final call in the chain — the one that passes a string argument — applies every accumulated style to that string.

chalk.red.bold.underline('Alert!')

Order within a chain generally does not matter for independent styles like color and bold. When two properties of the same category conflict (for example, two foreground colors), the rightmost one wins — chalk.red.yellow.green is equivalent to chalk.green.

Styles are applied left-to-right in the sense that they are all collected before any string is processed. There is no intermediate styled string produced at each step in the chain.

Nesting: Composing Styles Within Styles

You can pass a Chalk-styled string as an argument to another Chalk call. When an inner styled region ends, Chalk automatically re-opens the outer styling so the surrounding text resumes its original appearance. You do not need to manually reset and re-apply anything.

chalk.green(
  'I am green, ' +
  chalk.blue.bold('this part is blue and bold') +
  ', and I am green again.'
)

Chalk achieves this by scanning the string for any existing ESC sequences and re-inserting the enclosing style's open code wherever an inner close code appears. This means nesting works correctly even for same-category properties (for example, a blue substring inside a green string).

Chalk also handles multi-line strings: it closes the active styling before each newline and re-opens it on the next line. This prevents style bleed on macOS and other terminals where styles do not automatically reset at a line boundary.

Modifiers: Changing Appearance Without Changing Color

Modifiers are style properties that alter text appearance independently of color. They include:

Modifiers chain freely with color and background-color methods.

256-Color Mode and True Color

Chalk supports three tiers of extended color beyond the basic 16-color palette:

256-color mode gives you access to a palette of 256 indexed colors, supported by most terminal emulators. You select a color by its index:

chalk.ansi256(214)('Orange-ish text')
chalk.bgAnsi256(194)('Honeydew background')

True color (16-million color) lets you specify any color as red, green, and blue components, or as a CSS hex string. Most modern terminals support this:

chalk.rgb(123, 45, 67)('Custom reddish')
chalk.hex('#DEADED')('Lavender-gray')
chalk.bgRgb(15, 100, 204)('Blue background')
chalk.bgHex('#FF8800')('Orange background')

Background variants of all extended color methods are prefixed with bg and the model name is capitalized: bgRgb, bgHex, bgAnsi256.

Color Level Detection and Graceful Degradation

Chalk reads the terminal environment at startup and sets a color level — an integer from 0 to 3 — that governs which ANSI codes it emits:

When a color you specify exceeds what the terminal supports, Chalk downgrades automatically. For example, an rgb(255, 0, 0) call on a level-1 terminal is mapped to the nearest ANSI 16-color equivalent (red, 31) rather than emitting unsupported codes. You write the same code for all environments; Chalk handles the translation.

You can override detection using environment variables:

• FORCE_COLOR=0 — disables color entirely regardless of terminal
• FORCE_COLOR=1 — forces level 1 (basic 16 colors)
• FORCE_COLOR=2 — forces level 2 (256 colors)
• FORCE_COLOR=3 — forces level 3 (true color)

These variables are useful in CI pipelines or scripts where terminal detection may not reflect your intent.

You can also read or set chalk.level directly in your own application code. Because this property is global to the chalk object, you should not mutate it inside a reusable library or module — doing so would affect every other consumer of the same chalk instance in the process.

Chalk Instances: Isolating Color Level

When you are writing a library, a plugin, or a test suite where you cannot control the ambient terminal environment, you should create a Chalk instance using the named Chalk constructor. This gives you an isolated copy of Chalk with a fixed color level that is never affected by global mutations:

import { Chalk } from 'chalk';

const customChalk = new Chalk({ level: 0 }); // always plain text

This pattern is also useful in tests where you want to assert on string content without ANSI codes interfering with your assertions.

Important: new chalk.Instance() was removed in Chalk 5. Always use the named Chalk export — import { Chalk } from 'chalk' — and call new Chalk({ level: n }).

Template Literal Tags

A template literal tag is a JavaScript feature that lets you preprocess a template string. In earlier versions of Chalk, a tagged template syntax was built in — for example chalk`Hello {red world}` — allowing you to style only portions of a longer string without splitting it into multiple calls.

This syntax was removed in Chalk 5. If your project relies on tagged template literals, install the separate chalk-template package, which provides this functionality as a dedicated module and is the supported migration path.

CommonJS Projects

Chalk 5 is ESM-only. Calling require('chalk') in a CommonJS project throws a runtime error. If you cannot migrate your project to ESM, pin to chalk@4, which supports CommonJS and remains a stable, well-maintained release.

Applying a single style

import chalk from 'chalk';

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

Hello world!   ← rendered in blue

Chaining multiple styles

import chalk from 'chalk';

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

Hello world!   ← blue text, red background, bold

Nesting styles (inner style resets correctly)

import chalk from 'chalk';

console.log(
  chalk.green(
    'I am a green line ' +
    chalk.blue.underline.bold('with a blue substring') +
    ' that becomes green again!'
  )
);

I am a green line with a blue substring that becomes green again!
↑ green          ↑ blue + underline + bold  ↑ green resumes

Defining reusable themes

import chalk from 'chalk';

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

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

Error!     ← bold red
Warning!   ← orange

Using 256-color mode

import chalk from 'chalk';

console.log(chalk.ansi256(214)('256-color orange'));
console.log(chalk.bgAnsi256(194)('Honeydew background'));

256-color orange    ← foreground color index 214
Honeydew background ← background color index 194

Using true color (RGB and hex)

import chalk from 'chalk';

console.log(chalk.rgb(123, 45, 67).underline('Underlined reddish color'));
console.log(chalk.hex('#DEADED').bold('Bold lavender-gray!'));
console.log(chalk.bgRgb(15, 100, 204).inverse('Blue background, inverted'));

Underlined reddish color   ← RGB foreground + underline
Bold lavender-gray!        ← hex foreground + bold
Blue background, inverted  ← RGB background + inverted colors

Creating an isolated Chalk instance for a library

import { Chalk } from 'chalk';

// Level 0: always plain text, safe for testing or restricted environments
const plainChalk = new Chalk({ level: 0 });

console.log(plainChalk.red('This will not be red — color is disabled'));

This will not be red — color is disabled

Mixing styled and plain strings in a template literal

import chalk from 'chalk';

const cpu  = 90;
const ram  = 40;
const disk = 70;

console.log(`
CPU:  ${chalk.red(`${cpu}%`)}
RAM:  ${chalk.green(`${ram}%`)}
DISK: ${chalk.yellow(`${disk}%`)}
`);

CPU:  90%    ← red
RAM:  40%    ← green
DISK: 70%    ← yellow

Forcing color level via environment variable

# Disable color output regardless of terminal support
FORCE_COLOR=0 node my-script.js

# Force true color even in a dumb terminal
FORCE_COLOR=3 node my-script.js

• API Reference — Complete listing of all style methods, color functions (rgb, hex, ansi256), background variants, and the chalk.level property.
• Custom Chalk Instances — How to use new Chalk({ level }) to create isolated instances safe for libraries and test suites.
• Color Level and Environment Detection — Deep dive into how Chalk reads terminal capabilities, what FORCE_COLOR does, and how chalkStderr provides a separate instance for the stderr stream.
• Migrating from Chalk 4 to Chalk 5 — Covers the ESM-only change, removal of the tagged template syntax (use chalk-template), and the removal of new chalk.Instance().
• chalk-template — The standalone package that restores tagged-template-literal support (chalk`{red foo}`) for Chalk 5 projects.