The fastest Node.js library for formatting terminal text with ANSI colors~!
Switch branches/tags
Nothing to show
Clone or download
Latest commit 59d7d74 Dec 7, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bench chore: update bench Nov 15, 2018
shots update readme w/ results Jul 20, 2018
test test: assert deep chain references Nov 15, 2018
.editorconfig initial Jul 8, 2018
.gitignore initial Jul 8, 2018
.travis.yml initial Jul 8, 2018
index.js fix: enumerable properties; improve typings (#18) Dec 7, 2018
kleur.d.ts fix: enumerable properties; improve typings (#18) Dec 7, 2018
license initial Jul 8, 2018
package.json 3.0.1 Dec 7, 2018
readme.md docs: update benchmark results Nov 15, 2018

readme.md

kleur
The fastest Node.js library for formatting terminal text with ANSI colors~!

Features


As of v3.0 the Chalk-style syntax (magical getter) is no longer used.
If you need or require that syntax, consider using ansi-colors, which maintains chalk parity.


Install

$ npm install --save kleur

Usage

const { red, white, blue, bold } = require('kleur');

// basic usage
red('red text');

// chained methods
blue().bold().underline('howdy partner');

// nested methods
bold(`${ white().bgRed('[ERROR]') } ${ red().italic('Something happened')}`);

Chained Methods

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

Nested Methods

const { yellow, red, cyan } = require('kleur');

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

Conditional Support

Toggle color support as needed; kleur includes simple auto-detection which may not cover all cases.

const kleur = require('kleur');

// manually disable
kleur.enabled = false;

// or use another library to detect support
kleur.enabled = require('color-support').level;

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

API

Any kleur method returns a String when invoked with input; otherwise chaining is expected.

It's up to the developer to pass the output to destinations like console.log, process.stdout.write, etc.

The methods below are grouped by type for legibility purposes only. They each can be chained or nested with one another.

Colors:

black — red — green — yellow — blue — magenta — cyan — white — gray

Backgrounds:

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

Modifiers:

reset — bold — dim — italic* — underline — inverse — hidden — strikethrough*

* Not widely supported

Benchmarks

Using Node v10.13.0

Load time

chalk: 9.397ms
kleur: 0.525ms
ansi-colors: 1.200ms

Performance

# All Colors
  ansi-colors x 210,244 ops/sec ±0.36% (94 runs sampled)
  chalk x 11,999 ops/sec ±2.08% (84 runs sampled)
  kleur x 442,028 ops/sec ±0.26% (95 runs sampled)

# Stacked colors
  ansi-colors x 25,117 ops/sec ±0.33% (92 runs sampled)
  chalk x 2,602 ops/sec ±1.87% (84 runs sampled)
  kleur x 40,395 ops/sec ±0.41% (95 runs sampled)

# Nested colors
  ansi-colors x 77,423 ops/sec ±0.26% (95 runs sampled)
  chalk x 5,705 ops/sec ±1.48% (87 runs sampled)
  kleur x 114,039 ops/sec ±0.44% (95 runs sampled)

Credits

This project originally forked Brian Woodward's awesome ansi-colors library.

Beginning with kleur@3.0, the Chalk-style syntax (magical getter) has been replaced with function calls per key:

// Old:
c.red.bold.underline('old');

// New:
c.red().bold().underline('new');

As I work more with Rust, the newer syntax feels so much better & more natural!

If you prefer the old syntax, you may migrate to ansi-colors... or suffer the deprecation notice on older kleur versions 😅

License

MIT © Luke Edwards