UNPKG

3.82 kB Markdown View Raw
1# Colorette [![](https://img.shields.io/npm/v/colorette.svg?label=&color=0080ff)](https://www.npmjs.org/package/colorette) [![CI](https://img.shields.io/travis/jorgebucaran/colorette.svg?label=)](https://travis-ci.org/jorgebucaran/colorette)
2
3> Color your terminal using pure idiomatic JavaScript.
4
5Colorette is a Node.js library for embellishing your CLI tools with colors and styles using [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code).
6
7- Up to ~10x faster than the alternatives ([run the benchmarks](#run-the-benchmarks)).
8- No wonky prototype-based method chains.
9- Automatic color support detection.
10- ~80 LOC and no dependencies.
11- [`NO_COLOR`](https://no-color.org) friendly.
12
13## Quickstart
14
15```console
16npm i colorette
17```
18
19Load the [styles](#styles) you need. [Here](#supported-styles)'s the list of the styles you can use.
20
21```js
22const { red, blue, bold } = require("colorette")
23```
24
25Wrap your strings in one or more styles to produce the finish you're looking for.
26
27```js
28console.log(bold(blue("Engage!")))
29```
30
31Or mix it with [template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) to interpolate variables, expressions and create multi-line strings easily.
32
33```js
34console.log(`
35 Beets are ${red("red")},
36 Plums are ${blue("blue")},
37 ${bold("Colorette!")}.
38`)
39```
40
41Using `console.log`'s [string substitution](https://nodejs.org/api/console.html#console_console_log_data_args) can be useful too!
42
43```js
44console.log(bold("Total: $%f"), 1.99)
45```
46
47You can even nest styles without breaking existing escape codes.
48
49```js
50console.log(red(`Red Shirt ${blue("Blue Shirt")} Red Shirt`))
51```
52
53Feeling adventurous? Try the [pipeline operator](https://github.com/tc39/proposal-pipeline-operator).
54
55```js
56console.log("Make it so!" |> bold |> blue)
57```
58
59## Supported styles
60
61Colorette supports the standard and bright color variations out-of-the-box. For true color support see [this issue](https://github.com/jorgebucaran/colorette/issues/27).
62
63| Colors | Background Colors | Bright Colors | Bright Background Colors | Modifiers |
64| ------- | ----------------- | ------------- | ------------------------ | ----------------- |
65| black | bgBlack | blackBright | bgBlackBright | dim |
66| red | bgRed | redBright | bgRedBright | **bold** |
67| green | bgGreen | greenBright | bgGreenBright | hidden |
68| yellow | bgYellow | yellowBright | bgYellowBright | _italic_ |
69| blue | bgBlue | blueBright | bgBlueBright | underline |
70| magenta | bgMagenta | magentaBright | bgMagentaBright | ~~strikethrough~~ |
71| cyan | bgCyan | cyanBright | bgCyanBright | reset |
72| white | bgWhite | whiteBright | bgWhiteBright | |
73| gray | | | | |
74
75## API
76
77### <code><i>style</i>(string)</code>
78
79Returns a string wrapped in the corresponding ANSI escape code.
80
81```js
82red("Red Alert") //=> \u001b[31mRed Alert\u001b[39m
83```
84
85### `options.enabled`
86
87Colorette is enabled if your terminal supports color, `FORCE_COLOR=1` or if `NO_COLOR` isn't in the environment, but you can always override it when you need to.
88
89```js
90const { options } = require("colorette")
91
92options.enabled = false
93```
94
95## Run the benchmarks
96
97```
98npm i -C bench && node bench
99```
100
101<pre>
102# Using Styles
103chalk × 14,468 ops/sec
104colorette × 901,148 ops/sec
105
106# Combining Styles
107chalk × 44,067 ops/sec
108colorette × 2,566,778 ops/sec
109
110# Nesting Styles
111chalk × 40,165 ops/sec
112colorette × 506,494 ops/sec
113</pre>
114
115## License
116
117[MIT](LICENSE.md)