[![*nix build status][nix-build-image]][nix-build-url]
[![Windows build status][win-build-image]][win-build-url]
![Transpilation status][transpilation-image]
[![npm version][npm-image]][npm-url]
# cli-color
## Yet another colors and formatting for the console solution
Colors, formatting and other goodies for the console. This package won't mess with built-ins and provides neat way to predefine formatting patterns, see below.
## Installation
$ npm install cli-color
## Usage
Usage:
```javascript
var clc = require("cli-color");
```
Output colored text:
```javascript
console.log(clc.red("Text in red"));
```
Styles can be mixed:
```javascript
console.log(clc.red.bgWhite.underline("Underlined red text on white background."));
```
Styled text can be mixed with unstyled:
```javascript
console.log(clc.red("red") + " plain " + clc.blue("blue"));
```
Styled text can be nested:
```javascript
console.log(clc.red("red " + clc.blue("blue") + " red"));
```
**Best way is to predefine needed stylings and then use it**:
```javascript
var error = clc.red.bold;
var warn = clc.yellow;
var notice = clc.blue;
console.log(error("Error!"));
console.log(warn("Warning"));
console.log(notice("Notice"));
```
_Note: No colors or styles are output when [`NO_COLOR` env var](https://no-color.org/) is set_
Supported are all ANSI colors and styles:
#### Styles
Styles will display correctly if font used in your console supports them.
- bold
- italic
- underline
- blink
- inverse
- strike
#### Colors
| Foreground | Background | |
| black | bgBlack |  |
| red | bgRed |  |
| green | bgGreen |  |
| yellow | bgYellow |  |
| blue | bgBlue |  |
| magenta | bgMagenta |  |
| cyan | bgCyan |  |
| white | bgWhite |  |
##### Bright variants
| Foreground | Background | |
| blackBright | bgBlackBright |  |
| redBright | bgRedBright |  |
| greenBright | bgGreenBright |  |
| yellowBright | bgYellowBright |  |
| blueBright | bgBlueBright |  |
| magentaBright | bgMagentaBright |  |
| cyanBright | bgCyanBright |  |
| whiteBright | bgWhiteBright |  |
##### xTerm colors (256 colors table)
**Not supported on Windows and some terminals**. However if used in not supported environment, the closest color from basic (16 colors) palette is chosen.
Usage:
```javascript
var msg = clc.xterm(202).bgXterm(236);
console.log(msg("Orange text on dark gray background"));
```
Color table:
| 0 | |
1 | |
2 | |
3 | |
4 | |
5 | |
6 | |
7 | |
| 8 | |
9 | |
10 | |
11 | |
12 | |
13 | |
14 | |
15 | |
| 16 | |
17 |  |
18 |  |
19 |  |
20 |  |
21 | |
| 22 |  |
23 |  |
24 |  |
25 |  |
26 |  |
27 |  |
| 28 |  |
29 |  |
30 |  |
31 |  |
32 |  |
33 |  |
| 34 |  |
35 |  |
36 |  |
37 |  |
38 |  |
39 |  |
| 40 |  |
41 |  |
42 |  |
43 |  |
44 |  |
45 |  |
| 46 | |
47 |  |
48 |  |
49 |  |
50 |  |
51 | |
| 52 |  |
53 |  |
54 |  |
55 |  |
56 |  |
57 |  |
| 58 |  |
59 |  |
60 |  |
61 |  |
62 |  |
63 |  |
| 64 |  |
65 |  |
66 |  |
67 |  |
68 |  |
69 |  |
| 70 |  |
71 |  |
72 |  |
73 |  |
74 |  |
75 |  |
| 76 |  |
77 |  |
78 |  |
79 |  |
80 |  |
81 |  |
| 82 |  |
83 |  |
84 |  |
85 |  |
86 |  |
87 |  |
| 88 |  |
89 |  |
90 |  |
91 |  |
92 |  |
93 |  |
| 94 |  |
95 |  |
96 |  |
97 |  |
98 |  |
99 |  |
| 100 |  |
101 |  |
102 |  |
103 |  |
104 |  |
105 |  |
| 106 |  |
107 |  |
108 |  |
109 |  |
110 |  |
111 |  |
| 112 |  |
113 |  |
114 |  |
115 |  |
116 |  |
117 |  |
| 118 |  |
119 |  |
120 |  |
121 |  |
122 |  |
123 |  |
| 124 |  |
125 |  |
126 |  |
127 |  |
128 |  |
129 |  |
| 130 |  |
131 |  |
132 |  |
133 |  |
134 |  |
135 |  |
| 136 |  |
137 |  |
138 |  |
139 |  |
140 |  |
141 |  |
| 142 |  |
143 |  |
144 |  |
145 |  |
146 |  |
147 |  |
| 148 |  |
149 |  |
150 |  |
151 |  |
152 |  |
153 |  |
| 154 |  |
155 |  |
156 |  |
157 |  |
158 |  |
159 |  |
| 160 |  |
161 |  |
162 |  |
163 |  |
164 |  |
165 |  |
| 166 |  |
167 |  |
168 |  |
169 |  |
170 |  |
171 |  |
| 172 |  |
173 |  |
174 |  |
175 |  |
176 |  |
177 |  |
| 178 |  |
179 |  |
180 |  |
181 |  |
182 |  |
183 |  |
| 184 |  |
185 |  |
186 |  |
187 |  |
188 |  |
189 |  |
| 190 |  |
191 |  |
192 |  |
193 |  |
194 |  |
195 |  |
| 196 | |
197 |  |
198 |  |
199 |  |
200 |  |
201 | |
| 202 |  |
203 |  |
204 |  |
205 |  |
206 |  |
207 |  |
| 208 |  |
209 |  |
210 |  |
211 |  |
212 |  |
213 |  |
| 214 |  |
215 |  |
216 |  |
217 |  |
218 |  |
219 |  |
| 220 |  |
221 |  |
222 |  |
223 |  |
224 |  |
225 |  |
| 226 | |
227 |  |
228 |  |
229 |  |
230 |  |
231 | |
| 232 |  |
233 |  |
234 |  |
235 |  |
236 |  |
237 |  |
| 238 |  |
239 |  |
240 |  |
241 |  |
242 |  |
243 |  |
| 244 | |
245 |  |
246 |  |
247 |  |
248 |  |
249 |  |
| 250 |  |
251 |  |
252 |  |
253 |  |
254 |  |
255 |  |
#### Reset
Terminal can be cleared with `clc.reset`
```javascript
process.stdout.write(clc.reset);
```
#### Erase
##### clc.erase.screen
Entire screen
```javascript
process.stdout.write(clc.erase.screen);
```
##### clc.erase.screenLeft
Left portion of a screen
```javascript
process.stdout.write(clc.erase.screenLeft);
```
##### clc.erase.screenRight
Right portion of a screen
```javascript
process.stdout.write(clc.erase.screenRight);
```
##### clc.erase.line
Current line
```javascript
process.stdout.write(clc.erase.line);
```
##### clc.erase.lineRight
Right portion of current line
```javascript
process.stdout.write(clc.erase.lineRight);
```
##### clc.erase.lineLeft
Left portion of current line
```javascript
process.stdout.write(clc.erase.lineLeft);
```
#### Move around functions
##### clc.move(x, y)
Move cursor _x_ columns and _y_ rows away. Values can be positive or negative, e.g.:
```javascript
process.stdout.write(clc.move(-2, -2)); // Move cursors two columns and two rows back
```
##### clc.move.to(x, y)
Absolute move. Sets cursor position at _x_ column and _y_ row
```javascript
process.stdout.write(clc.move.to(0, 0)); // Move cursor to first row and first column in terminal window
```
##### clc.move.up(n)
Move cursor up _n_ rows
```javascript
process.stdout.write(clc.move.up(2));
```
##### clc.move.down(n)
Move cursor down _n_ rows
```javascript
process.stdout.write(clc.move.down(2));
```
##### clc.move.right(n)
Move cursor right _n_ columns
```javascript
process.stdout.write(clc.move.right(2));
```
##### clc.move.left(n)
Move cursor left _n_ columns
```javascript
process.stdout.write(clc.move.left(2));
```
##### clc.move.lines(n)
Move cursor `n` lines forward if `n` is positive, otherwise `n` lines backward, and place it at line beginning
```javascript
process.stdout.write(clc.move.lines(2));
```
##### clc.move.top
Move cursor to top of a screen
```javascript
process.stdout.write(clc.move.top);
```
##### clc.move.bottom
Move cursor to bottom of a screen
```javascript
process.stdout.write(clc.move.bottom);
```
##### clc.move.lineBegin
Move cursor to begin of a line
```javascript
process.stdout.write(clc.move.lineBegin);
```
##### clc.move.lineEnd
Move cursor to end of a line
```javascript
process.stdout.write(clc.move.lineEnd);
```
#### Terminal characteristics
##### clc.windowSize.width
Returns terminal width
##### clc.windowSize.height
Returns terminal height
### Additional functionalities
#### clc.slice(str[, begin[, end]])
Slice provided string with preservation of eventual ANSI formatting
```javascript
var clc = require("cli-color");
var str = clc.bold("foo") + "bar" + clc.red("elo");
var sliced = clc.slice(str, 1, 7); // Same as: clc.bold('oo') + 'bar' + clc.red('e')
```
#### clc.strip(formatedText)
Strips ANSI formatted string to plain text
```javascript
var ansiStrip = require("cli-color/strip");
var plain = ansiStrip(formatted);
```
#### clc.getStrippedLength(str)
Get actual length of ANSI-formatted string
```javascript
var clc = require("cli-color");
var str = clc.bold("foo") + "bar" + clc.red("elo");
clc.getStrippedLength(str); // 9
```
#### clc.art(text, styleConf)
Create a text-graphical art. Within `styleConf`, string replacements needs to be defined, which are then used to convert `text` to styled graphical text.
```javascript
var text = ".........\n" + ". Hello .\n" + ".........\n";
var style = { ".": clc.yellowBright("X") };
process.stdout.write(clc.art(text, style));
```
#### clc.columns(data[, options])
Outputs aligned table of columns.
`data` is expected to be an array (or other iterable structure) of rows, where each row is also an array (or other iterable structure) of content to display.
Supported `options`:
- `sep`: Custom colums separator (defaults to `|`)
- `columns`: Per column customizations, as e.g. `[{ align: 'right' }, null, { align: 'left' }]`:
- `align`: Possible options: `'left'`, `'right` (efaults to `'left'`)
```javascript
var clc = require("cli-color");
process.stdout.write(
clc.columns([
[clc.bold("First Name"), clc.bold("Last Name"), clc.bold("Age")], ["John", "Doe", 34],
["Martha", "Smith", 20], ["Jan", "Kowalski", 30]
])
);
/* Outputs:
First Name | Last Name | Age
John | Doe | 34
Martha | Smith | 20
Jan | Kowalski | 30
*/
```
##### throbber(write, interval[, format])
Writes throbber string to _write_ function at given _interval_. Optionally throbber output can be formatted with given _format_ function
```javascript
var setupThrobber = require("cli-color/throbber");
var throbber = setupThrobber(function (str) { process.stdout.write(str); }, 200);
throbber.start();
// at any time you can stop/start throbber
throbber.stop();
```
## Tests
$ npm test
## Security contact information
To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security). Tidelift will coordinate the fix and disclosure.
## Contributors
- [@rentalhost](https://github.com/rentalhost) (David Rodrigues)
- Help with support for nested styles. Introduction of `clc.art` module, and significant improvements to tests coverage
- [@StreetStrider](https://github.com/StreetStrider)
- Implementation of sophistcated `clc.slice` functionality, and introduction of `clc.getStrippedLength` utility
[nix-build-image]: https://semaphoreci.com/api/v1/medikoo-org/cli-color/branches/master/shields_badge.svg
[nix-build-url]: https://semaphoreci.com/medikoo-org/cli-color
[win-build-image]: https://ci.appveyor.com/api/projects/status/mnd4catkeu181ll5?svg=true
[win-build-url]: https://ci.appveyor.com/project/medikoo/cli-color
[transpilation-image]: https://img.shields.io/badge/transpilation-free-brightgreen.svg
[npm-image]: https://img.shields.io/npm/v/cli-color.svg
[npm-url]: https://www.npmjs.com/package/cli-color
---