[6a3a178] | 1 | # ansi-colors [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=W8YFZ425KND68) [![NPM version](https://img.shields.io/npm/v/ansi-colors.svg?style=flat)](https://www.npmjs.com/package/ansi-colors) [![NPM monthly downloads](https://img.shields.io/npm/dm/ansi-colors.svg?style=flat)](https://npmjs.org/package/ansi-colors) [![NPM total downloads](https://img.shields.io/npm/dt/ansi-colors.svg?style=flat)](https://npmjs.org/package/ansi-colors) [![Linux Build Status](https://img.shields.io/travis/doowb/ansi-colors.svg?style=flat&label=Travis)](https://travis-ci.org/doowb/ansi-colors)
|
---|
| 2 |
|
---|
| 3 | > 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).
|
---|
| 4 |
|
---|
| 5 | Please consider following this project's author, [Brian Woodward](https://github.com/doowb), and consider starring the project to show your :heart: and support.
|
---|
| 6 |
|
---|
| 7 | ## Install
|
---|
| 8 |
|
---|
| 9 | Install with [npm](https://www.npmjs.com/):
|
---|
| 10 |
|
---|
| 11 | ```sh
|
---|
| 12 | $ npm install --save ansi-colors
|
---|
| 13 | ```
|
---|
| 14 |
|
---|
| 15 | ![image](https://user-images.githubusercontent.com/383994/39635445-8a98a3a6-4f8b-11e8-89c1-068c45d4fff8.png)
|
---|
| 16 |
|
---|
| 17 | ## Why use this?
|
---|
| 18 |
|
---|
| 19 | ansi-colors is _the fastest Node.js library for terminal styling_. A more performant drop-in replacement for chalk, with no dependencies.
|
---|
| 20 |
|
---|
| 21 | * _Blazing fast_ - Fastest terminal styling library in node.js, 10-20x faster than chalk!
|
---|
| 22 |
|
---|
| 23 | * _Drop-in replacement_ for [chalk](https://github.com/chalk/chalk).
|
---|
| 24 | * _No dependencies_ (Chalk has 7 dependencies in its tree!)
|
---|
| 25 |
|
---|
| 26 | * _Safe_ - Does not modify the `String.prototype` like [colors](https://github.com/Marak/colors.js).
|
---|
| 27 | * Supports [nested colors](#nested-colors), **and does not have the [nested styling bug](#nested-styling-bug) that is present in [colorette](https://github.com/jorgebucaran/colorette), [chalk](https://github.com/chalk/chalk), and [kleur](https://github.com/lukeed/kleur)**.
|
---|
| 28 | * Supports [chained colors](#chained-colors).
|
---|
| 29 | * [Toggle color support](#toggle-color-support) on or off.
|
---|
| 30 |
|
---|
| 31 | ## Usage
|
---|
| 32 |
|
---|
| 33 | ```js
|
---|
| 34 | const c = require('ansi-colors');
|
---|
| 35 |
|
---|
| 36 | console.log(c.red('This is a red string!'));
|
---|
| 37 | console.log(c.green('This is a red string!'));
|
---|
| 38 | console.log(c.cyan('This is a cyan string!'));
|
---|
| 39 | console.log(c.yellow('This is a yellow string!'));
|
---|
| 40 | ```
|
---|
| 41 |
|
---|
| 42 | ![image](https://user-images.githubusercontent.com/383994/39653848-a38e67da-4fc0-11e8-89ae-98c65ebe9dcf.png)
|
---|
| 43 |
|
---|
| 44 | ## Chained colors
|
---|
| 45 |
|
---|
| 46 | ```js
|
---|
| 47 | console.log(c.bold.red('this is a bold red message'));
|
---|
| 48 | console.log(c.bold.yellow.italic('this is a bold yellow italicized message'));
|
---|
| 49 | console.log(c.green.bold.underline('this is a bold green underlined message'));
|
---|
| 50 | ```
|
---|
| 51 |
|
---|
| 52 | ![image](https://user-images.githubusercontent.com/383994/39635780-7617246a-4f8c-11e8-89e9-05216cc54e38.png)
|
---|
| 53 |
|
---|
| 54 | ## Nested colors
|
---|
| 55 |
|
---|
| 56 | ```js
|
---|
| 57 | console.log(c.yellow(`foo ${c.red.bold('red')} bar ${c.cyan('cyan')} baz`));
|
---|
| 58 | ```
|
---|
| 59 |
|
---|
| 60 | ![image](https://user-images.githubusercontent.com/383994/39635817-8ed93d44-4f8c-11e8-8afd-8c3ea35f5fbe.png)
|
---|
| 61 |
|
---|
| 62 | ### Nested styling bug
|
---|
| 63 |
|
---|
| 64 | `ansi-colors` does not have the nested styling bug found in [colorette](https://github.com/jorgebucaran/colorette), [chalk](https://github.com/chalk/chalk), and [kleur](https://github.com/lukeed/kleur).
|
---|
| 65 |
|
---|
| 66 | ```js
|
---|
| 67 | const { bold, red } = require('ansi-styles');
|
---|
| 68 | console.log(bold(`foo ${red.dim('bar')} baz`));
|
---|
| 69 |
|
---|
| 70 | const colorette = require('colorette');
|
---|
| 71 | console.log(colorette.bold(`foo ${colorette.red(colorette.dim('bar'))} baz`));
|
---|
| 72 |
|
---|
| 73 | const kleur = require('kleur');
|
---|
| 74 | console.log(kleur.bold(`foo ${kleur.red.dim('bar')} baz`));
|
---|
| 75 |
|
---|
| 76 | const chalk = require('chalk');
|
---|
| 77 | console.log(chalk.bold(`foo ${chalk.red.dim('bar')} baz`));
|
---|
| 78 | ```
|
---|
| 79 |
|
---|
| 80 | **Results in the following**
|
---|
| 81 |
|
---|
| 82 | (sans icons and labels)
|
---|
| 83 |
|
---|
| 84 | ![image](https://user-images.githubusercontent.com/383994/47280326-d2ee0580-d5a3-11e8-9611-ea6010f0a253.png)
|
---|
| 85 |
|
---|
| 86 | ## Toggle color support
|
---|
| 87 |
|
---|
| 88 | Easily enable/disable colors.
|
---|
| 89 |
|
---|
| 90 | ```js
|
---|
| 91 | const c = require('ansi-colors');
|
---|
| 92 |
|
---|
| 93 | // disable colors manually
|
---|
| 94 | c.enabled = false;
|
---|
| 95 |
|
---|
| 96 | // or use a library to automatically detect support
|
---|
| 97 | c.enabled = require('color-support').hasBasic;
|
---|
| 98 |
|
---|
| 99 | console.log(c.red('I will only be colored red if the terminal supports colors'));
|
---|
| 100 | ```
|
---|
| 101 |
|
---|
| 102 | ## Strip ANSI codes
|
---|
| 103 |
|
---|
| 104 | Use the `.unstyle` method to strip ANSI codes from a string.
|
---|
| 105 |
|
---|
| 106 | ```js
|
---|
| 107 | console.log(c.unstyle(c.blue.bold('foo bar baz')));
|
---|
| 108 | //=> 'foo bar baz'
|
---|
| 109 | ```
|
---|
| 110 |
|
---|
| 111 | ## Available styles
|
---|
| 112 |
|
---|
| 113 | **Note** that bright and bright-background colors are not always supported.
|
---|
| 114 |
|
---|
| 115 | | Colors | Background Colors | Bright Colors | Bright Background Colors |
|
---|
| 116 | | ------- | ----------------- | ------------- | ------------------------ |
|
---|
| 117 | | black | bgBlack | blackBright | bgBlackBright |
|
---|
| 118 | | red | bgRed | redBright | bgRedBright |
|
---|
| 119 | | green | bgGreen | greenBright | bgGreenBright |
|
---|
| 120 | | yellow | bgYellow | yellowBright | bgYellowBright |
|
---|
| 121 | | blue | bgBlue | blueBright | bgBlueBright |
|
---|
| 122 | | magenta | bgMagenta | magentaBright | bgMagentaBright |
|
---|
| 123 | | cyan | bgCyan | cyanBright | bgCyanBright |
|
---|
| 124 | | white | bgWhite | whiteBright | bgWhiteBright |
|
---|
| 125 | | gray | | | |
|
---|
| 126 | | grey | | | |
|
---|
| 127 |
|
---|
| 128 | _(`gray` is the U.S. spelling, `grey` is more commonly used in the Canada and U.K.)_
|
---|
| 129 |
|
---|
| 130 | ### Style modifiers
|
---|
| 131 |
|
---|
| 132 | * dim
|
---|
| 133 | * **bold**
|
---|
| 134 |
|
---|
| 135 | * hidden
|
---|
| 136 | * _italic_
|
---|
| 137 |
|
---|
| 138 | * underline
|
---|
| 139 | * inverse
|
---|
| 140 | * ~~strikethrough~~
|
---|
| 141 |
|
---|
| 142 | * reset
|
---|
| 143 |
|
---|
| 144 | ## Aliases
|
---|
| 145 |
|
---|
| 146 | Create custom aliases for styles.
|
---|
| 147 |
|
---|
| 148 | ```js
|
---|
| 149 | const colors = require('ansi-colors');
|
---|
| 150 |
|
---|
| 151 | colors.alias('primary', colors.yellow);
|
---|
| 152 | colors.alias('secondary', colors.bold);
|
---|
| 153 |
|
---|
| 154 | console.log(colors.primary.secondary('Foo'));
|
---|
| 155 | ```
|
---|
| 156 |
|
---|
| 157 | ## Themes
|
---|
| 158 |
|
---|
| 159 | A theme is an object of custom aliases.
|
---|
| 160 |
|
---|
| 161 | ```js
|
---|
| 162 | const colors = require('ansi-colors');
|
---|
| 163 |
|
---|
| 164 | colors.theme({
|
---|
| 165 | danger: colors.red,
|
---|
| 166 | dark: colors.dim.gray,
|
---|
| 167 | disabled: colors.gray,
|
---|
| 168 | em: colors.italic,
|
---|
| 169 | heading: colors.bold.underline,
|
---|
| 170 | info: colors.cyan,
|
---|
| 171 | muted: colors.dim,
|
---|
| 172 | primary: colors.blue,
|
---|
| 173 | strong: colors.bold,
|
---|
| 174 | success: colors.green,
|
---|
| 175 | underline: colors.underline,
|
---|
| 176 | warning: colors.yellow
|
---|
| 177 | });
|
---|
| 178 |
|
---|
| 179 | // Now, we can use our custom styles alongside the built-in styles!
|
---|
| 180 | console.log(colors.danger.strong.em('Error!'));
|
---|
| 181 | console.log(colors.warning('Heads up!'));
|
---|
| 182 | console.log(colors.info('Did you know...'));
|
---|
| 183 | console.log(colors.success.bold('It worked!'));
|
---|
| 184 | ```
|
---|
| 185 |
|
---|
| 186 | ## Performance
|
---|
| 187 |
|
---|
| 188 | **Libraries tested**
|
---|
| 189 |
|
---|
| 190 | * ansi-colors v3.0.4
|
---|
| 191 | * chalk v2.4.1
|
---|
| 192 |
|
---|
| 193 | ### Mac
|
---|
| 194 |
|
---|
| 195 | > MacBook Pro, Intel Core i7, 2.3 GHz, 16 GB.
|
---|
| 196 |
|
---|
| 197 | **Load time**
|
---|
| 198 |
|
---|
| 199 | Time it takes to load the first time `require()` is called:
|
---|
| 200 |
|
---|
| 201 | * ansi-colors - `1.915ms`
|
---|
| 202 | * chalk - `12.437ms`
|
---|
| 203 |
|
---|
| 204 | **Benchmarks**
|
---|
| 205 |
|
---|
| 206 | ```
|
---|
| 207 | # All Colors
|
---|
| 208 | ansi-colors x 173,851 ops/sec ±0.42% (91 runs sampled)
|
---|
| 209 | chalk x 9,944 ops/sec ±2.53% (81 runs sampled)))
|
---|
| 210 |
|
---|
| 211 | # Chained colors
|
---|
| 212 | ansi-colors x 20,791 ops/sec ±0.60% (88 runs sampled)
|
---|
| 213 | chalk x 2,111 ops/sec ±2.34% (83 runs sampled)
|
---|
| 214 |
|
---|
| 215 | # Nested colors
|
---|
| 216 | ansi-colors x 59,304 ops/sec ±0.98% (92 runs sampled)
|
---|
| 217 | chalk x 4,590 ops/sec ±2.08% (82 runs sampled)
|
---|
| 218 | ```
|
---|
| 219 |
|
---|
| 220 | ### Windows
|
---|
| 221 |
|
---|
| 222 | > Windows 10, Intel Core i7-7700k CPU @ 4.2 GHz, 32 GB
|
---|
| 223 |
|
---|
| 224 | **Load time**
|
---|
| 225 |
|
---|
| 226 | Time it takes to load the first time `require()` is called:
|
---|
| 227 |
|
---|
| 228 | * ansi-colors - `1.494ms`
|
---|
| 229 | * chalk - `11.523ms`
|
---|
| 230 |
|
---|
| 231 | **Benchmarks**
|
---|
| 232 |
|
---|
| 233 | ```
|
---|
| 234 | # All Colors
|
---|
| 235 | ansi-colors x 193,088 ops/sec ±0.51% (95 runs sampled))
|
---|
| 236 | chalk x 9,612 ops/sec ±3.31% (77 runs sampled)))
|
---|
| 237 |
|
---|
| 238 | # Chained colors
|
---|
| 239 | ansi-colors x 26,093 ops/sec ±1.13% (94 runs sampled)
|
---|
| 240 | chalk x 2,267 ops/sec ±2.88% (80 runs sampled))
|
---|
| 241 |
|
---|
| 242 | # Nested colors
|
---|
| 243 | ansi-colors x 67,747 ops/sec ±0.49% (93 runs sampled)
|
---|
| 244 | chalk x 4,446 ops/sec ±3.01% (82 runs sampled))
|
---|
| 245 | ```
|
---|
| 246 |
|
---|
| 247 | ## About
|
---|
| 248 |
|
---|
| 249 | <details>
|
---|
| 250 | <summary><strong>Contributing</strong></summary>
|
---|
| 251 |
|
---|
| 252 | Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
|
---|
| 253 |
|
---|
| 254 | </details>
|
---|
| 255 |
|
---|
| 256 | <details>
|
---|
| 257 | <summary><strong>Running Tests</strong></summary>
|
---|
| 258 |
|
---|
| 259 | 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:
|
---|
| 260 |
|
---|
| 261 | ```sh
|
---|
| 262 | $ npm install && npm test
|
---|
| 263 | ```
|
---|
| 264 |
|
---|
| 265 | </details>
|
---|
| 266 |
|
---|
| 267 | <details>
|
---|
| 268 | <summary><strong>Building docs</strong></summary>
|
---|
| 269 |
|
---|
| 270 | _(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_
|
---|
| 271 |
|
---|
| 272 | To generate the readme, run the following command:
|
---|
| 273 |
|
---|
| 274 | ```sh
|
---|
| 275 | $ npm install -g verbose/verb#dev verb-generate-readme && verb
|
---|
| 276 | ```
|
---|
| 277 |
|
---|
| 278 | </details>
|
---|
| 279 |
|
---|
| 280 | ### Related projects
|
---|
| 281 |
|
---|
| 282 | You might also be interested in these projects:
|
---|
| 283 |
|
---|
| 284 | * [ansi-wrap](https://www.npmjs.com/package/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.")
|
---|
| 285 | * [strip-color](https://www.npmjs.com/package/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.")
|
---|
| 286 |
|
---|
| 287 | ### Contributors
|
---|
| 288 |
|
---|
| 289 | | **Commits** | **Contributor** |
|
---|
| 290 | | --- | --- |
|
---|
| 291 | | 48 | [jonschlinkert](https://github.com/jonschlinkert) |
|
---|
| 292 | | 42 | [doowb](https://github.com/doowb) |
|
---|
| 293 | | 6 | [lukeed](https://github.com/lukeed) |
|
---|
| 294 | | 2 | [Silic0nS0ldier](https://github.com/Silic0nS0ldier) |
|
---|
| 295 | | 1 | [dwieeb](https://github.com/dwieeb) |
|
---|
| 296 | | 1 | [jorgebucaran](https://github.com/jorgebucaran) |
|
---|
| 297 | | 1 | [madhavarshney](https://github.com/madhavarshney) |
|
---|
| 298 | | 1 | [chapterjason](https://github.com/chapterjason) |
|
---|
| 299 |
|
---|
| 300 | ### Author
|
---|
| 301 |
|
---|
| 302 | **Brian Woodward**
|
---|
| 303 |
|
---|
| 304 | * [GitHub Profile](https://github.com/doowb)
|
---|
| 305 | * [Twitter Profile](https://twitter.com/doowb)
|
---|
| 306 | * [LinkedIn Profile](https://linkedin.com/in/woodwardbrian)
|
---|
| 307 |
|
---|
| 308 | ### License
|
---|
| 309 |
|
---|
| 310 | Copyright © 2019, [Brian Woodward](https://github.com/doowb).
|
---|
| 311 | Released under the [MIT License](LICENSE).
|
---|
| 312 |
|
---|
| 313 | ***
|
---|
| 314 |
|
---|
| 315 | _This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on July 01, 2019._ |
---|