Configuration
Client initialization, authentication, default options
Git2Docs CertifiedThis page explains how to install Chalk, configure its color level, and initialize instances for use in your Node.js or browser-bundled application. Chalk is an ESM-only library that wraps terminal output strings in ANSI escape sequences, automatically detecting the host terminal's color capability at runtime. Understanding initialization matters because color level affects every styled string your application produces — getting it wrong silently strips all color or applies escape codes a terminal cannot render. The two primary paths covered here are using the pre-configured default export and creating isolated Chalk instances with explicit color-level settings via the Chalk constructor.
Before you begin, ensure your environment meets the following requirements:
- Node.js ≥ 22 — Chalk's package declares
>=22and CI tests against Node 22 and 26 only. Earlier versions are not tested. - ESM-compatible project — Chalk is ESM-only. There is no CommonJS build, so your project must use
"type": "module"inpackage.json, or a bundler configured to consume ES modules. - npm, pnpm, or yarn — any of these package managers can install Chalk.
-
Ensure you are running Node.js ≥ 22. Chalk is tested on Node 22 and Node 26 in CI.
-
Install Chalk into your project using your preferred package manager:
npm
npm install chalkpnpm
pnpm add chalkyarn
yarn add chalk -
Because Chalk is ESM-only, your project must import it with
import, notrequire. If yourpackage.jsondoes not already declare"type": "module", either add it or use the.mjsextension for the files that import Chalk.{ "type": "module" }CommonJS note: On Node.js ≥ 22.12,
require('chalk')loads the ES module successfully. Access the default export via.default(e.g.const chalk = require('chalk').default). On earlier Node 22 releases,require('chalk')throwsERR_REQUIRE_ESM. -
Chalk has no runtime dependencies.
ansi-stylesandsupports-colorare vendored internally, so no additional packages are installed into yournode_modules.
Color level (level)
The central configuration knob in Chalk is the color level, an integer from 0 to 3 that controls which ANSI escape sequences are emitted.
| Level | Description |
|---|---|
0 | All colors disabled — plain strings are returned as-is |
1 | Basic 16-color support |
2 | 256-color support |
3 | Truecolor (16 million colors) support |
Setting any value outside this range — or a non-integer — throws an error.
Automatic detection (default behavior)
When you use the default chalk export, the level is detected automatically at module load time by inspecting the runtime environment. You do not need to set anything for typical use.
Overriding detection with environment variables
You can force a specific level without changing code:
| Variable / Flag | Effect |
|---|---|
FORCE_COLOR=0 | Disable all color (level 0) |
FORCE_COLOR=1 | Enable basic color (level 1) |
FORCE_COLOR=2 | Enable 256-color (level 2) |
FORCE_COLOR=3 | Enable Truecolor (level 3) |
FORCE_COLOR=true or FORCE_COLOR= (empty) | Enable color at level 1 or above; actual level is still detected from the terminal |
--no-color flag | Disable all color |
--color flag | Enable basic color |
--color=256 flag | Enable 256-color mode |
--color=16m flag | Enable Truecolor mode |
Numeric FORCE_COLOR sets the level directly and is capped at 3. The flags --color=256 and --color=16m take precedence over a non-zero numeric FORCE_COLOR.
Setting level on the default instance
You can reassign chalk.level at runtime, but this applies globally to every consumer of the default export in the same process. Prefer creating an isolated instance instead:
import chalk from 'chalk';
// Global override — affects all code using the default export
chalk.level = 1;
Creating an isolated instance with new Chalk({ level })
The Chalk constructor accepts an Options object with one field:
level(0 | 1 | 2 | 3 | undefined) — The color level for this instance. Omit it, or passundefined, to have the level auto-detected from the environment. Throws if the value is notundefinedand not an integer from 0 to 3.
This is the recommended approach whenever you need per-stream or per-context control, or are writing a reusable module that should not alter global state:
import { Chalk } from 'chalk';
const noColorChalk = new Chalk({ level: 0 }); // always plain text
const basicChalk = new Chalk({ level: 1 }); // 16-color output
const chalk256 = new Chalk({ level: 2 }); // 256-color output
const trueChalk = new Chalk({ level: 3 }); // Truecolor output
const autoChalk = new Chalk(); // level auto-detected
chalkStderr
Chalk exports a second pre-configured instance, chalkStderr, whose color level is detected from stderr instead of stdout. Use it when writing diagnostic output to process.stderr:
import { chalkStderr } from 'chalk';
process.stderr.write(chalkStderr.red('Fatal error\n'));
Browser environments
When Chalk is used in a browser bundle, the default condition in the package exports selects a browser-specific color detector that inspects the Chromium brand version instead of terminal flags:
- Chromium brand version > 93 → level 3 (Truecolor)
- Any other Chrome/Chromium user agent → level 1
- No
navigator, or a non-Chromium browser → level 0
Since Chrome 69, ANSI escape codes are natively supported in the developer console, so level 3 output renders correctly in modern Chromium-based DevTools.
Import the default instance
For most scripts and CLI tools, import the default chalk export and start chaining styles immediately. No initialization code is required — the color level is auto-detected.
import chalk from 'chalk';
console.log(chalk.blue('Hello world!'));
Chain styles
Styles are chainable properties. Call the last property in the chain as a function, passing one or more strings. Multiple arguments are joined with a space.
import chalk from 'chalk';
console.log(chalk.blue.bgRed.bold('Hello world!'));
console.log(chalk.blue('Hello', 'World!', 'Foo', 'bar'));
Define reusable style themes
Because a chalk chain without a final call returns a function, you can assign partial chains to variables and reuse them:
import chalk from 'chalk';
const error = chalk.bold.red;
const warning = chalk.hex('#FFA500');
console.log(error('Error!'));
console.log(warning('Warning!'));
Use an isolated instance for reusable modules
If your module is consumed by other packages, never mutate the global chalk.level. Create an isolated instance instead:
import { Chalk } from 'chalk';
const chalk = new Chalk({ level: 2 }); // 256-color, isolated
console.log(chalk.green('Module output'));
Interpolate values in template literals (standard ES syntax)
Chalk's chainable builder returns a function, so you can use standard ES template literals with ${} interpolation — just call the chalk style as a function inside the expression:
import chalk from 'chalk';
const cpuUsage = '90%';
console.log(`CPU: ${chalk.red(cpuUsage)}`);
Important: Do not use chalk as a tagged template literal (e.g.
chalk.red\text`). The core library does not support tagged template literal interpolation. If you need tagged template literal syntax with${}interpolation, install the separate [chalk-template`](https://github.com/chalk/chalk-template) package.
Write to stderr with chalkStderr
import { chalkStderr } from 'chalk';
process.stderr.write(chalkStderr.yellow('Warning: retrying...\n'));
Disable color output programmatically
import { Chalk } from 'chalk';
const plainChalk = new Chalk({ level: 0 });
console.log(plainChalk.red('This will have no color'));
Basic colored output
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!'));
Combining styled and plain strings
import chalk from 'chalk';
console.log(chalk.blue('Hello') + ' World' + chalk.red('!'));
Multiple arguments (space-joined)
import chalk from 'chalk';
console.log(chalk.blue('Hello', 'World!', 'Foo', 'bar', 'biz', 'baz'));
Nested styles
import chalk from 'chalk';
console.log(chalk.red('Hello', chalk.underline.bgBlue('world') + '!'));
Reusable theme definitions
import chalk from 'chalk';
const error = chalk.bold.red;
const warning = chalk.hex('#FFA500');
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'
Truecolor with 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 gray!'));
Isolated instance with explicit color level
import { Chalk } from 'chalk';
const customChalk = new Chalk({ level: 0 });
console.log(customChalk.red('This will not be red'));
Validating style names with exported name arrays
import { modifierNames, foregroundColorNames } from 'chalk';
console.log(modifierNames.includes('bold'));
//=> true
console.log(foregroundColorNames.includes('pink'));
//=> false
Underline color (requires an underline modifier)
import chalk from 'chalk';
console.log(chalk.underlineHex('#DEADED').underlineCurly('Hello, world!'));
Background color methods
import chalk from 'chalk';
console.log(chalk.bgHex('#DEADED').underline('Hello, world!'));
console.log(chalk.bgRgb(15, 100, 204).inverse('Hello!'));
ERR_REQUIRE_ESM when calling require('chalk')
Symptom: Your CommonJS file throws Error [ERR_REQUIRE_ESM]: require() of ES Module … not supported.
Cause: You are running Node.js 22 but on a release earlier than 22.12. Those releases cannot require() an ES module.
Fix: Upgrade to Node.js ≥ 22.12, or convert the importing file to ESM (import chalk from 'chalk'). On Node.js ≥ 22.12, require('chalk') works and returns the ES module namespace; access the default export with .default:
const chalk = require('chalk').default;
No color appears in output
Symptom: Terminal output contains no ANSI color — strings appear plain.
Cause (1): The detected color level is 0. This happens when stdout is not a TTY (e.g. the output is piped), when FORCE_COLOR=0 is set, or when --no-color is passed.
Fix: Force a level with an environment variable:
FORCE_COLOR=1 node your-script.js
# or
FORCE_COLOR=3 node your-script.js # Truecolor
Or use the --color flag:
node your-script.js --color
Cause (2): A Chalk instance was constructed with { level: 0 }.
Fix: Remove the explicit level or set it to the appropriate value:
import { Chalk } from 'chalk';
const chalk = new Chalk({ level: 3 });
Tagged template literal produces garbled or missing interpolations
Symptom: chalk.green\Hello ${name}`printsHello , Sindre` or similar — the interpolated value appears in the wrong position, or the template does not behave like a standard template literal.
Cause: Chalk's chainable builder does not implement tagged template literal semantics. Used as a tag, it receives the raw string array and joins it, so variable interpolation does not work as expected.
Fix: Either call chalk as a regular function with standard ES template literals:
console.log(chalk.green(`Hello ${name}`));
Or install chalk-template for proper tagged template literal support with interpolation.
level setter throws a RangeError-style error
Symptom: Assigning chalk.level = someValue or passing { level: someValue } to new Chalk() throws Error: The \level` should be an integer from 0 to 3`.
Cause: The value is not a safe integer in the range 0–3. Common mistakes include passing true, null, undefined to the constructor's level field (note: passing undefined or omitting level is valid and triggers auto-detection), or a floating-point number.
Fix: Use only integer values 0, 1, 2, or 3. Omit level entirely (or pass undefined) to let Chalk detect the level automatically:
import { Chalk } from 'chalk';
const chalk = new Chalk(); // auto-detect
const chalk2 = new Chalk({ level: 2 }); // explicit 256-color
Colors render differently between stdout and stderr
Symptom: Styled strings sent to process.stderr appear plain or at a lower color level than those sent to process.stdout.
Cause: The default chalk export detects color support for stdout. If stderr is attached to a different TTY or is piped, its detected level may differ.
Fix: Use the chalkStderr export, which is a separate Chalk instance whose color level is independently detected for stderr:
import { chalkStderr } from 'chalk';
process.stderr.write(chalkStderr.red('Error message\n'));