npm package
ansi-styles review
Use ansi-styles when writing the formatting layer is part of your job and you can manage color state and output policy.
A red label can leave the next word in the wrong color if its closing sequence resets the surrounding foreground. ansi-styles gives JavaScript formatter authors direct access to ANSI escape codes. Each style has open and close strings, and conversion helpers generate foreground, background, and underline color sequences. Your formatter manages nesting and decides whether to emit color. Version 7 requires Node 22 or newer.
Use ansi-styles when writing the formatting layer is part of your job and you can manage color state and output policy. For application-level colored messages, start with the higher-level Chalk package recommended by the project.
Answers from our run
ansi-styles or chalk: which should you use?
chalk: Choose Chalk when you want a higher-level package for styling strings. The ansi-styles README explicitly recommends it for that job. Use ansi-styles when writing the formatting layer is part of your job and you can manage color state and output policy.
When should you not use ansi-styles?
You just want to print a red error message. The project's documentation recommends the higher-level Chalk package for styling strings.
Use it if
Skip it if
Setup reality
Install with npm install ansi-styles@7.0.0 and use import styles from 'ansi-styles' in an ESM entry point, such as a .mjs file. The published manifest declares type: module, exports ./index.js, bundled declarations at ./index.d.ts, and Node >=22. These are package declarations, not a tested compatibility matrix. This guide uses the supplied versioned documentation, implementation, package metadata, and release notes. No installation, package execution, test run, tarball comparison, or terminal-rendering result is supplied. All snippets below are source-based, unexecuted illustrations for version 7.0.0. Each includes its own import.
Closing a style resets its category rather than restoring the previous value. Red and green both close with foreground reset 39. If you put a red segment inside green text, reopen green after closing red. Bold and dim share closing code 22, so ending one can end the other. The reset modifier uses code 0 and clears other active attributes too. A nesting formatter needs to track these relationships.
The implementation generates the requested sequence without inspecting your terminal. Decide whether output should contain escapes before wrapping the text, and choose the color depth yourself. RGB conversion to a palette can lose color detail. A truecolor helper does not establish terminal support. Underline color needs an underline modifier to be visible; the README marks underline styles and colors as not widely supported.
For Go styling and terminal layouts, the supplied description of the existing Lip Gloss guide covers a different job, including borders and measurement. With ansi-styles, start with a single status string and check terminal output and redirected output in your application before expanding your formatter.
The dimension notes below are documentation-based editorial assessments of the supplied evidence. API stability considers the exposed contract and the declared runtime requirement. Docs quality considers examples and stated limits. Maintenance considers the documented release changes. Ecosystem considers declared integration surfaces. Reader-visible numbers should be read against the site's published rubric; these notes do not define a separate scoring scale. Adoption, compatibility across environments, future support, and terminal rendering were not measured.
Patterns
Wrap a green status wrap-status
import styles from 'ansi-styles';
const text = `${styles.green.open}ready${styles.green.close}`;
console.log(text);The close string resets the foreground to its default. It does not remember a previous foreground color.
Combine bold and a foreground combine-modifiers
import styles from 'ansi-styles';
const label = styles.bold.open + styles.red.open
+ 'failed' + styles.red.close + styles.bold.close;
console.error(label);Close the categories you opened. Bold and dim both use closing code 22, so closing bold also ends dim.
Reopen the outer color after a nested label restore-outer-color
import styles from 'ansi-styles';
const line = styles.green.open + 'build '
+ styles.red.open + 'failed' + styles.red.close
+ styles.green.open + ' after compilation' + styles.green.close;
console.log(line);Reopening green is deliberate. The red close emits foreground reset 39 rather than restoring green.
Pair foreground and background choose-background
import styles from 'ansi-styles';
console.log(styles.black.open + styles.bgYellow.open
+ ' WARNING ' + styles.bgYellow.close + styles.black.close);Background and foreground have separate reset sequences. This example resets both categories. The reset modifier would clear other active attributes too.
Generate an RGB foreground sequence emit-truecolor
import styles from 'ansi-styles';
const open = styles.color.ansi16m(120, 80, 240);
console.log(open + 'accent' + styles.color.close);This emits a truecolor request without detecting support. Your output policy must choose whether that request is appropriate.
Convert RGB to a 256-color background convert-palette
import styles from 'ansi-styles';
const index = styles.rgbToAnsi256(120, 80, 240);
const open = styles.bgColor.ansi256(index);
console.log(open + ' selected ' + styles.bgColor.close);The conversion approximates the RGB color with a palette entry. It does not negotiate a palette with the terminal.
Convert a hex color to a basic foreground convert-basic-color
import styles from 'ansi-styles';
const code = styles.hexToAnsi('#C0FFEE');
console.log(styles.color.ansi(code) + 'accent' + styles.color.close);color.ansi accepts an ANSI foreground code rather than a palette index. Use the conversion helper instead of passing an RGB channel.
Allow only supported foreground names validate-foreground
import styles, {foregroundColorNames} from 'ansi-styles';
function colorize(name, text) {
if (!foregroundColorNames.includes(name)) return text;
const style = styles[name];
return style.open + text + style.close;
}This validates the style name, not the contents of text. The caller still needs to manage nesting restoration.
Apply an underline and its color apply-colored-underline
import styles from 'ansi-styles';
console.log(styles.underlineCurly.open + styles.underlineRed.open
+ 'check this' + styles.underlineRed.close + styles.underlineCurly.close);Underline color needs an underline modifier to be visible. The README marks these controls as not widely supported, so keep the words meaningful without them.
Keep a plain-output path gate-color-output
import styles from 'ansi-styles';
function status(text, colorEnabled) {
return colorEnabled
? styles.green.open + text + styles.green.close
: text;
}colorEnabled is a caller-supplied policy, not a detection result from ansi-styles. Connect it to your application's terminal and user-preference handling.
Alternatives
| Package | Registry | Pick it when |
|---|---|---|
| chalk | npm | Choose Chalk when you want a higher-level package for styling strings. The ansi-styles README explicitly recommends it for that job. |
| picocolors | npm | Consider picocolors for terminal output formatting with ANSI colors, the scope stated in its npm description. The supplied evidence does not establish a size, speed, or API comparison. |
More cli & tooling guides
How this guide is made: grounded in the library's documentation, release notes, changelog, and issue history, on a fixed rubric — not a hands-on install of every release. The 50 most-downloaded entries are additionally install-verified in clean containers. Corrections: contact the desk.