0
# Colors and Styling
1

2
Terminal Kit provides comprehensive color and text styling capabilities, supporting everything from basic ANSI colors to 24-bit RGB colors, with full background color support and text formatting options.
3

4
## Basic ANSI Colors
5

6
### Foreground Colors
7

8
```javascript { .api }
9
terminal.black(text?: string): Terminal;
10
terminal.red(text?: string): Terminal;
11
terminal.green(text?: string): Terminal;
12
terminal.yellow(text?: string): Terminal;
13
terminal.blue(text?: string): Terminal;
14
terminal.magenta(text?: string): Terminal;
15
terminal.cyan(text?: string): Terminal;
16
terminal.white(text?: string): Terminal;
17
terminal.gray(text?: string): Terminal;
18
terminal.grey(text?: string): Terminal;
19
```
20

21
Basic 8-color ANSI support. Methods are chainable and can include text.
22

23
```javascript
24
const term = require('terminal-kit').terminal;
25

26
term.red('Error: ').white('Something went wrong!\n');
27
term.green().bold('Success!\n');
28
```
29

30
### Bright Colors
31

32
```javascript { .api }
33
terminal.brightBlack(text?: string): Terminal;
34
terminal.brightRed(text?: string): Terminal;
35
terminal.brightGreen(text?: string): Terminal;
36
terminal.brightYellow(text?: string): Terminal;
37
terminal.brightBlue(text?: string): Terminal;
38
terminal.brightMagenta(text?: string): Terminal;
39
terminal.brightCyan(text?: string): Terminal;
40
terminal.brightWhite(text?: string): Terminal;
41
```
42

43
Bright variants of the basic colors.
44

45
```javascript
46
term.brightRed('Urgent: ').brightWhite('Important message\n');
47
```
48

49
### Background Colors
50

51
```javascript { .api }
52
terminal.bgBlack(text?: string): Terminal;
53
terminal.bgRed(text?: string): Terminal;
54
terminal.bgGreen(text?: string): Terminal;
55
terminal.bgYellow(text?: string): Terminal;
56
terminal.bgBlue(text?: string): Terminal;
57
terminal.bgMagenta(text?: string): Terminal;
58
terminal.bgCyan(text?: string): Terminal;
59
terminal.bgWhite(text?: string): Terminal;
60
terminal.bgGray(text?: string): Terminal;
61
terminal.bgGrey(text?: string): Terminal;
62
```
63

64
Background color variants.
65

66
```javascript
67
term.bgRed().white(' ERROR ').styleReset(' Something failed\n');
68
```
69

70
### Bright Background Colors
71

72
```javascript { .api }
73
terminal.bgBrightBlack(text?: string): Terminal;
74
terminal.bgBrightRed(text?: string): Terminal;
75
terminal.bgBrightGreen(text?: string): Terminal;
76
terminal.bgBrightYellow(text?: string): Terminal;
77
terminal.bgBrightBlue(text?: string): Terminal;
78
terminal.bgBrightMagenta(text?: string): Terminal;
79
terminal.bgBrightCyan(text?: string): Terminal;
80
terminal.bgBrightWhite(text?: string): Terminal;
81
```
82

83
Bright background colors.
84

85
## Advanced Color Support
86

87
### 256-Color Palette
88

89
```javascript { .api }
90
terminal.color256(colorIndex: number, text?: string): Terminal;
91
terminal.bgColor256(colorIndex: number, text?: string): Terminal;
92
```
93

94
Use the full 256-color terminal palette (0-255).
95

96
```javascript
97
// Use color index 196 (bright red)
98
term.color256(196, 'Bright red text\n');
99

100
// Background color
101
term.bgColor256(21).white(' Blue background ').styleReset('\n');
102
```
103

104
### RGB Colors (24-bit True Color)
105

106
```javascript { .api }
107
terminal.colorRgb(r: number, g: number, b: number, text?: string): Terminal;
108
terminal.bgColorRgb(r: number, g: number, b: number, text?: string): Terminal;
109
```
110

111
Use RGB values (0-255 each) for true color support.
112

113
```javascript
114
// Custom RGB colors
115
term.colorRgb(255, 100, 50, 'Orange text\n');
116
term.bgColorRgb(30, 144, 255).white(' Dodger blue background ').styleReset('\n');
117
```
118

119
### Grayscale Colors
120

121
```javascript { .api }
122
terminal.colorGrayscale(level: number, text?: string): Terminal;
123
terminal.bgColorGrayscale(level: number, text?: string): Terminal;
124
```
125

126
Use grayscale values (0-23 for terminal-kit's grayscale palette).
127

128
```javascript
129
term.colorGrayscale(12, 'Medium gray text\n');
130
term.bgColorGrayscale(20).black(' Light gray background ').styleReset('\n');
131
```
132

133
### Generic Color Methods
134

135
```javascript { .api }
136
terminal.color(color: string | number, text?: string): Terminal;
137
terminal.bgColor(color: string | number, text?: string): Terminal;
138
```
139

140
Set colors using color names or numbers.
141

142
```javascript
143
term.color('red', 'Red text using name\n');
144
term.color(9, 'Bright red using index\n');
145
term.bgColor('blue').white(' Blue background ').styleReset('\n');
146
```
147

148
### Color Reset
149

150
```javascript { .api }
151
terminal.defaultColor(text?: string): Terminal;
152
```
153

154
Reset to default terminal colors.
155

156
```javascript
157
term.red('Red text ').defaultColor('back to default\n');
158
```
159

160
## Text Styling
161

162
### Basic Styling
163

164
```javascript { .api }
165
terminal.styleReset(text?: string): Terminal;
166
terminal.bold(state?: boolean, text?: string): Terminal;
167
terminal.dim(state?: boolean, text?: string): Terminal;
168
terminal.italic(state?: boolean, text?: string): Terminal;
169
terminal.underline(state?: boolean, text?: string): Terminal;
170
terminal.blink(state?: boolean, text?: string): Terminal;
171
terminal.inverse(state?: boolean, text?: string): Terminal;
172
terminal.hidden(state?: boolean, text?: string): Terminal;
173
terminal.strike(state?: boolean, text?: string): Terminal;
174
```
175

176
Text formatting and styling options. The `state` parameter toggles the style on/off.
177

178
```javascript
179
term.bold('Bold text ');
180
term.italic(true, 'Italic text ');
181
term.underline().red('Underlined red text').styleReset('\n');
182

183
// Toggle styles
184
term.bold(true).red('Bold red ').bold(false).green('normal green\n');
185
```
186

187
### Style Combinations
188

189
```javascript
190
// Combine multiple styles
191
term.bold().italic().underline().red('Multiple styles\n').styleReset();
192

193
// Chain styles with colors
194
term.bgYellow().black().bold(' WARNING ').styleReset().yellow(' Check this out\n');
195
```
196

197
## Color Utility Functions
198

199
### Color Conversion
200

201
```javascript { .api }
202
// Color name utilities
203
colorNameToIndex(colorName: string): number;
204
indexToColorName(colorIndex: number): string;
205
colorNameToRgb(colorName: string): { r: number; g: number; b: number };
206
rgbToColorName(r: number, g: number, b: number): string;
207

208
// Color format conversion  
209
color256ToRgb(colorIndex: number): { r: number; g: number; b: number };
210
rgbToColor256(r: number, g: number, b: number): number;
211
hexToRgba(hex: string): { r: number; g: number; b: number; a: number };
212
rgbToHex(r: number, g: number, b: number): string;
213
```
214

215
Utility functions for color format conversion.
216

217
```javascript
218
const termkit = require('terminal-kit');
219

220
// Convert color name to index
221
const redIndex = termkit.colorNameToIndex('red'); // Returns 1
222

223
// Convert RGB to 256-color index
224
const colorIndex = termkit.rgbToColor256(255, 100, 50);
225
term.color256(colorIndex, 'Orange-ish text\n');
226

227
// Hex to RGBA conversion
228
const rgba = termkit.hexToRgba('#FF6432');
229
term.colorRgb(rgba.r, rgba.g, rgba.b, 'Hex color text\n');
230
```
231

232
## Color Palettes
233

234
### Get and Set Colors
235

236
```javascript { .api }
237
terminal.getColor(register: number, callback: (error: Error | null, r: number, g: number, b: number) => void): void;
238
terminal.setColor(register: number, r: number, g: number, b: number, names?: string[], callback?: (error: Error | null) => void): void;
239
```
240

241
Get or set individual color register values.
242

243
```javascript
244
// Get current color value
245
term.getColor(1, (error, r, g, b) => {
246
  if (!error) {
247
    console.log(`Red register: RGB(${r}, ${g}, ${b})`);
248
  }
249
});
250

251
// Set custom color
252
term.setColor(1, 255, 100, 50, ['custom-orange'], (error) => {
253
  if (!error) {
254
    term.red('Now using custom orange for red\n');
255
  }
256
});
257
```
258

259
### Palette Operations
260

261
```javascript { .api }
262
terminal.getPalette(register: number, callback: (error: Error | null, palette: ColorPalette) => void): void;
263
terminal.setPalette(palette: ColorPalette, callback?: (error: Error | null) => void): void;
264
```
265

266
Get or set entire color palettes.
267

268
```javascript { .api }
269
interface ColorPalette {
270
  [colorIndex: number]: {
271
    r: number;
272
    g: number;
273
    b: number;
274
    names?: string[];
275
  };
276
}
277
```
278

279
## Chroma.js Integration
280

281
Terminal Kit includes the Chroma.js library for advanced color manipulation.
282

283
```javascript { .api }
284
terminal.chroma: typeof import('chroma-js');
285
```
286

287
```javascript
288
const term = require('terminal-kit').terminal;
289
const chroma = term.chroma;
290

291
// Create color scale
292
const scale = chroma.scale(['red', 'yellow', 'green']).mode('lab');
293

294
// Use colors from scale
295
for (let i = 0; i <= 10; i++) {
296
  const color = scale(i / 10).rgb();
297
  term.colorRgb(color[0], color[1], color[2], '█');
298
}
299
term('\n');
300
```
301

302
## Usage Examples
303

304
### Rainbow Text
305

306
```javascript
307
const term = require('terminal-kit').terminal;
308

309
const text = 'Rainbow Text!';
310
const colors = ['red', 'yellow', 'green', 'cyan', 'blue', 'magenta'];
311

312
for (let i = 0; i < text.length; i++) {
313
  const color = colors[i % colors.length];
314
  term[color](text[i]);
315
}
316
term('\n');
317
```
318

319
### Progress Bar with Colors
320

321
```javascript
322
function drawProgressBar(percent) {
323
  const width = 40;
324
  const filled = Math.floor(width * percent / 100);
325
  const empty = width - filled;
326
  
327
  term.moveTo(1, 10);
328
  term.cyan('[');
329
  
330
  // Green for progress
331
  term.bgGreen(' '.repeat(filled));
332
  
333
  // Red for remaining
334
  term.bgRed(' '.repeat(empty));
335
  
336
  term.cyan('] ');
337
  
338
  // Color-coded percentage
339
  if (percent < 30) {
340
    term.red(`${percent}%`);
341
  } else if (percent < 70) {
342
    term.yellow(`${percent}%`);
343
  } else {
344
    term.green(`${percent}%`);
345
  }
346
}
347
```
348

349
### Styled Log Messages
350

351
```javascript
352
function logMessage(level, message) {
353
  const timestamp = new Date().toISOString();
354
  
355
  term.gray(`[${timestamp}] `);
356
  
357
  switch (level) {
358
    case 'error':
359
      term.bgRed().white(' ERROR ').styleReset().red(` ${message}\n`);
360
      break;
361
    case 'warn':
362
      term.bgYellow().black(' WARN ').styleReset().yellow(` ${message}\n`);
363
      break;
364
    case 'info':
365
      term.bgBlue().white(' INFO ').styleReset().blue(` ${message}\n`);
366
      break;
367
    case 'success':
368
      term.bgGreen().white(' SUCCESS ').styleReset().green(` ${message}\n`);
369
      break;
370
    default:
371
      term(` ${message}\n`);
372
  }
373
}
374

375
// Usage
376
logMessage('error', 'Something went wrong');
377
logMessage('success', 'Operation completed');
378
```