Getting Started
Installation and first API call
Git2Docs CertifiedThis page walks you through installing Chalk and making your first styled terminal output call. Chalk is an ESM-only Node.js library that wraps strings in ANSI escape sequences, automatically detecting your terminal's color capability at runtime — no manual escape code management required. By the end of this page you will have Chalk installed, imported, and producing color-coded output through its chainable style API.
Before you begin, ensure you have:
- Node.js ≥ 22 — Chalk's
package.jsondeclares"node": ">=22". CI tests cover Node 26 and 22. - An ESM-compatible project — Chalk ships no CommonJS build. Your project must be able to consume ES modules (either
"type": "module"inpackage.json, a.mjsfile extension, or an ESM-compatible bundler). - npm, pnpm, or yarn — any of these can install the package.
CommonJS note: On Node.js ≥ 22.12 you can
require('chalk')without the ESM loader flag; the call returns the ES module namespace and you access the default export via.default. On Node.js 22.0–22.11,require('chalk')throwsERR_REQUIRE_ESM.
-
Install Chalk in your project:
npm install chalk -
Create a script (e.g.
hello.mjs) and import the default export:import chalk from 'chalk'; console.log(chalk.blue('Hello world!')); -
Run the script:
node hello.mjsYou should see
Hello world!printed in blue in your terminal.
Step 1 — Install the package
Run the install command for your package manager:
# npm
npm install chalk
# pnpm
pnpm add chalk
# yarn
yarn add chalk
You know this worked when chalk appears in your node_modules directory and in package.json under dependencies.
Step 2 — Import the default export
In any .js file inside an ESM project (or a .mjs file), add:
import chalk from 'chalk';
The chalk default export is a pre-configured function whose color level is auto-detected from your terminal at import time. No configuration is required for typical use.
Step 3 — Apply your first style
Call any style property as a method, passing one or more strings:
console.log(chalk.blue('Hello world!'));
Chalk wraps the string in the appropriate ANSI escape sequences for your terminal and returns the result. If your terminal supports color, the text appears blue.
Step 4 — Chain styles
Style properties are chainable. Each property access returns a new, cached builder function (not the same instance), so you can combine modifiers, foreground colors, and background colors freely:
console.log(chalk.blue.bgRed.bold('Hello world!'));
When two properties of the same type conflict (e.g. chalk.red.yellow), all ANSI open codes are emitted but only the last one in the chain is visually applied — chalk.red.yellow renders yellow.
Step 5 (optional) — Create an isolated instance
If you need a fixed color level independent of the host terminal — for example, to disable color in test output or force Truecolor in a specific context — construct a Chalk instance with an explicit level:
import { Chalk } from 'chalk';
const customChalk = new Chalk({ level: 0 }); // colors disabled
Valid levels are 0 (disabled), 1 (16 colors), 2 (256 colors), and 3 (Truecolor). Passing any other value throws an Error with the message The \level` should be an integer from 0 to 3`.
Basic color
import chalk from 'chalk';
console.log(chalk.blue('Hello world!'));
Combining styled and plain strings
import chalk from 'chalk';
console.log(chalk.blue('Hello') + ' World' + chalk.red('!'));
Chaining multiple styles
import chalk from 'chalk';
console.log(chalk.blue.bgRed.bold('Hello world!'));
Passing multiple arguments (joined with spaces)
Chalk's chainable builders accept multiple string arguments and join them with a single space:
import chalk from 'chalk';
console.log(chalk.blue('Hello', 'World!', 'Foo', 'bar', 'biz', 'baz'));
Nesting styles
import chalk from 'chalk';
console.log(chalk.red('Hello', chalk.underline.bgBlue('world') + '!'));
Defining reusable themes
Because each property access returns a new builder function, you can store chains as named variables:
import chalk from 'chalk';
const error = chalk.bold.red;
const warning = chalk.hex('#FFA500'); // Orange
console.log(error('Error!'));
console.log(warning('Warning!'));
Using Truecolor and 256-color methods
import chalk from 'chalk';
console.log(chalk.rgb(123, 45, 67).underline('Underlined reddish color'));
console.log(chalk.hex('#DEADED').bold('Bold gray!'));
console.log(chalk.bgHex('#DEADED').underline('Hello, world!'));
console.log(chalk.bgRgb(15, 100, 204).inverse('Hello!'));
Chalk automatically downsamples these values to the escape format your terminal supports (e.g. if the detected level is 1, an RGB value is mapped to the nearest basic ANSI color).
Using console.log string substitution
Standard console.log substitution tokens work normally alongside Chalk:
import chalk from 'chalk';
const name = 'Sindre';
console.log(chalk.green('Hello %s'), name);
//=> 'Hello Sindre'
Using an isolated instance with a fixed level
import { Chalk } from 'chalk';
const customChalk = new Chalk({ level: 0 });
console.log(customChalk.red('This will not be colored'));
CommonJS interop (Node.js ≥ 22.12 only)
On Node.js ≥ 22.12, CommonJS files can load Chalk without the ESM loader flag. Access the default export via .default:
// my-script.cjs (Node.js ≥22.12 only)
const { default: chalk } = require('chalk');
console.log(chalk.green('Works in CJS on Node ≥22.12'));
Warning: Avoid tagged template literal syntax with core Chalk.
chalk.red\text ${val}`does not interpolate correctly — the values are misplaced in the output. Usechalk.red(`text ${val}`)instead, or install the [chalk-template`](https://github.com/chalk/chalk-template) package for tagged template literal support.
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.0–22.11. The ability to require() ES modules without the loader flag was added in Node.js 22.12.
Fix: Upgrade to Node.js ≥ 22.12, or convert your file to ESM (import chalk from 'chalk').
No color in output / all text appears plain
Symptom: Chalk calls produce no color; strings are returned without ANSI codes.
Cause (a): The terminal or environment reports a color level of 0 (e.g. a non-TTY pipe, CI environment, or FORCE_COLOR=0).
Fix: Set FORCE_COLOR=1 (basic), FORCE_COLOR=2 (256-color), or FORCE_COLOR=3 (Truecolor) in your environment to override detection. Note that FORCE_COLOR takes precedence over --no-color but --color=256 and --color=16m take precedence over a non-zero numeric FORCE_COLOR.
Cause (b): You explicitly constructed new Chalk({ level: 0 }) and are using that instance.
Fix: Omit the level option or pass undefined to let Chalk detect the level automatically.
Error: The \level` should be an integer from 0 to 3`
Symptom: Constructing new Chalk({ level: n }) or assigning chalkInstance.level = n throws this error.
Cause: You passed a value that is not a safe integer between 0 and 3 (e.g. 4, 1.5, null, or a string).
Fix: Use only 0, 1, 2, or 3. To auto-detect, omit the level option entirely.
Tagged template literal produces garbled or misplaced values
Symptom: chalk.green\Hello ${name}`prints something likeHello , Sindre` — values appear after the full string rather than interpolated inline.
Cause: Core Chalk does not support tagged template literals. When used as a tag, the raw string array is coerced and values are appended after a space, not substituted at their positions.
Fix: Use a regular function call with a template literal: chalk.green(\Hello ${name}`). For full tagged template support, install the [chalk-template`](https://github.com/chalk/chalk-template) package.
Last chained color is not what appears in the terminal
Symptom: chalk.red.yellow('text') renders yellow, not red.
Cause: When conflicting styles are chained, all ANSI open codes are emitted in order. The last code in the chain is applied last and therefore wins visually. chalk.red.yellow emits the red open code followed by the yellow open code — the terminal renders yellow.
Fix: Place the style you want applied last in the chain, or remove conflicting styles.