0
# Color Analysis
1

2
Methods for analyzing color properties including darkness, brightness, luminance, validity checks, and retrieving color metadata.
3

4
## Capabilities
5

6
### Darkness and Lightness
7

8
#### Check if Color is Dark
9

10
Determines if a color is considered dark based on its brightness value.
11

12
```javascript { .api }
13
/**
14
 * Returns true if the color is dark (brightness < 128)
15
 * @returns boolean indicating if color is dark
16
 */
17
isDark(): boolean;
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
import tinycolor from "tinycolor2";
24

25
const darkColor = tinycolor("#333333");
26
const lightColor = tinycolor("#cccccc");
27

28
console.log(darkColor.isDark());  // true
29
console.log(lightColor.isDark()); // false
30

31
// Useful for determining text color
32
const backgroundColor = tinycolor("#2c3e50");
33
const textColor = backgroundColor.isDark() ? "#ffffff" : "#000000";
34
```
35

36
#### Check if Color is Light
37

38
Determines if a color is considered light (opposite of dark).
39

40
```javascript { .api }
41
/**
42
 * Returns true if the color is light (brightness >= 128)
43
 * @returns boolean indicating if color is light
44
 */
45
isLight(): boolean;
46
```
47

48
**Usage Examples:**
49

50
```javascript
51
const darkColor = tinycolor("#333333");
52
const lightColor = tinycolor("#cccccc");
53

54
console.log(darkColor.isLight());  // false
55
console.log(lightColor.isLight()); // true
56

57
// Choose appropriate overlay
58
const bgColor = tinycolor("#f8f9fa");
59
const overlayOpacity = bgColor.isLight() ? 0.1 : 0.8;
60
```
61

62
### Brightness and Luminance
63

64
#### Get Brightness
65

66
Returns the perceived brightness using the W3C formula.
67

68
```javascript { .api }
69
/**
70
 * Returns the perceived brightness using W3C formula
71
 * Formula: (r * 299 + g * 587 + b * 114) / 1000
72
 * @returns number between 0-255 representing brightness
73
 */
74
getBrightness(): number;
75
```
76

77
**Usage Examples:**
78

79
```javascript
80
const red = tinycolor("red");
81
const blue = tinycolor("blue");
82
const white = tinycolor("white");
83

84
console.log(red.getBrightness());   // 76.245
85
console.log(blue.getBrightness());  // 28.814
86
console.log(white.getBrightness()); // 255
87

88
// Sort colors by brightness
89
const colors = ["red", "blue", "green", "yellow"].map(tinycolor);
90
colors.sort((a, b) => b.getBrightness() - a.getBrightness());
91
```
92

93
#### Get Luminance
94

95
Returns the relative luminance using the WCAG formula.
96

97
```javascript { .api }
98
/**
99
 * Returns the relative luminance using WCAG formula
100
 * Used for accessibility calculations
101
 * @returns number between 0-1 representing luminance
102
 */
103
getLuminance(): number;
104
```
105

106
**Usage Examples:**
107

108
```javascript
109
const white = tinycolor("white");
110
const black = tinycolor("black");
111
const red = tinycolor("red");
112

113
console.log(white.getLuminance()); // 1
114
console.log(black.getLuminance()); // 0
115
console.log(red.getLuminance());   // ~0.2126
116

117
// Calculate contrast ratio manually
118
const bg = tinycolor("#2c3e50");
119
const text = tinycolor("#ffffff");
120
const l1 = Math.max(bg.getLuminance(), text.getLuminance());
121
const l2 = Math.min(bg.getLuminance(), text.getLuminance());
122
const contrast = (l1 + 0.05) / (l2 + 0.05);
123
```
124

125
### Validation and Metadata
126

127
#### Check Color Validity
128

129
Determines if the color was successfully parsed from the input.
130

131
```javascript { .api }
132
/**
133
 * Returns true if the color was successfully parsed
134
 * @returns boolean indicating if color is valid
135
 */
136
isValid(): boolean;
137
```
138

139
**Usage Examples:**
140

141
```javascript
142
const validColor = tinycolor("red");
143
const invalidColor = tinycolor("not-a-color");
144
const emptyColor = tinycolor("");
145

146
console.log(validColor.isValid());   // true
147
console.log(invalidColor.isValid()); // false
148
console.log(emptyColor.isValid());   // false
149

150
// Validate user input
151
function processUserColor(input) {
152
  const color = tinycolor(input);
153
  if (!color.isValid()) {
154
    throw new Error("Invalid color format");
155
  }
156
  return color;
157
}
158
```
159

160
#### Get Original Input
161

162
Returns the original input that was used to create the color.
163

164
```javascript { .api }
165
/**
166
 * Returns the original input used to create the color
167
 * @returns any - the original input value
168
 */
169
getOriginalInput(): any;
170
```
171

172
**Usage Examples:**
173

174
```javascript
175
const hexColor = tinycolor("#ff0000");
176
const rgbColor = tinycolor("rgb(255, 0, 0)");
177
const objColor = tinycolor({ r: 255, g: 0, b: 0 });
178

179
console.log(hexColor.getOriginalInput());   // "#ff0000"
180
console.log(rgbColor.getOriginalInput());   // "rgb(255, 0, 0)"
181
console.log(objColor.getOriginalInput());   // { r: 255, g: 0, b: 0 }
182

183
// Store original format for round-trip conversions
184
const userInput = "#ff0000";
185
const color = tinycolor(userInput);
186
const originalFormat = color.getOriginalInput();
187
```
188

189
#### Get Input Format
190

191
Returns the format that was detected when parsing the input.
192

193
```javascript { .api }
194
/**
195
 * Returns the format that was detected during parsing
196
 * @returns string indicating the detected format
197
 */
198
getFormat(): string;
199
```
200

201
**Usage Examples:**
202

203
```javascript
204
const hexColor = tinycolor("#ff0000");
205
const rgbColor = tinycolor("rgb(255, 0, 0)");
206
const namedColor = tinycolor("red");
207
const objColor = tinycolor({ r: 255, g: 0, b: 0 });
208

209
console.log(hexColor.getFormat());   // "hex"
210
console.log(rgbColor.getFormat());   // "rgb"
211
console.log(namedColor.getFormat()); // "name"
212
console.log(objColor.getFormat());   // "rgb"
213

214
// Preserve original format in conversions
215
function preserveFormat(color) {
216
  const format = color.getFormat();
217
  switch (format) {
218
    case "hex": return color.toHexString();
219
    case "rgb": return color.toRgbString();
220
    case "hsl": return color.toHslString();
221
    case "name": return color.toName() || color.toHexString();
222
    default: return color.toString();
223
  }
224
}
225
```
226

227
#### Get Alpha Value
228

229
Returns the alpha (transparency) value of the color.
230

231
```javascript { .api }
232
/**
233
 * Returns the alpha value of the color
234
 * @returns number between 0-1 representing transparency (0 = transparent, 1 = opaque)
235
 */
236
getAlpha(): number;
237
```
238

239
**Usage Examples:**
240

241
```javascript
242
const opaqueColor = tinycolor("red");
243
const transparentColor = tinycolor("rgba(255, 0, 0, 0.5)");
244
const transparentHex = tinycolor("#ff000080");
245

246
console.log(opaqueColor.getAlpha());      // 1
247
console.log(transparentColor.getAlpha()); // 0.5
248
console.log(transparentHex.getAlpha());   // ~0.5
249

250
// Check if color needs transparency support
251
function needsAlphaChannel(color) {
252
  return color.getAlpha() < 1;
253
}
254

255
// Create CSS with appropriate format
256
function toCssColor(color) {
257
  return needsAlphaChannel(color) 
258
    ? color.toRgbString() 
259
    : color.toHexString();
260
}
261
```
262

263
## Analysis Workflows
264

265
### Color Classification
266

267
```javascript
268
function classifyColor(colorInput) {
269
  const color = tinycolor(colorInput);
270
  
271
  if (!color.isValid()) {
272
    return { type: "invalid" };
273
  }
274
  
275
  const brightness = color.getBrightness();
276
  const luminance = color.getLuminance();
277
  const alpha = color.getAlpha();
278
  
279
  return {
280
    type: "valid",
281
    darkness: color.isDark() ? "dark" : "light",
282
    brightness: brightness,
283
    luminance: luminance,
284
    transparency: alpha < 1 ? "transparent" : "opaque",
285
    format: color.getFormat(),
286
    original: color.getOriginalInput()
287
  };
288
}
289
```
290

291
### Accessibility Preparation
292

293
```javascript
294
function prepareForAccessibility(color) {
295
  return {
296
    color: color,
297
    luminance: color.getLuminance(),
298
    brightness: color.getBrightness(),
299
    isDark: color.isDark(),
300
    alpha: color.getAlpha(),
301
    // These values are used by tinycolor.readability()
302
    rgb: color.toRgb()
303
  };
304
}
305
```