Amazing CLIfor Terminal
API reference

API Reference

Complete API documentation for all public classes, functions, and types

Git2Docs Certified

Description

Chalk exposes a chainable style-builder API for wrapping strings in ANSI escape sequences. Import the default export for immediate use with auto-detected color support, or construct an isolated Chalk instance when you need explicit control over the color level — for example, when writing to a non-TTY stream or inside a reusable module. Every style property access and color method call returns a new, cached builder function; calling that builder with one or more string arguments produces the final styled string.


Parameters

new Chalk(options?)

ParameterTypeRequiredDescription
optionsOptionsNoConfiguration object for the new instance.
options.level0 | 1 | 2 | 3 | undefinedNoColor support level. 0 disables all colors, 1 enables basic 16-color support, 2 enables 256-color support, 3 enables Truecolor (16 million colors). Omit or pass undefined to auto-detect from the environment.

Style builder call signature

Every ChalkInstance (including the default export) is itself a callable. Once you have built up a chain of styles, call the final builder:

ParameterTypeRequiredDescription
...textunknown[]Yes (at least one)One or more values to style. Multiple arguments are joined with a single space.

Dynamic color methods

rgb(red, green, blue) / bgRgb(red, green, blue) / underlineRgb(red, green, blue)

ParameterTypeRequiredDescription
rednumberYesRed channel, 0–255.
greennumberYesGreen channel, 0–255.
bluenumberYesBlue channel, 0–255.

hex(color) / bgHex(color) / underlineHex(color)

ParameterTypeRequiredDescription
colorstringYesCSS-style hex string, e.g. '#DEADED'.

ansi256(index) / bgAnsi256(index) / underlineAnsi256(index)

ParameterTypeRequiredDescription
indexnumberYes8-bit color index, 0–255.

Returns

new Chalk(options?)

Returns a ChalkInstance — a callable function with every style property and color method attached to its prototype. The instance's level is set to the value supplied in options.level, or auto-detected from the environment when that option is omitted.

Style property access (e.g., .red, .bold, .bgBlue)

Returns a new builder function cached on the parent builder. It is never this; each access in a chain creates a distinct cached function at that step.

Dynamic color method call (e.g., .rgb(255, 0, 0), .hex('#FF0000'))

Returns a new builder function configured with the computed ANSI open/close pair for the specified color and the current color level.

Calling the final builder (e.g., chalk.red.bold('Hello'))

Returns a string containing the input text wrapped in the accumulated ANSI escape sequences. When level is 0, or the input is empty, the input is returned unstyled — except when visible is in the chain, in which case an empty string '' is returned instead (for example, new Chalk({ level: 0 }).visible('x') returns '').

supportsColor / supportsColorStderr

Each is either a ColorSupport object — { level: ColorSupportLevel, hasBasic: boolean, has256: boolean, has16m: boolean } — or false when no color support is detected. Always guard with a truthy check before reading .level.

chalkStderr

A separate ChalkInstance pre-configured with the color level detected for stderr instead of stdout.

Name arrays (modifierNames, foregroundColorNames, backgroundColorNames, underlineColorNames, colorNames)

Each is a readonly array of string literals representing every valid style name in that category. colorNames is the union of foregroundColorNames and backgroundColorNames; underline color names are kept in underlineColorNames separately.


Errors
ErrorCondition
Error: The \level` should be an integer from 0 to 3`Thrown by new Chalk({ level }) when level is not undefined and is not a safe integer in the range 0–3.
Error: The \level` should be an integer from 0 to 3`Thrown by the level setter on any ChalkInstance (including the default export) when you assign a value that is not a safe integer in the range 0–3.
ERR_REQUIRE_ESMThrown by Node.js itself when you call require('chalk') on a Node.js release earlier than 22.12. On Node.js ≥22.12 require('chalk') succeeds and returns the ES module namespace; access the default export via .default.

Examples

Basic styling

Import the default export and chain styles.

import chalk from 'chalk';

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

Chaining multiple styles

import chalk from 'chalk';

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

Multiple arguments (joined with spaces)

import chalk from 'chalk';

console.log(chalk.blue('Hello', 'World!', 'Foo', 'bar', 'biz', 'baz'));

Nesting styled strings

import chalk from 'chalk';

console.log(chalk.red('Hello', chalk.underline.bgBlue('world') + '!'));

Defining reusable theme helpers

Capture a partially-applied builder and reuse it like a function.

import chalk from 'chalk';

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

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

Using console.log string substitution

import chalk from 'chalk';

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

RGB and hex colors

import chalk from 'chalk';

console.log(chalk.rgb(123, 45, 67).underline('Underlined reddish color'));
console.log(chalk.hex('#DEADED').bold('Bold gray!'));

Background and underline color variants

import chalk from 'chalk';

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

// Underline colors only show when an underline style is also applied
console.log(chalk.underlineHex('#DEADED').underlineCurly('Hello, world!'));
console.log(chalk.underlineRgb(15, 100, 204).underline('Hello!'));

8-bit (ansi256) colors

import chalk from 'chalk';

console.log(chalk.ansi256(201)('Purple-ish text'));
console.log(chalk.bgAnsi256(194)('Honeydew, more or less'));

Creating an isolated Chalk instance

Use new Chalk({ level }) in a reusable module so you do not globally mutate the shared default instance.

import { Chalk } from 'chalk';

const noColorChalk = new Chalk({ level: 0 });
console.log(noColorChalk.red('This will not be styled'));

const truecolorChalk = new Chalk({ level: 3 });
console.log(truecolorChalk.hex('#FF8800').bold('Orange!'));

Configuring level after construction

import chalk from 'chalk';

chalk.level = 1; // Downgrade to basic 16-color support for this process

Inspecting color support at runtime

import { supportsColor, supportsColorStderr } from 'chalk';

if (supportsColor) {
  console.log(`stdout color level: ${supportsColor.level}`);
}

if (supportsColorStderr) {
  console.log(`stderr color level: ${supportsColorStderr.level}`);
}

Writing to stderr with chalkStderr

import { chalkStderr } from 'chalk';

process.stderr.write(chalkStderr.red('Something went wrong\n'));

Validating style names at runtime

import { modifierNames, foregroundColorNames } from 'chalk';

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

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

CommonJS interop (Node.js ≥22.12 only)

// Works only on Node.js >=22.12; throws ERR_REQUIRE_ESM on earlier 22.x releases.
const chalkModule = require('chalk');
const chalk = chalkModule.default;

console.log(chalk.green('CommonJS interop'));

Tagged template literals — use chalk-template instead

Core chalk does not support tagged template literal interpolation. The following produces incorrect output:

// ❌ Wrong — values are misplaced, not interpolated correctly
chalk.green`Hello ${name}`;

Use the chalk-template package for tagged template literal support:

// ✅ Correct — install chalk-template separately
import chalkTemplate from 'chalk-template';

console.log(chalkTemplate`{green Hello {bold ${name}}}`);

Notes

Builder functions are cached, not shared

Accessing a style property such as chalk.red returns a new builder function the first time, then caches it on the parent builder. It never returns this. This means new Chalk({ level: 1 }).red === instance is false. Each link in a chain is a distinct function object.


Chaining conflicting styles

When you chain more than one style of the same type (for example, two foreground colors), all ANSI open codes are emitted in the output string. Because later codes open after earlier ones, only the last conflicting style is visually applied. For example, chalk.yellow.red renders red text, while chalk.red.yellow renders yellow text.


Multiple arguments vs. template literals

Calling chalk.red('a', 'b', 'c') joins the arguments with spaces: the result is the same as chalk.red('a b c'). This is entirely different from tagged template literal syntax — which core chalk does not support. To interpolate values in a template, call the builder as a regular function inside the template expression:

console.log(`CPU: ${chalk.red('90%')}`);

Environment-variable overrides

The vendored supports-color module reads several environment signals in priority order:

  • FORCE_COLOR — A numeric value (0–3) sets the level directly, capped at 3. FORCE_COLOR=true (or an empty string) enables color at level 1 or above. FORCE_COLOR overrides --no-color; it does not override --color=256 or --color=16m.
  • --color=16m and --color=256 CLI flags — Enable Truecolor (level 3) and 256-color (level 2) respectively, and take precedence over a non-zero numeric FORCE_COLOR.
  • --color and --no-color CLI flags — Enable or disable color at the detected terminal level. FORCE_COLOR overrides --no-color.
  • TERM, COLORTERM, and CI-related variables — Inspected for additional color-level hints.

Chalk does not read or respect NO_COLOR.


Underline colors require an underline style

Underline color methods (underlineRed, underlineHex, etc.) only produce visible output when an underline style modifier (underline, underlineCurly, underlineDotted, etc.) is also present in the chain. At level 1, underline colors are downsampled to the first 16 palette entries rather than to a basic color code.


Color downsampling

When a terminal supports fewer colors than a method requests, chalk automatically downsamples. For example, chalk.ansi256(196) becomes ANSI escape 91 (bright red) at level 1, and chalk.bgAnsi256(196) becomes 101 at level 1.


Browser environments

In non-Node runtimes (bundled browser code), chalk resolves source/vendor/supports-color/browser.js via the default export condition in package.json. That module inspects the Chromium brand version: a brand version above 93 receives level 3; any other Chrome or Chromium user agent receives level 1; a non-Chromium browser or an environment with no navigator object receives level 0. Since Chrome 69, ANSI escape codes are natively supported in the developer console.


No runtime dependencies

Chalk has no npm dependencies. ansi-styles and supports-color are vendored under source/vendor/ and imported internally via the #ansi-styles and #supports-color import-map aliases. Your dependency graph is not affected.


Deprecated exports

The following exports exist for backward compatibility and will be removed in a future major version. Prefer the non-deprecated equivalents.

Deprecated exportPreferred replacement
modifiersmodifierNames
foregroundColorsforegroundColorNames
backgroundColorsbackgroundColorNames
colorscolorNames
Type ModifiersType ModifierName
Type ForegroundColorType ForegroundColorName
Type BackgroundColorType BackgroundColorName
Type ColorType ColorName