0
# Picocolors
1

2
Picocolors is a high-performance, zero-dependency library for terminal output formatting with ANSI colors. It provides the smallest and fastest solution for adding colors and text formatting to command-line interfaces, being 14 times smaller and 2 times faster than chalk.
3

4
## Package Information
5

6
- **Package Name**: picocolors
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install picocolors`
10

11
## Core Imports
12

13
```javascript
14
import pc from "picocolors";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const pc = require("picocolors");
21
```
22

23
For TypeScript with named imports:
24

25
```typescript
26
import { Colors } from "picocolors";
27
```
28

29
## Basic Usage
30

31
```javascript
32
import pc from "picocolors";
33

34
// Basic colors
35
console.log(pc.red("Error message"));
36
console.log(pc.green("Success message"));
37
console.log(pc.blue("Info message"));
38

39
// Text formatting
40
console.log(pc.bold("Important text"));
41
console.log(pc.italic("Emphasized text"));
42
console.log(pc.underline("Underlined text"));
43

44
// Nested formatting
45
console.log(pc.red(`Error: ${pc.bold("Something went wrong")}`));
46

47
// Background colors
48
console.log(pc.bgYellow(pc.black("Warning message")));
49

50
// Checking color support
51
if (pc.isColorSupported) {
52
  console.log(pc.green("Colors are supported!"));
53
}
54
```
55

56
## Architecture
57

58
Picocolors uses a formatter-based architecture that:
59

60
- **Auto-detects color support** based on environment variables, CLI flags, and terminal capabilities
61
- **Handles nested formatting** by properly managing ANSI escape sequences
62
- **Optimizes performance** through minimal overhead and efficient string operations
63
- **Provides browser compatibility** with a separate browser bundle that disables colors
64
- **Supports manual configuration** via the `createColors` factory function
65

66
The library automatically detects color support by checking:
67

68
- `NO_COLOR` and `FORCE_COLOR` environment variables
69
- `--no-color` and `--color` command-line flags
70
- Platform detection (Windows support)
71
- TTY detection and TERM environment variable
72
- CI environment detection
73

74
## Capabilities
75

76
### Color Support Detection
77

78
Check if colors are supported in the current environment.
79

80
```javascript { .api }
81
// Property indicating color support
82
const isColorSupported: boolean;
83
```
84

85
### Color Factory
86

87
Create a custom colors object with manual color support configuration.
88

89
```javascript { .api }
90
/**
91
 * Create a Colors object with custom color support configuration
92
 * @param enabled - Whether to enable colors (defaults to auto-detection)
93
 * @returns Colors object with all formatting functions
94
 */
95
function createColors(enabled?: boolean): Colors;
96
```
97

98
**Usage Example:**
99

100
```javascript
101
import pc from "picocolors";
102

103
// Create colors with manual configuration
104
const colors = pc.createColors(true);  // Force enable
105
const noColors = pc.createColors(false); // Force disable
106

107
console.log(colors.red("This will be red"));
108
console.log(noColors.red("This will be plain text"));
109
```
110

111
### Text Formatting
112

113
Apply text styling and formatting effects.
114

115
```javascript { .api }
116
// Reset all formatting
117
const reset: (input: string | number | null | undefined) => string;
118

119
// Text styling
120
const bold: (input: string | number | null | undefined) => string;
121
const dim: (input: string | number | null | undefined) => string;
122
const italic: (input: string | number | null | undefined) => string;
123
const underline: (input: string | number | null | undefined) => string;
124
const inverse: (input: string | number | null | undefined) => string;
125
const hidden: (input: string | number | null | undefined) => string;
126
const strikethrough: (input: string | number | null | undefined) => string;
127
```
128

129
**Usage Examples:**
130

131
```javascript
132
console.log(pc.bold("Bold text"));
133
console.log(pc.italic("Italic text"));
134
console.log(pc.underline("Underlined text"));
135
console.log(pc.strikethrough("Strikethrough text"));
136
console.log(pc.dim("Dimmed text"));
137
console.log(pc.inverse("Inverted colors"));
138
console.log(pc.hidden("Hidden text"));
139
console.log(pc.reset("Reset formatting"));
140
```
141

142
### Standard Colors
143

144
Apply standard foreground colors to text.
145

146
```javascript { .api }
147
// Standard foreground colors
148
const black: (input: string | number | null | undefined) => string;
149
const red: (input: string | number | null | undefined) => string;
150
const green: (input: string | number | null | undefined) => string;
151
const yellow: (input: string | number | null | undefined) => string;
152
const blue: (input: string | number | null | undefined) => string;
153
const magenta: (input: string | number | null | undefined) => string;
154
const cyan: (input: string | number | null | undefined) => string;
155
const white: (input: string | number | null | undefined) => string;
156
const gray: (input: string | number | null | undefined) => string;
157
```
158

159
**Usage Examples:**
160

161
```javascript
162
console.log(pc.black("Black text"));
163
console.log(pc.red("Red text"));
164
console.log(pc.green("Green text"));
165
console.log(pc.yellow("Yellow text"));
166
console.log(pc.blue("Blue text"));
167
console.log(pc.magenta("Magenta text"));
168
console.log(pc.cyan("Cyan text"));
169
console.log(pc.white("White text"));
170
console.log(pc.gray("Gray text"));
171
```
172

173
### Background Colors
174

175
Apply background colors to text.
176

177
```javascript { .api }
178
// Standard background colors
179
const bgBlack: (input: string | number | null | undefined) => string;
180
const bgRed: (input: string | number | null | undefined) => string;
181
const bgGreen: (input: string | number | null | undefined) => string;
182
const bgYellow: (input: string | number | null | undefined) => string;
183
const bgBlue: (input: string | number | null | undefined) => string;
184
const bgMagenta: (input: string | number | null | undefined) => string;
185
const bgCyan: (input: string | number | null | undefined) => string;
186
const bgWhite: (input: string | number | null | undefined) => string;
187
```
188

189
**Usage Examples:**
190

191
```javascript
192
console.log(pc.bgBlack("Text with black background"));
193
console.log(pc.bgRed("Text with red background"));
194
console.log(pc.bgGreen("Text with green background"));
195
console.log(pc.bgYellow("Text with yellow background"));
196
console.log(pc.bgBlue("Text with blue background"));
197
console.log(pc.bgMagenta("Text with magenta background"));
198
console.log(pc.bgCyan("Text with cyan background"));
199
console.log(pc.bgWhite("Text with white background"));
200
```
201

202
### Bright Colors
203

204
Apply bright/high-intensity foreground colors to text.
205

206
```javascript { .api }
207
// Bright foreground colors
208
const blackBright: (input: string | number | null | undefined) => string;
209
const redBright: (input: string | number | null | undefined) => string;
210
const greenBright: (input: string | number | null | undefined) => string;
211
const yellowBright: (input: string | number | null | undefined) => string;
212
const blueBright: (input: string | number | null | undefined) => string;
213
const magentaBright: (input: string | number | null | undefined) => string;
214
const cyanBright: (input: string | number | null | undefined) => string;
215
const whiteBright: (input: string | number | null | undefined) => string;
216
```
217

218
**Usage Examples:**
219

220
```javascript
221
console.log(pc.blackBright("Bright black text"));
222
console.log(pc.redBright("Bright red text"));
223
console.log(pc.greenBright("Bright green text"));
224
console.log(pc.yellowBright("Bright yellow text"));
225
console.log(pc.blueBright("Bright blue text"));
226
console.log(pc.magentaBright("Bright magenta text"));
227
console.log(pc.cyanBright("Bright cyan text"));
228
console.log(pc.whiteBright("Bright white text"));
229
```
230

231
### Bright Background Colors
232

233
Apply bright/high-intensity background colors to text.
234

235
```javascript { .api }
236
// Bright background colors
237
const bgBlackBright: (input: string | number | null | undefined) => string;
238
const bgRedBright: (input: string | number | null | undefined) => string;
239
const bgGreenBright: (input: string | number | null | undefined) => string;
240
const bgYellowBright: (input: string | number | null | undefined) => string;
241
const bgBlueBright: (input: string | number | null | undefined) => string;
242
const bgMagentaBright: (input: string | number | null | undefined) => string;
243
const bgCyanBright: (input: string | number | null | undefined) => string;
244
const bgWhiteBright: (input: string | number | null | undefined) => string;
245
```
246

247
**Usage Examples:**
248

249
```javascript
250
console.log(pc.bgBlackBright("Text with bright black background"));
251
console.log(pc.bgRedBright("Text with bright red background"));
252
console.log(pc.bgGreenBright("Text with bright green background"));
253
console.log(pc.bgYellowBright("Text with bright yellow background"));
254
console.log(pc.bgBlueBright("Text with bright blue background"));
255
console.log(pc.bgMagentaBright("Text with bright magenta background"));
256
console.log(pc.bgCyanBright("Text with bright cyan background"));
257
console.log(pc.bgWhiteBright("Text with bright white background"));
258
```
259

260
## Types
261

262
```typescript { .api }
263
// Function signature for all color and formatting functions
264
type Formatter = (input: string | number | null | undefined) => string;
265

266
// Main Colors interface containing all formatting functions
267
interface Colors {
268
  // Color support detection
269
  isColorSupported: boolean;
270

271
  // Text formatting
272
  reset: Formatter;
273
  bold: Formatter;
274
  dim: Formatter;
275
  italic: Formatter;
276
  underline: Formatter;
277
  inverse: Formatter;
278
  hidden: Formatter;
279
  strikethrough: Formatter;
280

281
  // Standard colors
282
  black: Formatter;
283
  red: Formatter;
284
  green: Formatter;
285
  yellow: Formatter;
286
  blue: Formatter;
287
  magenta: Formatter;
288
  cyan: Formatter;
289
  white: Formatter;
290
  gray: Formatter;
291

292
  // Background colors
293
  bgBlack: Formatter;
294
  bgRed: Formatter;
295
  bgGreen: Formatter;
296
  bgYellow: Formatter;
297
  bgBlue: Formatter;
298
  bgMagenta: Formatter;
299
  bgCyan: Formatter;
300
  bgWhite: Formatter;
301

302
  // Bright colors
303
  blackBright: Formatter;
304
  redBright: Formatter;
305
  greenBright: Formatter;
306
  yellowBright: Formatter;
307
  blueBright: Formatter;
308
  magentaBright: Formatter;
309
  cyanBright: Formatter;
310
  whiteBright: Formatter;
311

312
  // Bright background colors
313
  bgBlackBright: Formatter;
314
  bgRedBright: Formatter;
315
  bgGreenBright: Formatter;
316
  bgYellowBright: Formatter;
317
  bgBlueBright: Formatter;
318
  bgMagentaBright: Formatter;
319
  bgCyanBright: Formatter;
320
  bgWhiteBright: Formatter;
321
}
322
```
323

324
## Advanced Usage
325

326
### Nested Formatting
327

328
Picocolors properly handles nested color and formatting combinations:
329

330
```javascript
331
// Complex nested formatting
332
console.log(
333
  pc.bold(
334
    pc.yellow(
335
      pc.bgRed(
336
        pc.italic("Complex nested formatting")
337
      )
338
    )
339
  )
340
);
341

342
// Inline color changes within text
343
console.log(
344
  pc.green(`Success: ${pc.bold("Operation completed")} successfully`)
345
);
346
```
347

348
### Input Type Handling
349

350
All formatter functions accept and handle various input types:
351

352
```javascript
353
console.log(pc.red(null));      // "null"
354
console.log(pc.red(undefined)); // "undefined"
355
console.log(pc.red(123));       // "123"
356
console.log(pc.red(true));      // "true"
357
console.log(pc.red(NaN));       // "NaN"
358
```
359

360
### Environment Configuration
361

362
Control color behavior through environment variables and CLI flags:
363

364
```bash
365
# Disable colors
366
NO_COLOR=1 node script.js
367
node script.js --no-color
368

369
# Force enable colors
370
FORCE_COLOR=1 node script.js
371
node script.js --color
372
```
373

374
### Browser Usage
375

376
For browser environments, use the browser-specific bundle:
377

378
```javascript
379
// Browser bundle automatically disables colors
380
import pc from "picocolors/picocolors.browser.js";
381

382
// All functions return plain strings in browser
383
console.log(pc.red("This will be plain text in browser"));
384
```