Background Colors

Chalk provides sixteen named background colors — from bgBlack through bgWhite — plus eight brighter variants that paint the cell behind your text rather than the text itself. This page covers every named background style available in Chalk 5, explains the bgBlackBright / bgGray / bgGrey alias relationship, and shows you how to chain background colors with foreground colors and modifiers to build expressive terminal output.

Before using Chalk's background color styles, make sure you have:

• Node.js 16 or later (required by Chalk 5)
• Chalk 5 installed (npm install chalk) — Chalk 5 is ESM-only; if your project uses CommonJS and you cannot migrate, pin to chalk@4 instead
• An ESM-compatible module system — import syntax is required; require('chalk') throws a runtime error in Chalk 5
• A terminal emulator that supports ANSI escape codes (virtually all modern terminals on macOS, Linux, and Windows Terminal qualify)

1. Install Chalk from npm:

npm install chalk

2. Or with yarn:

yarn add chalk

3. Or with pnpm:

pnpm add chalk

4. Import the default export in your ESM file:

import chalk from 'chalk';

No additional setup is required. Chalk detects your terminal's color support automatically and makes all background color properties available on the chalk object immediately.

Chalk's background color output is governed by a single level property that controls how many colors the terminal can render. You can read or set it at runtime:

import chalk from 'chalk';

console.log(chalk.level); // e.g. 3 in a true-color terminal

Chalk auto-detects the level from the environment. You should not override chalk.level globally in reusable library code, because the setting is shared across all consumers in the same process. Instead, create an isolated instance with a fixed level:

import { Chalk } from 'chalk';

const chalkForTests = new Chalk({ level: 1 }); // always basic color, ignores terminal

You can also override detection at the process level using the FORCE_COLOR environment variable:

When FORCE_COLOR is set it overrides all other detection logic, including --color and --no-color flags.

Every background color is a chainable property on the chalk object. Access it just like a foreground color, but with the bg prefix and a capitalized color name. Calling the final property in the chain as a function applies all accumulated styles to the string you pass:

import chalk from 'chalk';

console.log(chalk.bgBlue('Highlighted text'));

Standard backgrounds (bgBlack … bgWhite)

These eight styles correspond to the original 16-color ANSI palette's background codes (ANSI 40–47):

• bgBlack
• bgRed
• bgGreen
• bgYellow
• bgBlue
• bgMagenta
• bgCyan
• bgWhite

Bright backgrounds (bgBlackBright … bgWhiteBright)

Eight additional styles use the high-intensity background codes (ANSI 100–107). Each name mirrors its standard counterpart with Bright appended:

• bgBlackBright
• bgRedBright
• bgGreenBright
• bgYellowBright
• bgBlueBright
• bgMagentaBright
• bgCyanBright
• bgWhiteBright

The bgGray and bgGrey aliases

bgBlackBright produces a dark gray background that is commonly needed for visual separators and secondary information. Because bgBlackBright is verbose, Chalk ships two shorter aliases that resolve to exactly the same ANSI code:

• bgGray — preferred spelling in American English
• bgGrey — preferred spelling in British English

All three names are interchangeable:

console.log(chalk.bgGray('Same result'));
console.log(chalk.bgGrey('Same result'));
console.log(chalk.bgBlackBright('Same result'));

Chaining background colors with foreground colors and modifiers

Background styles chain with any foreground color or modifier in any order. When a conflict exists (two background colors in one chain), the last one wins:

// White text on a red background, bold
console.log(chalk.white.bgRed.bold('ERROR'));

// The second background color wins
console.log(chalk.bgBlue.bgGreen('Green wins'));

Passing multiple strings

If you pass more than one argument, Chalk joins them with a space and applies the background to the whole result:

console.log(chalk.bgCyan('Step', '1', 'of', '3'));
// => 'Step 1 of 3' on a cyan background

Basic named background

Apply a solid background color to a short label:

import chalk from 'chalk';

console.log(chalk.bgGreen(' SUCCESS '));
console.log(chalk.bgRed(' FAILURE '));
console.log(chalk.bgYellow(' WARNING '));

 SUCCESS   ← green background, default foreground
 FAILURE   ← red background, default foreground
 WARNING   ← yellow background, default foreground

Background combined with foreground color

Pair a foreground color with a contrasting background for maximum legibility:

import chalk from 'chalk';

console.log(chalk.black.bgWhite(' DOCS '));
console.log(chalk.white.bgBlue(' INFO '));
console.log(chalk.black.bgYellowBright(' NOTE '));

 DOCS   ← black text on white background
 INFO   ← white text on blue background
 NOTE   ← black text on bright-yellow background

Background combined with a modifier

Bold text on a colored background draws attention to critical output:

import chalk from 'chalk';

console.log(chalk.bold.white.bgRed(' CRITICAL ERROR '));
console.log(chalk.italic.bgMagenta(' experimental feature '));

Using the bgGray alias

bgGray and bgGrey are both aliases for bgBlackBright. Use whichever spelling matches your codebase's convention:

import chalk from 'chalk';

console.log(chalk.white.bgGray(' DISABLED '));
console.log(chalk.white.bgGrey(' DISABLED '));
console.log(chalk.white.bgBlackBright(' DISABLED ')); // identical output

All three lines produce white text on a dark-gray background.

Nesting background styles inside a larger string

Wrap only part of a longer string with a background color by nesting chalk calls:

import chalk from 'chalk';

console.log(
  chalk.green('Build') +
  ' ' +
  chalk.bold.white.bgGreen(' PASSED ') +
  ' in 3.2 s'
);

Build  PASSED  in 3.2 s
       ↑ white bold text on green background

Defining a reusable theme

Store styled chalk chains as named constants to keep your output consistent across a CLI:

import chalk from 'chalk';

const tag = {
  success: chalk.black.bgGreen,
  error:   chalk.white.bgRed,
  warn:    chalk.black.bgYellow,
  info:    chalk.white.bgBlue,
  muted:   chalk.white.bgGray,
};

console.log(tag.success(' DONE  '), 'All tests passed.');
console.log(tag.error(  ' FAIL  '), 'Snapshot mismatch in Button.test.js');
console.log(tag.warn(   ' WARN  '), 'Deprecated API used.');
console.log(tag.info(   ' INFO  '), 'Listening on port 3000.');
console.log(tag.muted(  ' SKIP  '), 'No changes detected.');

Isolated Chalk instance with a fixed color level (library-safe)

When writing a reusable module, lock the color level to prevent auto-detection from affecting other consumers:

import { Chalk } from 'chalk';

const chalk1 = new Chalk({ level: 1 }); // always basic 16 colors

console.log(chalk1.bgCyan(' STATUS '));

Programmatic validation with backgroundColorNames

If you accept background-color names as user input, validate them against Chalk's own list:

import { backgroundColorNames } from 'chalk';

console.log(backgroundColorNames);
// => ['bgBlack', 'bgRed', 'bgGreen', 'bgYellow', 'bgBlue',
//     'bgMagenta', 'bgCyan', 'bgWhite',
//     'bgBlackBright', 'bgGray', 'bgGrey',
//     'bgRedBright', 'bgGreenBright', 'bgYellowBright',
//     'bgBlueBright', 'bgMagentaBright', 'bgCyanBright', 'bgWhiteBright']

const userInput = 'bgTeal';
console.log(backgroundColorNames.includes(userInput)); // false — reject unknown names

No background color appears — output is plain text

Symptom: Calling chalk.bgRed('text') prints text with no visible background.

Likely cause: Chalk has detected a color level of 0, meaning the current environment reports no color support. This commonly happens in CI pipelines, log files, or when FORCE_COLOR=0 is set.

Fix: Check chalk.level at startup. If you need color in a CI environment, set FORCE_COLOR=3 (or another non-zero level) in the pipeline's environment variables, or use the --color flag when running your script. Do not override chalk.level globally in library code — use new Chalk({ level: 1 }) instead.

require('chalk') throws Error [ERR_REQUIRE_ESM]

Symptom: Your script crashes at startup with a message about ESM.

Likely cause: Chalk 5 is ESM-only. CommonJS require() cannot load it.

Fix: Convert your file to ESM by adding "type": "module" to package.json and switching to import chalk from 'chalk'. If migrating to ESM is not possible right now, downgrade to chalk@4, which supports CommonJS: npm install chalk@4.

Two background colors are chained but only one appears

Symptom: chalk.bgBlue.bgRed('text') shows only a red background, not blue.

Likely cause: This is expected behavior. When you chain conflicting styles (two background colors), the later one in the chain takes precedence. chalk.bgBlue.bgRed is equivalent to chalk.bgRed.

Fix: Use only one background color per chain. To display text blocks with different backgrounds on the same line, concatenate separate chalk calls:

console.log(chalk.bgBlue(' A ') + chalk.bgRed(' B '));

bgGray or bgGrey is not recognized in TypeScript

Symptom: TypeScript reports that bgGray or bgGrey does not exist on the ChalkInstance type.

Likely cause: You may be using an outdated version of Chalk's type definitions, or you are looking at a Chalk 4 type definition that predates the alias.

Fix: Ensure you are on Chalk 5 and that your node_modules type definitions are up to date (npm install chalk@latest). Both bgGray and bgGrey are declared as readonly bgGray: this and readonly bgGrey: this in the current ChalkInstance interface and are fully type-safe.

Background color looks wrong or maps to a different color

Symptom: chalk.bgBlueBright appears as a different shade than expected, or matches another color entirely.

Likely cause: Chalk auto-detects color support and downgrades colors when the terminal reports a lower level. For example, at level 1 (basic 16 colors) all named backgrounds render as their nearest ANSI equivalent, but the exact shade is determined by your terminal emulator's color theme, not by Chalk.

Fix: This is correct behavior — Chalk degrades gracefully to ensure output remains legible everywhere. If you need a very specific color, use bgRgb() or bgHex() (requires level 3) and verify that your terminal supports true color. You can also force a consistent level during development with FORCE_COLOR=3.