0
# Color Format Conversion
1

2
Comprehensive conversion methods for transforming colors between different format representations including hex, RGB, HSL, HSV, and named colors.
3

4
## Capabilities
5

6
### Hex Format Conversion
7

8
#### Convert to Hex
9

10
Returns hex representation without the hash prefix.
11

12
```javascript { .api }
13
/**
14
 * Returns hex representation without hash prefix
15
 * @param allow3Char - Allow 3-character hex shorthand when possible
16
 * @returns string hex value without #
17
 */
18
toHex(allow3Char?: boolean): string;
19
```
20

21
**Usage Examples:**
22

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

26
const red = tinycolor("red");
27
const darkGray = tinycolor("#333333");
28

29
console.log(red.toHex());           // "ff0000"
30
console.log(red.toHex(true));       // "f00" (3-char shorthand)
31
console.log(darkGray.toHex());      // "333333"
32
console.log(darkGray.toHex(true));  // "333" (3-char shorthand)
33
```
34

35
#### Convert to Hex String
36

37
Returns hex representation with the hash prefix.
38

39
```javascript { .api }
40
/**
41
 * Returns hex representation with hash prefix
42
 * @param allow3Char - Allow 3-character hex shorthand when possible
43
 * @returns string hex value with #
44
 */
45
toHexString(allow3Char?: boolean): string;
46
```
47

48
**Usage Examples:**
49

50
```javascript
51
const blue = tinycolor("blue");
52
const lightGray = tinycolor("#cccccc");
53

54
console.log(blue.toHexString());           // "#0000ff"
55
console.log(blue.toHexString(true));       // "#00f" (3-char shorthand)
56
console.log(lightGray.toHexString(true));  // "#ccc" (3-char shorthand)
57

58
// Common usage in CSS
59
const cssColor = blue.toHexString();
60
```
61

62
#### Convert to 8-Character Hex
63

64
Returns 8-character hex representation including alpha channel.
65

66
```javascript { .api }
67
/**
68
 * Returns 8-character hex with alpha channel
69
 * @param allow4Char - Allow 4-character hex shorthand when possible
70
 * @returns string 8-character hex value without #
71
 */
72
toHex8(allow4Char?: boolean): string;
73
```
74

75
**Usage Examples:**
76

77
```javascript
78
const semiTransparentRed = tinycolor("rgba(255, 0, 0, 0.5)");
79
const opaqueBlue = tinycolor("blue");
80

81
console.log(semiTransparentRed.toHex8());      // "ff000080"
82
console.log(semiTransparentRed.toHex8(true));  // "f008" (4-char shorthand)
83
console.log(opaqueBlue.toHex8());              // "0000ffff"
84
```
85

86
#### Convert to 8-Character Hex String
87

88
Returns 8-character hex representation with hash prefix including alpha.
89

90
```javascript { .api }
91
/**
92
 * Returns 8-character hex string with hash prefix and alpha
93
 * @param allow4Char - Allow 4-character hex shorthand when possible
94
 * @returns string 8-character hex value with #
95
 */
96
toHex8String(allow4Char?: boolean): string;
97
```
98

99
**Usage Examples:**
100

101
```javascript
102
const transparentGreen = tinycolor("rgba(0, 255, 0, 0.3)");
103

104
console.log(transparentGreen.toHex8String());      // "#00ff004d"
105
console.log(transparentGreen.toHex8String(true));  // "#0f04" (4-char shorthand)
106
```
107

108
### RGB Format Conversion
109

110
#### Convert to RGB Object
111

112
Returns RGB representation as an object.
113

114
```javascript { .api }
115
/**
116
 * Returns RGB representation as an object
117
 * @returns object with r, g, b (0-255) and a (0-1) properties
118
 */
119
toRgb(): {r: number, g: number, b: number, a: number};
120
```
121

122
**Usage Examples:**
123

124
```javascript
125
const purple = tinycolor("purple");
126
const rgba = tinycolor("rgba(128, 0, 128, 0.7)");
127

128
console.log(purple.toRgb());
129
// { r: 128, g: 0, b: 128, a: 1 }
130

131
console.log(rgba.toRgb());
132
// { r: 128, g: 0, b: 128, a: 0.7 }
133

134
// Destructure for individual values
135
const { r, g, b, a } = purple.toRgb();
136
```
137

138
#### Convert to RGB String
139

140
Returns RGB/RGBA string representation.
141

142
```javascript { .api }
143
/**
144
 * Returns RGB/RGBA string representation
145
 * @returns string RGB or RGBA format
146
 */
147
toRgbString(): string;
148
```
149

150
**Usage Examples:**
151

152
```javascript
153
const orange = tinycolor("orange");
154
const transparentOrange = tinycolor("rgba(255, 165, 0, 0.5)");
155

156
console.log(orange.toRgbString());           // "rgb(255, 165, 0)"
157
console.log(transparentOrange.toRgbString()); // "rgba(255, 165, 0, 0.5)"
158

159
// Use in CSS
160
const element = document.querySelector(".box");
161
element.style.backgroundColor = orange.toRgbString();
162
```
163

164
#### Convert to Percentage RGB
165

166
Returns RGB representation with percentage values.
167

168
```javascript { .api }
169
/**
170
 * Returns RGB representation with percentage values
171
 * @returns object with r, g, b as percentages (0-100) and a (0-1)
172
 */
173
toPercentageRgb(): {r: string, g: string, b: string, a: number};
174
```
175

176
**Usage Examples:**
177

178
```javascript
179
const cyan = tinycolor("cyan");
180

181
console.log(cyan.toPercentageRgb());
182
// { r: "0%", g: "100%", b: "100%", a: 1 }
183
```
184

185
#### Convert to Percentage RGB String
186

187
Returns RGB string with percentage values.
188

189
```javascript { .api }
190
/**
191
 * Returns RGB string with percentage values
192
 * @returns string RGB format with percentages
193
 */
194
toPercentageRgbString(): string;
195
```
196

197
**Usage Examples:**
198

199
```javascript
200
const yellow = tinycolor("yellow");
201

202
console.log(yellow.toPercentageRgbString());
203
// "rgb(100%, 100%, 0%)"
204
```
205

206
### HSL Format Conversion
207

208
#### Convert to HSL Object
209

210
Returns HSL representation as an object.
211

212
```javascript { .api }
213
/**
214
 * Returns HSL representation as an object
215
 * @returns object with h (0-360), s (0-1), l (0-1), and a (0-1) properties
216
 */
217
toHsl(): {h: number, s: number, l: number, a: number};
218
```
219

220
**Usage Examples:**
221

222
```javascript
223
const red = tinycolor("red");
224
const lightBlue = tinycolor("lightblue");
225

226
console.log(red.toHsl());
227
// { h: 0, s: 1, l: 0.5, a: 1 }
228

229
console.log(lightBlue.toHsl());
230
// { h: 195, s: 0.53, l: 0.79, a: 1 }
231

232
// Use for color adjustments
233
const { h, s, l, a } = red.toHsl();
234
const darkerRed = tinycolor({ h, s, l: l * 0.8, a });
235
```
236

237
#### Convert to HSL String
238

239
Returns HSL/HSLA string representation.
240

241
```javascript { .api }
242
/**
243
 * Returns HSL/HSLA string representation
244
 * @returns string HSL or HSLA format
245
 */
246
toHslString(): string;
247
```
248

249
**Usage Examples:**
250

251
```javascript
252
const green = tinycolor("green");
253
const transparentGreen = tinycolor("rgba(0, 128, 0, 0.6)");
254

255
console.log(green.toHslString());           // "hsl(120, 100%, 25%)"
256
console.log(transparentGreen.toHslString()); // "hsla(120, 100%, 25%, 0.6)"
257
```
258

259
### HSV Format Conversion
260

261
#### Convert to HSV Object
262

263
Returns HSV representation as an object.
264

265
```javascript { .api }
266
/**
267
 * Returns HSV representation as an object
268
 * @returns object with h (0-360), s (0-1), v (0-1), and a (0-1) properties
269
 */
270
toHsv(): {h: number, s: number, v: number, a: number};
271
```
272

273
**Usage Examples:**
274

275
```javascript
276
const magenta = tinycolor("magenta");
277

278
console.log(magenta.toHsv());
279
// { h: 300, s: 1, v: 1, a: 1 }
280

281
// Create color wheel
282
const colors = [];
283
for (let h = 0; h < 360; h += 30) {
284
  colors.push(tinycolor({ h, s: 1, v: 1 }));
285
}
286
```
287

288
#### Convert to HSV String
289

290
Returns HSV/HSVA string representation.
291

292
```javascript { .api }
293
/**
294
 * Returns HSV/HSVA string representation
295
 * @returns string HSV or HSVA format
296
 */
297
toHsvString(): string;
298
```
299

300
**Usage Examples:**
301

302
```javascript
303
const violet = tinycolor("violet");
304

305
console.log(violet.toHsvString());
306
// "hsv(300, 47%, 93%)"
307
```
308

309
### Named Color Conversion
310

311
#### Convert to Named Color
312

313
Returns the named color if one exists, otherwise returns false.
314

315
```javascript { .api }
316
/**
317
 * Returns the named color if available
318
 * @returns string named color or false if no name exists
319
 */
320
toName(): string | false;
321
```
322

323
**Usage Examples:**
324

325
```javascript
326
const red = tinycolor("#ff0000");
327
const customColor = tinycolor("#ff0001");
328

329
console.log(red.toName());        // "red"
330
console.log(customColor.toName()); // false
331

332
// Fallback to hex if no name available
333
function getColorName(color) {
334
  return color.toName() || color.toHexString();
335
}
336
```
337

338
### Universal String Conversion
339

340
#### Convert to String
341

342
Returns string representation in the specified format.
343

344
```javascript { .api }
345
/**
346
 * Returns string representation in specified format
347
 * @param format - Optional format specifier
348
 * @returns string representation of color
349
 */
350
toString(format?: string): string;
351
```
352

353
**Usage Examples:**
354

355
```javascript
356
const color = tinycolor("red");
357

358
console.log(color.toString());        // Uses original format or default
359
console.log(color.toString("hex"));   // "#ff0000"
360
console.log(color.toString("rgb"));   // "rgb(255, 0, 0)"
361
console.log(color.toString("hsl"));   // "hsl(0, 100%, 50%)"
362
console.log(color.toString("name"));  // "red"
363

364
// Auto-format based on alpha
365
function smartFormat(color) {
366
  return color.getAlpha() < 1 
367
    ? color.toString("rgb")  // Use RGBA for transparency
368
    : color.toString("hex"); // Use hex for opaque colors
369
}
370
```
371

372
### Legacy Format Support
373

374
#### Convert to IE Filter
375

376
Returns Internet Explorer filter string for gradients (legacy support).
377

378
```javascript { .api }
379
/**
380
 * Returns IE filter string for gradients
381
 * @param secondColor - Optional second color for gradient
382
 * @returns string IE filter format
383
 */
384
toFilter(secondColor?: any): string;
385
```
386

387
**Usage Examples:**
388

389
```javascript
390
const startColor = tinycolor("red");
391
const endColor = tinycolor("blue");
392

393
console.log(startColor.toFilter(endColor));
394
// "progid:DXImageTransform.Microsoft.gradient(startColorstr=#ffff0000,endColorstr=#ff0000ff)"
395

396
// Single color filter
397
console.log(startColor.toFilter());
398
// "progid:DXImageTransform.Microsoft.gradient(startColorstr=#ffff0000,endColorstr=#ffff0000)"
399
```
400

401
## Format Comparison Examples
402

403
```javascript
404
const color = tinycolor("rgba(255, 128, 0, 0.8)");
405

406
// All format outputs for the same color
407
console.log("Hex:", color.toHexString());           // "#ff8000"
408
console.log("Hex8:", color.toHex8String());         // "#ff8000cc"
409
console.log("RGB:", color.toRgbString());           // "rgba(255, 128, 0, 0.8)"
410
console.log("HSL:", color.toHslString());           // "hsla(30, 100%, 50%, 0.8)"
411
console.log("HSV:", color.toHsvString());           // "hsva(30, 100%, 100%, 0.8)"
412
console.log("Name:", color.toName() || "No name");  // "No name"
413

414
// Object formats
415
console.log("RGB Object:", color.toRgb());
416
// { r: 255, g: 128, b: 0, a: 0.8 }
417

418
console.log("HSL Object:", color.toHsl());
419
// { h: 30, s: 1, l: 0.5, a: 0.8 }
420

421
console.log("HSV Object:", color.toHsv());
422
// { h: 30, s: 1, v: 1, a: 0.8 }
423
```
424

425
## Cloning Colors
426

427
```javascript { .api }
428
/**
429
 * Creates a new tinycolor instance with the same color values
430
 * @returns new tinycolor instance
431
 */
432
clone(): tinycolor;
433
```
434

435
**Usage Examples:**
436

437
```javascript
438
const original = tinycolor("red");
439
const copy = original.clone();
440

441
// Modify copy without affecting original
442
copy.lighten(20);
443

444
console.log(original.toHexString()); // "#ff0000" (unchanged)
445
console.log(copy.toHexString());     // "#ff6666" (lightened)
446
```