0
# Kleur
1

2
Kleur is the fastest Node.js library for formatting terminal text with ANSI colors. It provides a zero-dependency, highly performant solution for adding colors, backgrounds, and text modifiers to console output, with conditional color support and both chainable and tree-shakeable APIs.
3

4
## Package Information
5

6
- **Package Name**: kleur
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install kleur`
10

11
## Core Imports
12

13
Main API (chainable methods):
14

15
```javascript
16
import kleur from "kleur";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const kleur = require("kleur");
23
```
24

25
Tree-shakeable colors API:
26

27
```javascript
28
import { red, bold, bgBlue } from "kleur/colors";
29
```
30

31
For CommonJS:
32

33
```javascript
34
const { red, bold, bgBlue } = require("kleur/colors");
35
```
36

37
## Basic Usage
38

39
```javascript
40
import kleur from "kleur";
41

42
// Simple color application
43
console.log(kleur.red("Error: Something went wrong"));
44
console.log(kleur.green("Success: Operation completed"));
45

46
// Chained styling
47
console.log(kleur.bold().red().underline("Important message"));
48

49
// Nested colors
50
console.log(kleur.yellow(`Warning: ${kleur.red().bold("critical")} issue detected`));
51

52
// Complex nested example
53
console.log(kleur.bold(`${kleur.white().bgRed('[ERROR]')} ${kleur.red().italic('Something happened')}`));
54

55
// Tree-shakeable approach
56
import { red, bold, underline } from "kleur/colors";
57
console.log(red(bold(underline("Styled text"))));
58
```
59

60
## Architecture
61

62
Kleur provides two distinct APIs optimized for different use cases:
63

64
- **Main API**: Chainable methods on a single `kleur` object for complex styling combinations
65
- **Colors API**: Individual functions exported from `kleur/colors` for tree-shaking and functional composition
66
- **Color Detection**: Automatic TTY and environment variable detection with manual override capability
67
- **ANSI Implementation**: Optimized ANSI escape sequence generation with proper nesting support
68
- **Zero Dependencies**: Self-contained implementation for minimal footprint
69

70
## Capabilities
71

72
### Chainable Color API
73

74
Main kleur API providing chainable methods for complex text styling. Perfect for applications requiring dynamic color combinations and complex formatting.
75

76
```javascript { .api }
77
declare const kleur: Kleur & { enabled: boolean };
78

79
interface Kleur {
80
  // Colors
81
  black: Color;
82
  red: Color;
83
  green: Color;
84
  yellow: Color;
85
  blue: Color;
86
  magenta: Color;
87
  cyan: Color;
88
  white: Color;
89
  gray: Color;
90
  grey: Color;
91

92
  // Backgrounds  
93
  bgBlack: Color;
94
  bgRed: Color;
95
  bgGreen: Color;
96
  bgYellow: Color;
97
  bgBlue: Color;
98
  bgMagenta: Color;
99
  bgCyan: Color;
100
  bgWhite: Color;
101

102
  // Modifiers
103
  reset: Color;
104
  bold: Color;
105
  dim: Color;
106
  italic: Color;
107
  underline: Color;
108
  inverse: Color;
109
  hidden: Color;
110
  strikethrough: Color;
111
}
112

113
interface Color {
114
  (input: string | number): string;
115
  (): Kleur;
116
}
117
```
118

119
[Chainable API](./chainable-api.md)
120

121
### Tree-Shakeable Colors API
122

123
Individual color functions for minimal bundle size and functional composition. Ideal for applications where bundle size matters or when using only a few colors.
124

125
```javascript { .api }
126
declare function print(input: string | boolean | number): string;
127
declare function print(input: undefined | void): undefined;
128
declare function print(input: null): null;
129
type Colorize = typeof print;
130

131
// Configuration
132
declare const $: { enabled: boolean };
133

134
// All color functions follow the Colorize type
135
declare const black: Colorize;
136
declare const red: Colorize;
137
declare const green: Colorize;
138
declare const yellow: Colorize;
139
declare const blue: Colorize;
140
declare const magenta: Colorize;
141
declare const cyan: Colorize;
142
declare const white: Colorize;
143
declare const gray: Colorize;
144
declare const grey: Colorize;
145

146
// Backgrounds
147
declare const bgBlack: Colorize;
148
declare const bgRed: Colorize;
149
declare const bgGreen: Colorize;
150
declare const bgYellow: Colorize;
151
declare const bgBlue: Colorize;
152
declare const bgMagenta: Colorize;
153
declare const bgCyan: Colorize;
154
declare const bgWhite: Colorize;
155

156
// Modifiers
157
declare const reset: Colorize;
158
declare const bold: Colorize;
159
declare const dim: Colorize;
160
declare const italic: Colorize;
161
declare const underline: Colorize;
162
declare const inverse: Colorize;
163
declare const hidden: Colorize;
164
declare const strikethrough: Colorize;
165
```
166

167
[Tree-Shakeable API](./colors-api.md)
168

169
### Color Detection and Configuration
170

171
Automatic color support detection with manual override capabilities. Handles TTY contexts, environment variables, and cross-platform compatibility.
172

173
```javascript { .api }
174
// Main API
175
kleur.enabled = false; // Manually disable colors
176

177
// Colors API  
178
import { $ } from "kleur/colors";
179
$.enabled = false; // Manually disable colors
180
```
181

182
[Color Detection](./color-detection.md)