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._ |
\ | No newline at end of file |