UNPKG

6.14 kBMarkdownView Raw
1<h1 align="center">
2 <br>
3 <br>
4 <img width="360" src="https://cdn.rawgit.com/chalk/chalk/19935d6484811c5e468817f846b7b3d417d7bf4a/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)
13[![Coverage Status](https://coveralls.io/repos/chalk/chalk/badge.svg?branch=master)](https://coveralls.io/r/chalk/chalk?branch=master)
14[![](http://img.shields.io/badge/unicorn-approved-ff69b4.svg)](https://www.youtube.com/watch?v=9auOCbH5Ns4)
15
16
17[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). Although there are other ones, they either do too much or not enough.
18
19**Chalk is a clean and focused alternative.**
20
21![](https://github.com/chalk/ansi-styles/raw/master/screenshot.png)
22
23
24## Why
25
26- Highly performant
27- Doesn't extend `String.prototype`
28- Expressive API
29- Ability to nest styles
30- Clean and focused
31- Auto-detects color support
32- Actively maintained
33- [Used by ~4500 modules](https://www.npmjs.com/browse/depended/chalk) as of July 15, 2015
34
35
36## Install
37
38```
39$ npm install --save chalk
40```
41
42
43## Usage
44
45Chalk comes with an easy to use composable API where you just chain and nest the styles you want.
46
47```js
48var chalk = require('chalk');
49
50// style a string
51chalk.blue('Hello world!');
52
53// combine styled and normal strings
54chalk.blue('Hello') + 'World' + chalk.red('!');
55
56// compose multiple styles using the chainable API
57chalk.blue.bgRed.bold('Hello world!');
58
59// pass in multiple arguments
60chalk.blue('Hello', 'World!', 'Foo', 'bar', 'biz', 'baz');
61
62// nest styles
63chalk.red('Hello', chalk.underline.bgBlue('world') + '!');
64
65// nest styles of the same type even (color, underline, background)
66chalk.green(
67 'I am a green line ' +
68 chalk.blue.underline.bold('with a blue substring') +
69 ' that becomes green again!'
70);
71```
72
73Easily define your own themes.
74
75```js
76var chalk = require('chalk');
77var error = chalk.bold.red;
78console.log(error('Error!'));
79```
80
81Take advantage of console.log [string substitution](http://nodejs.org/docs/latest/api/console.html#console_console_log_data).
82
83```js
84var name = 'Sindre';
85console.log(chalk.green('Hello %s'), name);
86//=> Hello Sindre
87```
88
89
90## API
91
92### chalk.`<style>[.<style>...](string, [string...])`
93
94Example: `chalk.red.bold.underline('Hello', 'world');`
95
96Chain [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`.
97
98Multiple arguments will be separated by space.
99
100### chalk.enabled
101
102Color support is automatically detected, but you can override it by setting the `enabled` property. You should however only do this in your own code as it applies globally to all chalk consumers.
103
104If you need to change this in a reusable module create a new instance:
105
106```js
107var ctx = new chalk.constructor({enabled: false});
108```
109
110### chalk.supportsColor
111
112Detect whether the terminal [supports color](https://github.com/chalk/supports-color). Used internally and handled for you, but exposed for convenience.
113
114Can be overridden by the user with the flags `--color` and `--no-color`. For situations where using `--color` is not possible, add an environment variable `FORCE_COLOR` with any value to force color. Trumps `--no-color`.
115
116### chalk.styles
117
118Exposes the styles as [ANSI escape codes](https://github.com/chalk/ansi-styles).
119
120Generally not useful, but you might need just the `.open` or `.close` escape code if you're mixing externally styled strings with your own.
121
122```js
123var chalk = require('chalk');
124
125console.log(chalk.styles.red);
126//=> {open: '\u001b[31m', close: '\u001b[39m'}
127
128console.log(chalk.styles.red.open + 'Hello' + chalk.styles.red.close);
129```
130
131### chalk.hasColor(string)
132
133Check whether a string [has color](https://github.com/chalk/has-ansi).
134
135### chalk.stripColor(string)
136
137[Strip color](https://github.com/chalk/strip-ansi) from a string.
138
139Can be useful in combination with `.supportsColor` to strip color on externally styled text when it's not supported.
140
141Example:
142
143```js
144var chalk = require('chalk');
145var styledString = getText();
146
147if (!chalk.supportsColor) {
148 styledString = chalk.stripColor(styledString);
149}
150```
151
152
153## Styles
154
155### Modifiers
156
157- `reset`
158- `bold`
159- `dim`
160- `italic` *(not widely supported)*
161- `underline`
162- `inverse`
163- `hidden`
164- `strikethrough` *(not widely supported)*
165
166### Colors
167
168- `black`
169- `red`
170- `green`
171- `yellow`
172- `blue` *(on Windows the bright version is used as normal blue is illegible)*
173- `magenta`
174- `cyan`
175- `white`
176- `gray`
177
178### Background colors
179
180- `bgBlack`
181- `bgRed`
182- `bgGreen`
183- `bgYellow`
184- `bgBlue`
185- `bgMagenta`
186- `bgCyan`
187- `bgWhite`
188
189
190## 256-colors
191
192Chalk does not support anything other than the base eight colors, which guarantees it will work on all terminals and systems. Some terminals, specifically `xterm` compliant ones, will support the full range of 8-bit colors. For this the lower level [ansi-256-colors](https://github.com/jbnicolai/ansi-256-colors) package can be used.
193
194
195## Windows
196
197If you're on Windows, do yourself a favor and use [`cmder`](http://bliker.github.io/cmder/) instead of `cmd.exe`.
198
199
200## Related
201
202- [chalk-cli](https://github.com/chalk/chalk-cli) - CLI for this module
203- [ansi-styles](https://github.com/chalk/ansi-styles/) - ANSI escape codes for styling strings in the terminal
204- [supports-color](https://github.com/chalk/supports-color/) - Detect whether a terminal supports color
205- [strip-ansi](https://github.com/chalk/strip-ansi) - Strip ANSI escape codes
206- [has-ansi](https://github.com/chalk/has-ansi) - Check if a string has ANSI escape codes
207- [ansi-regex](https://github.com/chalk/ansi-regex) - Regular expression for matching ANSI escape codes
208- [wrap-ansi](https://github.com/chalk/wrap-ansi) - Wordwrap a string with ANSI escape codes
209
210
211## License
212
213MIT © [Sindre Sorhus](http://sindresorhus.com)