0
# Tree-Shakeable Colors API
1
2
The `kleur/colors` API provides individual color functions that are fully tree-shakeable, allowing you to import only the colors you need for minimal bundle size. Functions cannot be chained but can be nested for complex styling.
3
4
## Core Types
5
6
```javascript { .api }
7
type Colorize = {
8
(input: string | boolean | number): string;
9
(input: undefined | void): undefined;
10
(input: null): null;
11
};
12
13
// Configuration object
14
declare const $: { enabled: boolean };
15
```
16
17
## Text Colors
18
19
Individual functions for applying foreground colors.
20
21
```javascript { .api }
22
declare const black: Colorize;
23
declare const red: Colorize;
24
declare const green: Colorize;
25
declare const yellow: Colorize;
26
declare const blue: Colorize;
27
declare const magenta: Colorize;
28
declare const cyan: Colorize;
29
declare const white: Colorize;
30
declare const gray: Colorize;
31
declare const grey: Colorize;
32
```
33
34
### Usage Examples
35
36
```javascript
37
import { red, green, yellow } from "kleur/colors";
38
39
// Direct application
40
console.log(red("Error message"));
41
console.log(green("Success message"));
42
console.log(yellow("Warning message"));
43
44
// Handle different input types
45
console.log(red(404)); // "404" (number converted to string)
46
console.log(red(true)); // "true" (boolean converted to string)
47
console.log(red(null)); // null (preserved)
48
console.log(red(undefined)); // undefined (preserved)
49
```
50
51
## Background Colors
52
53
Individual functions for applying background colors.
54
55
```javascript { .api }
56
declare const bgBlack: Colorize;
57
declare const bgRed: Colorize;
58
declare const bgGreen: Colorize;
59
declare const bgYellow: Colorize;
60
declare const bgBlue: Colorize;
61
declare const bgMagenta: Colorize;
62
declare const bgCyan: Colorize;
63
declare const bgWhite: Colorize;
64
```
65
66
### Usage Examples
67
68
```javascript
69
import { bgRed, bgGreen, white } from "kleur/colors";
70
71
// Background colors
72
console.log(bgRed("Alert"));
73
console.log(bgGreen("Success"));
74
75
// Combine with text colors using nesting
76
console.log(bgRed(white("High contrast text")));
77
```
78
79
## Text Modifiers
80
81
Individual functions for applying text formatting styles.
82
83
```javascript { .api }
84
declare const reset: Colorize; // Reset all styling
85
declare const bold: Colorize; // Bold text
86
declare const dim: Colorize; // Dim/faint text
87
declare const italic: Colorize; // Italic text (not widely supported)
88
declare const underline: Colorize; // Underlined text
89
declare const inverse: Colorize; // Inverse/reverse colors
90
declare const hidden: Colorize; // Hidden text
91
declare const strikethrough: Colorize; // Strikethrough text (not widely supported)
92
```
93
94
### Usage Examples
95
96
```javascript
97
import { bold, underline, dim } from "kleur/colors";
98
99
// Text modifiers
100
console.log(bold("Bold text"));
101
console.log(underline("Underlined text"));
102
console.log(dim("Dimmed text"));
103
```
104
105
## Function Composition
106
107
Combine multiple colors and modifiers using nested function calls.
108
109
### Usage Examples
110
111
```javascript
112
import { red, bold, underline, bgWhite } from "kleur/colors";
113
114
// Simple nesting
115
console.log(bold(red("Bold red text")));
116
console.log(underline(red("Underlined red text")));
117
118
// Complex nesting
119
console.log(bgWhite(underline(red("Red underlined text with white background"))));
120
121
// Multiple combinations
122
console.log(bold(underline(red("Bold, underlined, red text"))));
123
```
124
125
## Mixed Text Styling
126
127
Create strings with multiple colors by concatenating function results.
128
129
### Usage Examples
130
131
```javascript
132
import { red, green, yellow, blue, bold } from "kleur/colors";
133
134
// Concatenation
135
console.log(red("Error: ") + "Something went " + bold("wrong"));
136
137
// Template literals
138
const status = "active";
139
const count = 5;
140
console.log(`Status: ${green(status)}, Users: ${blue(count)}`);
141
142
// Complex messages
143
console.log(
144
yellow("Warning: ") +
145
"Found " +
146
red(bold("3")) +
147
" critical issues and " +
148
yellow("12") +
149
" warnings"
150
);
151
```
152
153
## Tree-Shaking Benefits
154
155
Import only the colors you need to minimize bundle size.
156
157
### Usage Examples
158
159
```javascript
160
// Import only what you need
161
import { red, bold } from "kleur/colors";
162
163
// Instead of importing everything
164
// import kleur from "kleur"; // This imports all colors
165
166
// Your bundler will only include red() and bold() functions
167
console.log(red("Error"));
168
console.log(bold("Important"));
169
```
170
171
## Configuration
172
173
Control color output for the colors API.
174
175
```javascript { .api }
176
// Configuration object
177
declare const $: { enabled: boolean };
178
```
179
180
### Usage Examples
181
182
```javascript
183
import { $, red, green } from "kleur/colors";
184
185
// Check current color support
186
console.log("Colors enabled:", $.enabled);
187
188
// Manually disable colors
189
$.enabled = false;
190
console.log(red("This won't be colored"));
191
192
// Re-enable colors
193
$.enabled = true;
194
console.log(red("This will be colored"));
195
196
// Conditional coloring
197
$.enabled = require("color-support").level > 0;
198
```
199
200
## Import Patterns
201
202
Different ways to import the colors API.
203
204
### Usage Examples
205
206
```javascript
207
// Named imports (recommended)
208
import { red, bold, bgBlue } from "kleur/colors";
209
210
// Namespace import
211
import * as colors from "kleur/colors";
212
console.log(colors.red("Red text"));
213
console.log(colors.$.enabled);
214
215
// CommonJS named destructuring
216
const { red, bold, bgBlue } = require("kleur/colors");
217
218
// CommonJS namespace
219
const colors = require("kleur/colors");
220
console.log(colors.red("Red text"));
221
```