ansi-colors     

Easily add ANSI colors to your text and symbols in the terminal. A faster drop-in replacement for chalk, kleur and turbocolor (without the dependencies and rendering bugs).

Please consider following this project's author, Brian Woodward, and consider starring the project to show your ❤️ and support.

Install

Install with npm:

sh
$ npm install --save ansi-colors

!image

Why use this?

ansi-colors is _the fastest Node.js library for terminal styling_. A more performant drop-in replacement for chalk, with no dependencies.

• _Blazing fast_ - Fastest terminal styling library in node.js, 10-20x faster than chalk!

• _Drop-in replacement_ for chalk.
• _No dependencies_ (Chalk has 7 dependencies in its tree!)

• _Safe_ - Does not modify the String.prototype like colors.
• Supports [nested colors](#nested-colors), and does not have the [nested styling bug](#nested-styling-bug) that is present in colorette, chalk, and kleur.
• Supports [chained colors](#chained-colors).
• [Toggle color support](#toggle-color-support) on or off.

Usage

js
const c = require('ansi-colors');

console.log(c.red('This is a red string!'));
console.log(c.green('This is a red string!'));
console.log(c.cyan('This is a cyan string!'));
console.log(c.yellow('This is a yellow string!'));

!image

Chained colors

js
console.log(c.bold.red('this is a bold red message'));
console.log(c.bold.yellow.italic('this is a bold yellow italicized message'));
console.log(c.green.bold.underline('this is a bold green underlined message'));

!image

Nested colors

js
console.log(c.yellow(`foo ${c.red.bold('red')} bar ${c.cyan('cyan')} baz`));

!image

Nested styling bug

ansi-colors does not have the nested styling bug found in colorette, chalk, and kleur.

js
const { bold, red } = require('ansi-styles');
console.log(bold(`foo ${red.dim('bar')} baz`));

const colorette = require('colorette');
console.log(colorette.bold(`foo ${colorette.red(colorette.dim('bar'))} baz`));

const kleur = require('kleur');
console.log(kleur.bold(`foo ${kleur.red.dim('bar')} baz`));

const chalk = require('chalk');
console.log(chalk.bold(`foo ${chalk.red.dim('bar')} baz`));

Results in the following

(sans icons and labels)

!image

Toggle color support

Easily enable/disable colors.

js
const c = require('ansi-colors');

// disable colors manually
c.enabled = false;

// or use a library to automatically detect support
c.enabled = require('color-support').hasBasic;

console.log(c.red('I will only be colored red if the terminal supports colors'));

Strip ANSI codes

Use the .unstyle method to strip ANSI codes from a string.

js
console.log(c.unstyle(c.blue.bold('foo bar baz')));
//=> 'foo bar baz'

Available styles

Note that bright and bright-background colors are not always supported.

_(gray is the U.S. spelling, grey is more commonly used in the Canada and U.K.)_

Style modifiers

• dim
• bold

• hidden
• _italic_

• underline
• inverse
• strikethrough

• reset

Aliases

Create custom aliases for styles.

js
const colors = require('ansi-colors');

colors.alias('primary', colors.yellow);
colors.alias('secondary', colors.bold);

console.log(colors.primary.secondary('Foo'));

Themes

A theme is an object of custom aliases.

js
const colors = require('ansi-colors');

colors.theme({
  danger: colors.red,
  dark: colors.dim.gray,
  disabled: colors.gray,
  em: colors.italic,
  heading: colors.bold.underline,
  info: colors.cyan,
  muted: colors.dim,
  primary: colors.blue,
  strong: colors.bold,
  success: colors.green,
  underline: colors.underline,
  warning: colors.yellow
});

// Now, we can use our custom styles alongside the built-in styles!
console.log(colors.danger.strong.em('Error!'));
console.log(colors.warning('Heads up!'));
console.log(colors.info('Did you know...'));
console.log(colors.success.bold('It worked!'));

Performance

Libraries tested

• ansi-colors v3.0.4
• chalk v2.4.1

Mac

MacBook Pro, Intel Core i7, 2.3 GHz, 16 GB.

Load time

Time it takes to load the first time require() is called:

• ansi-colors - 1.915ms
• chalk - 12.437ms

Benchmarks

# All Colors
  ansi-colors x 173,851 ops/sec ±0.42% (91 runs sampled)
  chalk x 9,944 ops/sec ±2.53% (81 runs sampled)))

# Chained colors
  ansi-colors x 20,791 ops/sec ±0.60% (88 runs sampled)
  chalk x 2,111 ops/sec ±2.34% (83 runs sampled)

# Nested colors
  ansi-colors x 59,304 ops/sec ±0.98% (92 runs sampled)
  chalk x 4,590 ops/sec ±2.08% (82 runs sampled)

Windows

Windows 10, Intel Core i7-7700k CPU @ 4.2 GHz, 32 GB

Load time

Time it takes to load the first time require() is called:

• ansi-colors - 1.494ms
• chalk - 11.523ms

Benchmarks

# All Colors
  ansi-colors x 193,088 ops/sec ±0.51% (95 runs sampled))
  chalk x 9,612 ops/sec ±3.31% (77 runs sampled)))

# Chained colors
  ansi-colors x 26,093 ops/sec ±1.13% (94 runs sampled)
  chalk x 2,267 ops/sec ±2.88% (80 runs sampled))

# Nested colors
  ansi-colors x 67,747 ops/sec ±0.49% (93 runs sampled)
  chalk x 4,446 ops/sec ±3.01% (82 runs sampled))

About

<details> <summary><strong>Contributing</strong></summary>

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

</details>

<details> <summary><strong>Running Tests</strong></summary>

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

sh
$ npm install && npm test

</details>

<details> <summary><strong>Building docs</strong></summary>

_(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_

To generate the readme, run the following command:

sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb

</details>

Related projects

You might also be interested in these projects:

• ansi-wrap: Create ansi colors by passing the open and close codes. | [homepage](https://github.com/jonschlinkert/ansi-wrap "Create ansi colors by passing the open and close codes.")
• strip-color: Strip ANSI color codes from a string. No dependencies. | [homepage](https://github.com/jonschlinkert/strip-color "Strip ANSI color codes from a string. No dependencies.")

Contributors

Author

Brian Woodward

• GitHub Profile
• Twitter Profile
• LinkedIn Profile

License

Copyright © 2019, Brian Woodward. Released under the [MIT License](LICENSE).

_This file was generated by verb-generate-readme, v0.8.0, on July 01, 2019._