1# ansi-styles [![Build Status](https://travis-ci.org/chalk/ansi-styles.svg?branch=master)](https://travis-ci.org/chalk/ansi-styles)
2
3> [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors_and_Styles) for styling strings in the terminal
4
5You probably want the higher-level [chalk](https://github.com/chalk/chalk) module for styling your strings.
6
7<img src="screenshot.svg" width="900">
8
9## Install
10
11```
12$ npm install ansi-styles
13```
14
15## Usage
16
17```js
18const style = require('ansi-styles');
19
20console.log(`${style.green.open}Hello world!${style.green.close}`);
21
22
23// Color conversion between 16/256/truecolor
24// NOTE: If conversion goes to 16 colors or 256 colors, the original color
25//       may be degraded to fit that color palette. This means terminals
26//       that do not support 16 million colors will best-match the
27//       original color.
28console.log(style.bgColor.ansi.hsl(120, 80, 72) + 'Hello world!' + style.bgColor.close);
29console.log(style.color.ansi256.rgb(199, 20, 250) + 'Hello world!' + style.color.close);
30console.log(style.color.ansi16m.hex('#abcdef') + 'Hello world!' + style.color.close);
31```
32
33## API
34
35Each style has an `open` and `close` property.
36
37## Styles
38
39### Modifiers
40
41- `reset`
42- `bold`
43- `dim`
44- `italic` *(Not widely supported)*
45- `underline`
46- `inverse`
47- `hidden`
48- `strikethrough` *(Not widely supported)*
49
50### Colors
51
52- `black`
53- `red`
54- `green`
55- `yellow`
56- `blue`
57- `magenta`
58- `cyan`
59- `white`
60- `blackBright` (alias: `gray`, `grey`)
61- `redBright`
62- `greenBright`
63- `yellowBright`
64- `blueBright`
65- `magentaBright`
66- `cyanBright`
67- `whiteBright`
68
69### Background colors
70
71- `bgBlack`
72- `bgRed`
73- `bgGreen`
74- `bgYellow`
75- `bgBlue`
76- `bgMagenta`
77- `bgCyan`
78- `bgWhite`
79- `bgBlackBright` (alias: `bgGray`, `bgGrey`)
80- `bgRedBright`
81- `bgGreenBright`
82- `bgYellowBright`
83- `bgBlueBright`
84- `bgMagentaBright`
85- `bgCyanBright`
86- `bgWhiteBright`
87
88## Advanced usage
89
90By default, you get a map of styles, but the styles are also available as groups. They are non-enumerable so they don't show up unless you access them explicitly. This makes it easier to expose only a subset in a higher-level module.
91
92- `style.modifier`
93- `style.color`
94- `style.bgColor`
95
96###### Example
97
98```js
99console.log(style.color.green.open);
100```
101
102Raw escape codes (i.e. without the CSI escape prefix `\u001B[` and render mode postfix `m`) are available under `style.codes`, which returns a `Map` with the open codes as keys and close codes as values.
103
104###### Example
105
106```js
107console.log(style.codes.get(36));
108//=> 39
109```
110
111## [256 / 16 million (TrueColor) support](https://gist.github.com/XVilka/8346728)
112
113`ansi-styles` uses the [`color-convert`](https://github.com/Qix-/color-convert) package to allow for converting between various colors and ANSI escapes, with support for 256 and 16 million colors.
114
115The following color spaces from `color-convert` are supported:
116
117- `rgb`
118- `hex`
119- `keyword`
120- `hsl`
121- `hsv`
122- `hwb`
123- `ansi`
124- `ansi256`
125
126To use these, call the associated conversion function with the intended output, for example:
127
128```js
129style.color.ansi.rgb(100, 200, 15); // RGB to 16 color ansi foreground code
130style.bgColor.ansi.rgb(100, 200, 15); // RGB to 16 color ansi background code
131
132style.color.ansi256.hsl(120, 100, 60); // HSL to 256 color ansi foreground code
133style.bgColor.ansi256.hsl(120, 100, 60); // HSL to 256 color ansi foreground code
134
135style.color.ansi16m.hex('#C0FFEE'); // Hex (RGB) to 16 million color foreground code
136style.bgColor.ansi16m.hex('#C0FFEE'); // Hex (RGB) to 16 million color background code
137```
138
139## Related
140
141- [ansi-escapes](https://github.com/sindresorhus/ansi-escapes) - ANSI escape codes for manipulating the terminal
142
143## Maintainers
144
145- [Sindre Sorhus](https://github.com/sindresorhus)
146- [Josh Junon](https://github.com/qix-)
147
148---
149
150<div align="center">
151	<b>
152		<a href="https://tidelift.com/subscription/pkg/npm-ansi-styles?utm_source=npm-ansi-styles&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
153	</b>
154	<br>
155	<sub>
156		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
157	</sub>
158</div>
159