chalk @ 2.4.2 - readme.md
1
<h1 align="center">
2
<br>
3
<br>
4
<img width="320" src="media/logo.svg" alt="Chalk">
5
<br>
6
<br>
7
<br>
8
</h1>
9
10
> Terminal string styling done right
11
12
[![Build Status](https://travis-ci.org/chalk/chalk.svg?branch=master)](https://travis-ci.org/chalk/chalk) [![Coverage Status](https://coveralls.io/repos/github/chalk/chalk/badge.svg?branch=master)](https://coveralls.io/github/chalk/chalk?branch=master) [![](https://img.shields.io/badge/unicorn-approved-ff69b4.svg)](https://www.youtube.com/watch?v=9auOCbH5Ns4) [![XO code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/xojs/xo) [![Mentioned in Awesome Node.js](https://awesome.re/mentioned-badge.svg)](https://github.com/sindresorhus/awesome-nodejs)
13
14
### [See what's new in Chalk 2](https://github.com/chalk/chalk/releases/tag/v2.0.0)
15
16
<img src="https://cdn.rawgit.com/chalk/ansi-styles/8261697c95bf34b6c7767e2cbe9941a851d59385/screenshot.svg" alt="" width="900">
17
18
19
## Highlights
20
21
- Expressive API
22
- Highly performant
23
- Ability to nest styles
24
- [256/Truecolor color support](#256-and-truecolor-color-support)
25
- Auto-detects color support
26
- Doesn't extend `String.prototype`
27
- Clean and focused
28
- Actively maintained
29
- [Used by ~23,000 packages](https://www.npmjs.com/browse/depended/chalk) as of December 31, 2017
30
31
32
## Install
33
34
```console
35
$ npm install chalk
36
```
37
38
<a href="https://www.patreon.com/sindresorhus">
39
<img src="https://c5.patreon.com/external/logo/become_a_patron_button@2x.png" width="160">
40
</a>
41
42
43
## Usage
44
45
```js
46
const chalk = require('chalk');
47
48
console.log(chalk.blue('Hello world!'));
49
```
50
51
Chalk comes with an easy to use composable API where you just chain and nest the styles you want.
52
53
```js
54
const chalk = require('chalk');
55
const log = console.log;
56
57
// Combine styled and normal strings
58
log(chalk.blue('Hello') + ' World' + chalk.red('!'));
59
60
// Compose multiple styles using the chainable API
61
log(chalk.blue.bgRed.bold('Hello world!'));
62
63
// Pass in multiple arguments
64
log(chalk.blue('Hello', 'World!', 'Foo', 'bar', 'biz', 'baz'));
65
66
// Nest styles
67
log(chalk.red('Hello', chalk.underline.bgBlue('world') + '!'));
68
69
// Nest styles of the same type even (color, underline, background)
70
log(chalk.green(
71
'I am a green line ' +
72
chalk.blue.underline.bold('with a blue substring') +
73
' that becomes green again!'
74
));
75
76
// ES2015 template literal
77
log(`
78
CPU: ${chalk.red('90%')}
79
RAM: ${chalk.green('40%')}
80
DISK: ${chalk.yellow('70%')}
81
`);
82
83
// ES2015 tagged template literal
84
log(chalk`
85
CPU: {red ${cpu.totalPercent}%}
86
RAM: {green ${ram.used / ram.total * 100}%}
87
DISK: {rgb(255,131,0) ${disk.used / disk.total * 100}%}
88
`);
89
90
// Use RGB colors in terminal emulators that support it.
91
log(chalk.keyword('orange')('Yay for orange colored text!'));
92
log(chalk.rgb(123, 45, 67).underline('Underlined reddish color'));
93
log(chalk.hex('#DEADED').bold('Bold gray!'));
94
```
95
96
Easily define your own themes:
97
98
```js
99
const chalk = require('chalk');
100
101
const error = chalk.bold.red;
102
const warning = chalk.keyword('orange');
103
104
console.log(error('Error!'));
105
console.log(warning('Warning!'));
106
```
107
108
Take advantage of console.log [string substitution](https://nodejs.org/docs/latest/api/console.html#console_console_log_data_args):
109
110
```js
111
const name = 'Sindre';
112
console.log(chalk.green('Hello %s'), name);
113
//=> 'Hello Sindre'
114
```
115
116
117
## API
118
119
### chalk.`<style>[.<style>...](string, [string...])`
120
121
Example: `chalk.red.bold.underline('Hello', 'world');`
122
123
Chain [styles](#styles) and call the last one as a method with a string argument. Order doesn't matter, and later styles take precedent in case of a conflict. This simply means that `chalk.red.yellow.green` is equivalent to `chalk.green`.
124
125
Multiple arguments will be separated by space.
126
127
### chalk.enabled
128
129
Color support is automatically detected, as is the level (see `chalk.level`). However, if you'd like to simply enable/disable Chalk, you can do so via the `.enabled` property.
130
131
Chalk is enabled by default unless explicitly disabled via the constructor or `chalk.level` is `0`.
132
133
If you need to change this in a reusable module, create a new instance:
134
135
```js
136
const ctx = new chalk.constructor({enabled: false});
137
```
138
139
### chalk.level
140
141
Color support is automatically detected, but you can override it by setting the `level` property. You should however only do this in your own code as it applies globally to all Chalk consumers.
142
143
If you need to change this in a reusable module, create a new instance:
144
145
```js
146
const ctx = new chalk.constructor({level: 0});
147
```
148
149
Levels are as follows:
150
151
0. All colors disabled
152
1. Basic color support (16 colors)
153
2. 256 color support
154
3. Truecolor support (16 million colors)
155
156
### chalk.supportsColor
157
158
Detect whether the terminal [supports color](https://github.com/chalk/supports-color). Used internally and handled for you, but exposed for convenience.
159
160
Can be overridden by the user with the flags `--color` and `--no-color`. For situations where using `--color` is not possible, add the environment variable `FORCE_COLOR=1` to forcefully enable color or `FORCE_COLOR=0` to forcefully disable. The use of `FORCE_COLOR` overrides all other color support checks.
161
162
Explicit 256/Truecolor mode can be enabled using the `--color=256` and `--color=16m` flags, respectively.
163
164
165
## Styles
166
167
### Modifiers
168
169
- `reset`
170
- `bold`
171
- `dim`
172
- `italic` *(Not widely supported)*
173
- `underline`
174
- `inverse`
175
- `hidden`
176
- `strikethrough` *(Not widely supported)*
177
- `visible` (Text is emitted only if enabled)
178
179
### Colors
180
181
- `black`
182
- `red`
183
- `green`
184
- `yellow`
185
- `blue` *(On Windows the bright version is used since normal blue is illegible)*
186
- `magenta`
187
- `cyan`
188
- `white`
189
- `gray` ("bright black")
190
- `redBright`
191
- `greenBright`
192
- `yellowBright`
193
- `blueBright`
194
- `magentaBright`
195
- `cyanBright`
196
- `whiteBright`
197
198
### Background colors
199
200
- `bgBlack`
201
- `bgRed`
202
- `bgGreen`
203
- `bgYellow`
204
- `bgBlue`
205
- `bgMagenta`
206
- `bgCyan`
207
- `bgWhite`
208
- `bgBlackBright`
209
- `bgRedBright`
210
- `bgGreenBright`
211
- `bgYellowBright`
212
- `bgBlueBright`
213
- `bgMagentaBright`
214
- `bgCyanBright`
215
- `bgWhiteBright`
216
217
218
## Tagged template literal
219
220
Chalk can be used as a [tagged template literal](http://exploringjs.com/es6/ch_template-literals.html#_tagged-template-literals).
221
222
```js
223
const chalk = require('chalk');
224
225
const miles = 18;
226
const calculateFeet = miles => miles * 5280;
227
228
console.log(chalk`
229
There are {bold 5280 feet} in a mile.
230
In {bold ${miles} miles}, there are {green.bold ${calculateFeet(miles)} feet}.
231
`);
232
```
233
234
Blocks are delimited by an opening curly brace (`{`), a style, some content, and a closing curly brace (`}`).
235
236
Template styles are chained exactly like normal Chalk styles. The following two statements are equivalent:
237
238
```js
239
console.log(chalk.bold.rgb(10, 100, 200)('Hello!'));
240
console.log(chalk`{bold.rgb(10,100,200) Hello!}`);
241
```
242
243
Note that function styles (`rgb()`, `hsl()`, `keyword()`, etc.) may not contain spaces between parameters.
244
245
All interpolated values (`` chalk`${foo}` ``) are converted to strings via the `.toString()` method. All curly braces (`{` and `}`) in interpolated value strings are escaped.
246
247
248
## 256 and Truecolor color support
249
250
Chalk supports 256 colors and [Truecolor](https://gist.github.com/XVilka/8346728) (16 million colors) on supported terminal apps.
251
252
Colors are downsampled from 16 million RGB values to an ANSI color format that is supported by the terminal emulator (or by specifying `{level: n}` as a Chalk option). For example, Chalk configured to run at level 1 (basic color support) will downsample an RGB value of #FF0000 (red) to 31 (ANSI escape for red).
253
254
Examples:
255
256
- `chalk.hex('#DEADED').underline('Hello, world!')`
257
- `chalk.keyword('orange')('Some orange text')`
258
- `chalk.rgb(15, 100, 204).inverse('Hello!')`
259
260
Background versions of these models are prefixed with `bg` and the first level of the module capitalized (e.g. `keyword` for foreground colors and `bgKeyword` for background colors).
261
262
- `chalk.bgHex('#DEADED').underline('Hello, world!')`
263
- `chalk.bgKeyword('orange')('Some orange text')`
264
- `chalk.bgRgb(15, 100, 204).inverse('Hello!')`
265
266
The following color models can be used:
267
268
- [`rgb`](https://en.wikipedia.org/wiki/RGB_color_model) - Example: `chalk.rgb(255, 136, 0).bold('Orange!')`
269
- [`hex`](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet) - Example: `chalk.hex('#FF8800').bold('Orange!')`
270
- [`keyword`](https://www.w3.org/wiki/CSS/Properties/color/keywords) (CSS keywords) - Example: `chalk.keyword('orange').bold('Orange!')`
271
- [`hsl`](https://en.wikipedia.org/wiki/HSL_and_HSV) - Example: `chalk.hsl(32, 100, 50).bold('Orange!')`
272
- [`hsv`](https://en.wikipedia.org/wiki/HSL_and_HSV) - Example: `chalk.hsv(32, 100, 100).bold('Orange!')`
273
- [`hwb`](https://en.wikipedia.org/wiki/HWB_color_model) - Example: `chalk.hwb(32, 0, 50).bold('Orange!')`
274
- `ansi16`
275
- `ansi256`
276
277
278
## Windows
279
280
If you're on Windows, do yourself a favor and use [`cmder`](http://cmder.net/) instead of `cmd.exe`.
281
282
283
## Origin story
284
285
[colors.js](https://github.com/Marak/colors.js) used to be the most popular string styling module, but it has serious deficiencies like extending `String.prototype` which causes all kinds of [problems](https://github.com/yeoman/yo/issues/68) and the package is unmaintained. Although there are other packages, they either do too much or not enough. Chalk is a clean and focused alternative.
286
287
288
## Related
289
290
- [chalk-cli](https://github.com/chalk/chalk-cli) - CLI for this module
291
- [ansi-styles](https://github.com/chalk/ansi-styles) - ANSI escape codes for styling strings in the terminal
292
- [supports-color](https://github.com/chalk/supports-color) - Detect whether a terminal supports color
293
- [strip-ansi](https://github.com/chalk/strip-ansi) - Strip ANSI escape codes
294
- [strip-ansi-stream](https://github.com/chalk/strip-ansi-stream) - Strip ANSI escape codes from a stream
295
- [has-ansi](https://github.com/chalk/has-ansi) - Check if a string has ANSI escape codes
296
- [ansi-regex](https://github.com/chalk/ansi-regex) - Regular expression for matching ANSI escape codes
297
- [wrap-ansi](https://github.com/chalk/wrap-ansi) - Wordwrap a string with ANSI escape codes
298
- [slice-ansi](https://github.com/chalk/slice-ansi) - Slice a string with ANSI escape codes
299
- [color-convert](https://github.com/qix-/color-convert) - Converts colors between different models
300
- [chalk-animation](https://github.com/bokub/chalk-animation) - Animate strings in the terminal
301
- [gradient-string](https://github.com/bokub/gradient-string) - Apply color gradients to strings
302
- [chalk-pipe](https://github.com/LitoMore/chalk-pipe) - Create chalk style schemes with simpler style strings
303
- [terminal-link](https://github.com/sindresorhus/terminal-link) - Create clickable links in the terminal
304
305
306
## Maintainers
307
308
- [Sindre Sorhus](https://github.com/sindresorhus)
309
- [Josh Junon](https://github.com/qix-)
310
311
312
## License
313
314
MIT
315