API Reference
Complete API documentation for all public classes, functions, and types
Git2Docs CertifiedChalk 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.
new Chalk(options?)
| Parameter | Type | Required | Description |
|---|---|---|---|
options | Options | No | Configuration object for the new instance. |
options.level | 0 | 1 | 2 | 3 | undefined | No | Color 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:
| Parameter | Type | Required | Description |
|---|---|---|---|
...text | unknown[] | 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)
| Parameter | Type | Required | Description |
|---|---|---|---|
red | number | Yes | Red channel, 0–255. |
green | number | Yes | Green channel, 0–255. |
blue | number | Yes | Blue channel, 0–255. |
hex(color) / bgHex(color) / underlineHex(color)
| Parameter | Type | Required | Description |
|---|---|---|---|
color | string | Yes | CSS-style hex string, e.g. '#DEADED'. |
ansi256(index) / bgAnsi256(index) / underlineAnsi256(index)
| Parameter | Type | Required | Description |
|---|---|---|---|
index | number | Yes | 8-bit color index, 0–255. |
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.
| Error | Condition |
|---|---|
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_ESM | Thrown 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. |
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}}}`);
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_COLORoverrides--no-color; it does not override--color=256or--color=16m.--color=16mand--color=256CLI flags — Enable Truecolor (level 3) and 256-color (level 2) respectively, and take precedence over a non-zero numericFORCE_COLOR.--colorand--no-colorCLI flags — Enable or disable color at the detected terminal level.FORCE_COLORoverrides--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 export | Preferred replacement |
|---|---|
modifiers | modifierNames |
foregroundColors | foregroundColorNames |
backgroundColors | backgroundColorNames |
colors | colorNames |
Type Modifiers | Type ModifierName |
Type ForegroundColor | Type ForegroundColorName |
Type BackgroundColor | Type BackgroundColorName |
Type Color | Type ColorName |