0
# supports-color
1

2
supports-color is a lightweight JavaScript library that detects whether a terminal supports color output. It provides intelligent color support detection across different environments including Node.js and browsers, analyzing terminal streams to determine color capabilities ranging from basic 16-color support to full truecolor (16 million colors).
3

4
## Package Information
5

6
- **Package Name**: supports-color
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES modules)
9
- **Installation**: `npm install supports-color`
10

11
## Core Imports
12

13
```javascript
14
import supportsColor from "supports-color";
15
```
16

17
For the createSupportsColor function:
18

19
```javascript
20
import supportsColor, { createSupportsColor } from "supports-color";
21
```
22

23
For CommonJS:
24

25
```javascript
26
const supportsColor = require("supports-color");
27
const { createSupportsColor } = require("supports-color");
28
```
29

30
## Basic Usage
31

32
```javascript
33
import supportsColor from "supports-color";
34

35
// Check if terminal supports color
36
if (supportsColor.stdout) {
37
  console.log("Terminal stdout supports color");
38
  console.log(`Color level: ${supportsColor.stdout.level}`);
39
}
40

41
// Check specific color capabilities
42
if (supportsColor.stdout.has256) {
43
  console.log("Terminal supports 256 colors");
44
}
45

46
if (supportsColor.stderr.has16m) {
47
  console.log("Terminal stderr supports 16 million colors (truecolor)");
48
}
49

50
// Custom stream analysis
51
import { createSupportsColor } from "supports-color";
52

53
const customSupport = createSupportsColor(process.stdout);
54
if (customSupport) {
55
  console.log(`Custom stream color level: ${customSupport.level}`);
56
}
57
```
58

59
## Capabilities
60

61
### Pre-analyzed Color Support
62

63
The default export provides pre-analyzed color support for standard streams.
64

65
```javascript { .api }
66
interface SupportsColor {
67
  stdout: ColorInfo;
68
  stderr: ColorInfo;
69
}
70

71
const supportsColor: SupportsColor;
72
```
73

74
**Properties:**
75
- `stdout`: ColorInfo - Color support information for stdout stream
76
- `stderr`: ColorInfo - Color support information for stderr stream
77

78
### Custom Stream Analysis
79

80
Creates color support analysis for arbitrary streams with optional configuration.
81

82
```javascript { .api }
83
/**
84
 * Analyze color support for a custom stream
85
 * @param stream - Optional WriteStream to analyze (defaults to stdout-like behavior)
86
 * @param options - Optional configuration options
87
 * @returns Color support information or false if no color support
88
 */
89
function createSupportsColor(stream?: import('node:tty').WriteStream, options?: Options): ColorInfo;
90
```
91

92
**Parameters:**
93
- `stream` (optional): import('node:tty').WriteStream - The stream to analyze for color support
94
- `options` (optional): Options - Configuration options for the analysis
95

96
**Returns:** ColorInfo - Color support information or false
97

98
**Usage Examples:**
99

100
```javascript
101
import { createSupportsColor } from "supports-color";
102

103
// Analyze stdout with default settings
104
const stdoutSupport = createSupportsColor(process.stdout);
105

106
// Analyze stderr without flag sniffing
107
const stderrSupport = createSupportsColor(process.stderr, { sniffFlags: false });
108

109
// Analyze without providing a stream (uses default behavior)
110
const defaultSupport = createSupportsColor();
111
```
112

113
## Types
114

115
### ColorInfo Type
116

117
```javascript { .api }
118
/**
119
 * Color support information - either a ColorSupport object or false
120
 */
121
type ColorInfo = ColorSupport | false;
122
```
123

124
### ColorSupport Interface
125

126
```javascript { .api }
127
/**
128
 * Object describing terminal color capabilities
129
 */
130
interface ColorSupport {
131
  /** The color support level (0-3) */
132
  level: ColorSupportLevel;
133
  /** Whether basic 16 colors are supported */
134
  hasBasic: boolean;
135
  /** Whether ANSI 256 colors are supported */
136
  has256: boolean;
137
  /** Whether Truecolor 16 million colors are supported */
138
  has16m: boolean;
139
}
140
```
141

142
### ColorSupportLevel Type
143

144
```javascript { .api }
145
/**
146
 * Numeric representation of color support levels
147
 * - 0: All colors disabled
148
 * - 1: Basic 16 colors support
149
 * - 2: ANSI 256 colors support  
150
 * - 3: Truecolor 16 million colors support
151
 */
152
type ColorSupportLevel = 0 | 1 | 2 | 3;
153
```
154

155
### Options Interface
156

157
```javascript { .api }
158
/**
159
 * Configuration options for createSupportsColor function
160
 */
161
interface Options {
162
  /** Whether process.argv should be sniffed for --color and --no-color flags (default: true) */
163
  readonly sniffFlags?: boolean;
164
}
165
```
166

167
## Environment Variables
168

169
The library responds to various environment variables for controlling color behavior:
170

171
- **FORCE_COLOR**: Override color detection
172
  - `'0'` or `'false'`: Force disable colors
173
  - `'1'` or `'true'`: Force basic color support
174
  - `'2'`: Force 256 color support
175
  - `'3'`: Force truecolor support
176
- **TERM**: Terminal type detection (e.g., `'xterm-256color'`, `'dumb'`)
177
- **COLORTERM**: Color terminal indicator (e.g., `'truecolor'`)
178
- **CI**: Continuous integration detection
179
- **TRAVIS**, **CIRCLECI**, **APPVEYOR**, **GITLAB_CI**, **BUILDKITE**, **DRONE**: CI-specific variables
180
- **GITHUB_ACTIONS**, **GITEA_ACTIONS**: GitHub/Gitea Actions detection
181
- **TEAMCITY_VERSION**: TeamCity version detection
182
- **TERM_PROGRAM**, **TERM_PROGRAM_VERSION**: Terminal program detection (e.g., iTerm.app)
183
- **TF_BUILD**, **AGENT_NAME**: Azure DevOps detection
184

185
## Command-Line Flags
186

187
The library automatically detects and responds to command-line flags (when `sniffFlags` is true):
188

189
- **Enable color**: `--color`, `--colors`, `--color=true`, `--color=always`
190
- **Disable color**: `--no-color`, `--no-colors`, `--color=false`, `--color=never`
191
- **Force 256 colors**: `--color=256`
192
- **Force truecolor**: `--color=16m`, `--color=full`, `--color=truecolor`
193

194
## Platform Differences
195

196
### Node.js Environment
197
- Full detection logic including TTY analysis, environment variables, and platform-specific behavior
198
- Windows-specific color support detection based on OS build numbers
199
- CI system detection and handling
200

201
### Browser Environment  
202
- Chrome/Chromium-specific detection using navigator.userAgent and navigator.userAgentData
203
- Simplified color level detection (level 0, 1, or 3)
204
- No environment variable or command-line flag support
205

206
## Error Handling
207

208
The library is designed to gracefully handle various environments and never throws errors. It returns `false` when color support cannot be determined or is explicitly disabled.