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
|
## Performance
|
145
|
|
146
|
**Libraries tested**
|
147
|
|
148
|
* ansi-colors v3.0.4
|
149
|
* chalk v2.4.1
|
150
|
|
151
|
### Mac
|
152
|
|
153
|
> MacBook Pro, Intel Core i7, 2.3 GHz, 16 GB.
|
154
|
|
155
|
**Load time**
|
156
|
|
157
|
Time it takes to load the first time `require()` is called:
|
158
|
|
159
|
* ansi-colors - `1.915ms`
|
160
|
* chalk - `12.437ms`
|
161
|
|
162
|
**Benchmarks**
|
163
|
|
164
|
```
|
165
|
# All Colors
|
166
|
ansi-colors x 173,851 ops/sec ±0.42% (91 runs sampled)
|
167
|
chalk x 9,944 ops/sec ±2.53% (81 runs sampled)))
|
168
|
|
169
|
# Chained colors
|
170
|
ansi-colors x 20,791 ops/sec ±0.60% (88 runs sampled)
|
171
|
chalk x 2,111 ops/sec ±2.34% (83 runs sampled)
|
172
|
|
173
|
# Nested colors
|
174
|
ansi-colors x 59,304 ops/sec ±0.98% (92 runs sampled)
|
175
|
chalk x 4,590 ops/sec ±2.08% (82 runs sampled)
|
176
|
```
|
177
|
|
178
|
### Windows
|
179
|
|
180
|
> Windows 10, Intel Core i7-7700k CPU @ 4.2 GHz, 32 GB
|
181
|
|
182
|
**Load time**
|
183
|
|
184
|
Time it takes to load the first time `require()` is called:
|
185
|
|
186
|
* ansi-colors - `1.494ms`
|
187
|
* chalk - `11.523ms`
|
188
|
|
189
|
**Benchmarks**
|
190
|
|
191
|
```
|
192
|
# All Colors
|
193
|
ansi-colors x 193,088 ops/sec ±0.51% (95 runs sampled))
|
194
|
chalk x 9,612 ops/sec ±3.31% (77 runs sampled)))
|
195
|
|
196
|
# Chained colors
|
197
|
ansi-colors x 26,093 ops/sec ±1.13% (94 runs sampled)
|
198
|
chalk x 2,267 ops/sec ±2.88% (80 runs sampled))
|
199
|
|
200
|
# Nested colors
|
201
|
ansi-colors x 67,747 ops/sec ±0.49% (93 runs sampled)
|
202
|
chalk x 4,446 ops/sec ±3.01% (82 runs sampled))
|
203
|
```
|
204
|
|
205
|
## About
|
206
|
|
207
|
<details>
|
208
|
<summary><strong>Contributing</strong></summary>
|
209
|
|
210
|
Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
|
211
|
|
212
|
</details>
|
213
|
|
214
|
<details>
|
215
|
<summary><strong>Running Tests</strong></summary>
|
216
|
|
217
|
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:
|
218
|
|
219
|
```sh
|
220
|
$ npm install && npm test
|
221
|
```
|
222
|
|
223
|
</details>
|
224
|
|
225
|
<details>
|
226
|
<summary><strong>Building docs</strong></summary>
|
227
|
|
228
|
_(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.)_
|
229
|
|
230
|
To generate the readme, run the following command:
|
231
|
|
232
|
```sh
|
233
|
$ npm install -g verbose/verb#dev verb-generate-readme && verb
|
234
|
```
|
235
|
|
236
|
</details>
|
237
|
|
238
|
### Related projects
|
239
|
|
240
|
You might also be interested in these projects:
|
241
|
|
242
|
* [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.")
|
243
|
* [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.")
|
244
|
|
245
|
### Contributors
|
246
|
|
247
|
| **Commits** | **Contributor** |
|
248
|
| --- | --- |
|
249
|
| 42 | [doowb](https://github.com/doowb) |
|
250
|
| 38 | [jonschlinkert](https://github.com/jonschlinkert) |
|
251
|
| 6 | [lukeed](https://github.com/lukeed) |
|
252
|
| 2 | [Silic0nS0ldier](https://github.com/Silic0nS0ldier) |
|
253
|
| 1 | [dwieeb](https://github.com/dwieeb) |
|
254
|
| 1 | [jorgebucaran](https://github.com/jorgebucaran) |
|
255
|
| 1 | [madhavarshney](https://github.com/madhavarshney) |
|
256
|
| 1 | [chapterjason](https://github.com/chapterjason) |
|
257
|
|
258
|
### Author
|
259
|
|
260
|
**Brian Woodward**
|
261
|
|
262
|
* [GitHub Profile](https://github.com/doowb)
|
263
|
* [Twitter Profile](https://twitter.com/doowb)
|
264
|
* [LinkedIn Profile](https://linkedin.com/in/woodwardbrian)
|
265
|
|
266
|
Please consider supporting me on Patreon, or [start your own Patreon page](https://patreon.com/invite/bxpbvm)!
|
267
|
|
268
|
<a href="https://www.patreon.com/jonschlinkert">
|
269
|
<img src="https://c5.patreon.com/external/logo/become_a_patron_button@2x.png" height="50">
|
270
|
</a>
|
271
|
|
272
|
### License
|
273
|
|
274
|
Copyright © 2019, [Brian Woodward](https://github.com/doowb).
|
275
|
Released under the [MIT License](LICENSE).
|
276
|
|
277
|
***
|
278
|
|
279
|
_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on March 03, 2019._
|