1 | # Colorette
|
2 |
|
3 | > Easily set your terminal text color & styles.
|
4 |
|
5 | - No wonky prototype method-chain API.
|
6 | - Automatic color support detection.
|
7 | - Up to [2x faster](#benchmarks) than alternatives.
|
8 | - [`NO_COLOR`](https://no-color.org) friendly. ✅
|
9 |
|
10 | > 👋 [**Upgrading from Colorette `1.x`?**](https://github.com/jorgebucaran/colorette/issues/70)
|
11 |
|
12 | ## Quickstart
|
13 |
|
14 | Here's the first example to get you started.
|
15 |
|
16 | ```js
|
17 | import { blue, bold, underline } from "colorette"
|
18 |
|
19 | console.log(
|
20 | blue("I'm blue"),
|
21 | bold(blue("da ba dee")),
|
22 | underline(bold(blue("da ba daa")))
|
23 | )
|
24 | ```
|
25 |
|
26 | Here's an example using [template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals).
|
27 |
|
28 | ```js
|
29 | console.log(`
|
30 | There's a ${underline(blue("house"))},
|
31 | With a ${bold(blue("window"))},
|
32 | And a ${blue("corvette")}
|
33 | And everything is blue
|
34 | `)
|
35 | ```
|
36 |
|
37 | Of course, you can nest styles without breaking existing color sequences.
|
38 |
|
39 | ```js
|
40 | console.log(bold(`I'm ${blue(`da ba ${underline("dee")} da ba`)} daa`))
|
41 | ```
|
42 |
|
43 | Need to override automatic color detection? You can do that too.
|
44 |
|
45 | ```js
|
46 | import { createColors } from "colorette"
|
47 |
|
48 | const { blue } = createColors({ useColor: false })
|
49 |
|
50 | console.log(blue("Blue? Nope, nah"))
|
51 | ```
|
52 |
|
53 | ## Installation
|
54 |
|
55 | ```console
|
56 | npm install colorette
|
57 | ```
|
58 |
|
59 | ## API
|
60 |
|
61 | ### `blue(text)`
|
62 |
|
63 | > See all [supported colors](#supported-colors).
|
64 |
|
65 | ```js
|
66 | blue("I'm blue") //=> \x1b[34mI'm blue\x1b[39m
|
67 | ```
|
68 |
|
69 | ### `isColorSupported`
|
70 |
|
71 | `true` if your terminal supports color, `false` otherwise. Used internally and handled for you, but exposed for convenience.
|
72 |
|
73 | ### `createColors({ useColor })`
|
74 |
|
75 | Create a reusable instance of Colorette. Color support is automatically detected, but you can override it by setting the `useColor` boolean property.
|
76 |
|
77 | ```js
|
78 | import { createColors } from "colorette"
|
79 |
|
80 | const { blue } = createColors({ useColor: false })
|
81 | ```
|
82 |
|
83 | ## Environment
|
84 |
|
85 | You can override automatic color detection from the CLI too via `NO_COLOR=` or `FORCE_COLOR=`.
|
86 |
|
87 | ```console
|
88 | $ FORCE_COLOR= node example.js | ./consumer.js
|
89 | ```
|
90 |
|
91 | ## Supported colors
|
92 |
|
93 | | Colors | Background Colors | Bright Colors | Bright Background Colors | Modifiers |
|
94 | | ------- | ----------------- | ------------- | ------------------------ | ----------------- |
|
95 | | black | bgBlack | blackBright | bgBlackBright | dim |
|
96 | | red | bgRed | redBright | bgRedBright | **bold** |
|
97 | | green | bgGreen | greenBright | bgGreenBright | hidden |
|
98 | | yellow | bgYellow | yellowBright | bgYellowBright | _italic_ |
|
99 | | blue | bgBlue | blueBright | bgBlueBright | <u>underline</u> |
|
100 | | magenta | bgMagenta | magentaBright | bgMagentaBright | ~~strikethrough~~ |
|
101 | | cyan | bgCyan | cyanBright | bgCyanBright | reset |
|
102 | | white | bgWhite | whiteBright | bgWhiteBright | |
|
103 | | gray | | | | |
|
104 |
|
105 | ## [Benchmarks](https://github.com/jorgebucaran/colorette/actions/workflows/bench.yml)
|
106 |
|
107 | ```console
|
108 | npm --prefix bench start
|
109 | ```
|
110 |
|
111 | ## License
|
112 |
|
113 | [MIT](LICENSE.md)
|