readme.md
1 <div align="center"> 2 <img src="shots/logo.png" alt="kleur" height="120" /> 3 </div> 4 5 <div align="center"> 6 <a href="https://npmjs.org/package/kleur"> 7 <img src="https://badgen.now.sh/npm/v/kleur" alt="version" /> 8 </a> 9 <a href="https://travis-ci.org/lukeed/kleur"> 10 <img src="https://badgen.now.sh/travis/lukeed/kleur" alt="travis" /> 11 </a> 12 <a href="https://npmjs.org/package/kleur"> 13 <img src="https://badgen.now.sh/npm/dm/kleur" alt="downloads" /> 14 </a> 15 <a href="https://packagephobia.now.sh/result?p=kleur"> 16 <img src="https://packagephobia.now.sh/badge?p=kleur" alt="install size" /> 17 </a> 18 </div> 19 20 <div align="center">The fastest Node.js library for formatting terminal text with ANSI colors~!</div> 21 22 ## Features 23 24 * No dependencies 25 * Super [lightweight](#load-time) & [performant](#performance) 26 * Supports [nested](#nested-methods) & [chained](#chained-methods) colors 27 * No `String.prototype` modifications 28 * Conditional [color support](#conditional-support) 29 * Familiar [API](#api) 30 31 --- 32 33 As of `v3.0` the Chalk-style syntax (magical getter) is no longer used.<br>If you need or require that syntax, consider using [`ansi-colors`](https://github.com/doowb/ansi-colors), which maintains `chalk` parity. 34 35 --- 36 37 38 ## Install 39 40 ``` 41 $ npm install --save kleur 42 ``` 43 44 45 ## Usage 46 47 ```js 48 const { red, white, blue, bold } = require('kleur'); 49 50 // basic usage 51 red('red text'); 52 53 // chained methods 54 blue().bold().underline('howdy partner'); 55 56 // nested methods 57 bold(`${ white().bgRed('[ERROR]') } ${ red().italic('Something happened')}`); 58 ``` 59 60 ### Chained Methods 61 62 ```js 63 console.log(bold().red('this is a bold red message')); 64 console.log(bold().italic('this is a bold italicized message')); 65 console.log(bold().yellow().bgRed().italic('this is a bold yellow italicized message')); 66 console.log(green().bold().underline('this is a bold green underlined message')); 67 ``` 68 69 <img src="shots/1.png" width="300" /> 70 71 ### Nested Methods 72 73 ```js 74 const { yellow, red, cyan } = require('kleur'); 75 76 console.log(yellow(`foo ${red().bold('red')} bar ${cyan('cyan')} baz`)); 77 console.log(yellow('foo ' + red().bold('red') + ' bar ' + cyan('cyan') + ' baz')); 78 ``` 79 80 <img src="shots/2.png" width="300" /> 81 82 83 ### Conditional Support 84 85 Toggle color support as needed; `kleur` includes simple auto-detection which may not cover all cases. 86 87 ```js 88 const kleur = require('kleur'); 89 90 // manually disable 91 kleur.enabled = false; 92 93 // or use another library to detect support 94 kleur.enabled = require('color-support').level; 95 96 console.log(kleur.red('I will only be colored red if the terminal supports colors')); 97 ``` 98 99 100 ## API 101 102 Any `kleur` method returns a `String` when invoked with input; otherwise chaining is expected. 103 104 > It's up to the developer to pass the output to destinations like `console.log`, `process.stdout.write`, etc. 105 106 The methods below are grouped by type for legibility purposes only. They each can be [chained](#chained-methods) or [nested](#nested-methods) with one another. 107 108 ***Colors:*** 109 > black — red — green — yellow — blue — magenta — cyan — white — gray — grey 110 111 ***Backgrounds:*** 112 > bgBlack — bgRed — bgGreen — bgYellow — bgBlue — bgMagenta — bgCyan — bgWhite 113 114 ***Modifiers:*** 115 > reset — bold — dim — italic* — underline — inverse — hidden — strikethrough* 116 117 <sup>* <em>Not widely supported</em></sup> 118 119 120 ## Benchmarks 121 122 > Using Node v10.13.0 123 124 ### Load time 125 126 ``` 127 chalk :: 14.543ms 128 kleur :: 0.474ms 129 ansi-colors :: 1.923ms 130 ``` 131 132 ### Performance 133 134 ``` 135 # All Colors 136 ansi-colors x 199,381 ops/sec ±1.04% (96 runs sampled) 137 chalk x 12,107 ops/sec ±2.07% (87 runs sampled) 138 kleur x 715,334 ops/sec ±0.30% (93 runs sampled) 139 140 # Stacked colors 141 ansi-colors x 24,494 ops/sec ±1.03% (93 runs sampled) 142 chalk x 2,650 ops/sec ±2.06% (85 runs sampled) 143 kleur x 75,798 ops/sec ±0.19% (97 runs sampled) 144 145 # Nested colors 146 ansi-colors x 77,766 ops/sec ±0.32% (94 runs sampled) 147 chalk x 5,596 ops/sec ±1.85% (86 runs sampled) 148 kleur x 137,660 ops/sec ±0.31% (93 runs sampled) 149 ``` 150 151 152 ## Credits 153 154 This project originally forked [Brian Woodward](https://github.com/doowb)'s awesome [`ansi-colors`](https://github.com/doowb/ansi-colors) library. 155 156 Beginning with `kleur@3.0`, the Chalk-style syntax (magical getter) has been replaced with function calls per key: 157 158 ```js 159 // Old: 160 c.red.bold.underline('old'); 161 162 // New: 163 c.red().bold().underline('new'); 164 ``` 165 > <sup><em>As I work more with Rust, the newer syntax feels so much better & more natural!</em></sup> 166 167 If you prefer the old syntax, you may migrate to `ansi-colors`. Versions below `kleur@3.0` have been deprecated. 168 169 170 ## License 171 172 MIT © [Luke Edwards](https://lukeed.com)