0
# Chainable API
1

2
The main kleur API provides chainable methods for applying colors, backgrounds, and text modifiers. Each method can be called directly with text or chained together for complex styling combinations.
3

4
## Core Interface
5

6
```javascript { .api }
7
declare const kleur: Kleur & { enabled: boolean };
8

9
interface Kleur {
10
  // Colors
11
  black: Color;
12
  red: Color;
13
  green: Color;
14
  yellow: Color;
15
  blue: Color;
16
  magenta: Color;
17
  cyan: Color;
18
  white: Color;
19
  gray: Color;
20
  grey: Color;
21

22
  // Backgrounds
23
  bgBlack: Color;
24
  bgRed: Color;
25
  bgGreen: Color;
26
  bgYellow: Color;
27
  bgBlue: Color;
28
  bgMagenta: Color;
29
  bgCyan: Color;
30
  bgWhite: Color;
31

32
  // Modifiers
33
  reset: Color;
34
  bold: Color;
35
  dim: Color;
36
  italic: Color;
37
  underline: Color;
38
  inverse: Color;
39
  hidden: Color;
40
  strikethrough: Color;
41
}
42

43
interface Color {
44
  (input: string | number): string;
45
  (): Kleur;
46
}
47
```
48

49
## Text Colors
50

51
Apply foreground colors to text.
52

53
```javascript { .api }
54
kleur.black: Color;
55
kleur.red: Color;
56
kleur.green: Color;
57
kleur.yellow: Color;
58
kleur.blue: Color;
59
kleur.magenta: Color;
60
kleur.cyan: Color;
61
kleur.white: Color;
62
kleur.gray: Color;
63
kleur.grey: Color;
64
```
65

66
### Usage Examples
67

68
```javascript
69
import kleur from "kleur";
70

71
// Direct application
72
console.log(kleur.red("Error message"));
73
console.log(kleur.green("Success message"));
74
console.log(kleur.yellow("Warning message"));
75

76
// Numbers are automatically converted to strings
77
console.log(kleur.blue(404));
78
console.log(kleur.magenta(3.14159));
79
```
80

81
## Background Colors
82

83
Apply background colors to text.
84

85
```javascript { .api }
86
kleur.bgBlack: Color;
87
kleur.bgRed: Color;
88
kleur.bgGreen: Color;
89
kleur.bgYellow: Color;
90
kleur.bgBlue: Color;
91
kleur.bgMagenta: Color;
92
kleur.bgCyan: Color;
93
kleur.bgWhite: Color;
94
```
95

96
### Usage Examples
97

98
```javascript
99
import kleur from "kleur";
100

101
// Background colors
102
console.log(kleur.bgRed("Alert"));
103
console.log(kleur.bgGreen("Success"));
104

105
// Combine with text colors
106
console.log(kleur.white().bgRed("High contrast text"));
107
```
108

109
## Text Modifiers
110

111
Apply various text formatting styles.
112

113
```javascript { .api }
114
kleur.reset: Color;      // Reset all styling
115
kleur.bold: Color;       // Bold text
116
kleur.dim: Color;        // Dim/faint text
117
kleur.italic: Color;     // Italic text (not widely supported)
118
kleur.underline: Color;  // Underlined text
119
kleur.inverse: Color;    // Inverse/reverse colors
120
kleur.hidden: Color;     // Hidden text
121
kleur.strikethrough: Color; // Strikethrough text (not widely supported)
122
```
123

124
### Usage Examples
125

126
```javascript
127
import kleur from "kleur";
128

129
// Text modifiers
130
console.log(kleur.bold("Bold text"));
131
console.log(kleur.underline("Underlined text"));
132
console.log(kleur.dim("Dimmed text"));
133

134
// Note: italic and strikethrough are not widely supported across terminals
135
console.log(kleur.italic("Italic text"));
136
console.log(kleur.strikethrough("Strikethrough text"));
137
```
138

139
## Method Chaining
140

141
Chain multiple styles together for complex formatting.
142

143
### Usage Examples
144

145
```javascript
146
import kleur from "kleur";
147

148
// Chain colors and modifiers
149
console.log(kleur.red().bold("Bold red text"));
150
console.log(kleur.white().bgBlue().underline("White text on blue background"));
151

152
// Complex chaining
153
console.log(kleur.yellow().bold().bgRed().italic("Multi-styled text"));
154

155
// Chain order doesn't matter for styling
156
console.log(kleur.bold().red("Same as"));
157
console.log(kleur.red().bold("this text"));
158
```
159

160
## Nested Styling
161

162
Apply colors within already colored text using nested method calls.
163

164
### Usage Examples
165

166
```javascript
167
import kleur from "kleur";
168

169
// Nested colors
170
console.log(kleur.red(`Error: ${kleur.yellow("warning")} occurred`));
171

172
// Complex nesting
173
console.log(kleur.bold(`
174
  Status: ${kleur.green("OK")} 
175
  Errors: ${kleur.red().bold("3")} 
176
  Warnings: ${kleur.yellow("12")}
177
`));
178

179
// Template literals work well with nesting
180
const status = "connected";
181
const count = 42;
182
console.log(kleur.cyan(`Server ${kleur.green().bold(status)} with ${kleur.white().bgBlue(count)} users`));
183
```
184

185
## Configuration
186

187
Control color output globally.
188

189
```javascript { .api }
190
kleur.enabled: boolean;
191
```
192

193
### Usage Examples
194

195
```javascript
196
import kleur from "kleur";
197

198
// Check current color support
199
console.log("Colors enabled:", kleur.enabled);
200

201
// Manually disable colors
202
kleur.enabled = false;
203
console.log(kleur.red("This won't be colored"));
204

205
// Re-enable colors
206
kleur.enabled = true;
207
console.log(kleur.red("This will be colored"));
208

209
// Conditional coloring based on environment
210
kleur.enabled = process.env.NODE_ENV !== "test";
211
```