0
# Color Creation and Parsing
1
2
Core color creation functionality that accepts various input formats and creates tinycolor instances for manipulation and analysis.
3
4
## Capabilities
5
6
### Main Constructor
7
8
Creates a tinycolor instance from various color input formats.
9
10
```javascript { .api }
11
/**
12
* Creates a tinycolor instance from various input formats
13
* @param color - Color input (string, object, or tinycolor instance)
14
* @param opts - Optional configuration object
15
* @returns tinycolor instance
16
*/
17
function tinycolor(color, opts);
18
```
19
20
**Parameters:**
21
- `color`: Can be hex string, RGB/RGBA/HSL/HSLA/HSV/HSVA string, named color, color object, or existing tinycolor instance
22
- `opts`: Optional object with `format` (string) and `gradientType` (string) properties
23
24
**Usage Examples:**
25
26
```javascript
27
import tinycolor from "tinycolor2";
28
29
// String formats
30
const red = tinycolor("red");
31
const hex = tinycolor("#ff0000");
32
const hex3 = tinycolor("#f00");
33
const hex8 = tinycolor("#ff0000ff");
34
const rgb = tinycolor("rgb(255, 0, 0)");
35
const rgba = tinycolor("rgba(255, 0, 0, 0.5)");
36
const hsl = tinycolor("hsl(0, 100%, 50%)");
37
const hsla = tinycolor("hsla(0, 100%, 50%, 0.8)");
38
39
// Object formats
40
const rgbObj = tinycolor({ r: 255, g: 0, b: 0 });
41
const rgbaObj = tinycolor({ r: 255, g: 0, b: 0, a: 0.5 });
42
const hslObj = tinycolor({ h: 0, s: 1, l: 0.5 });
43
const hslaObj = tinycolor({ h: 0, s: 1, l: 0.5, a: 0.8 });
44
const hsvObj = tinycolor({ h: 0, s: 1, v: 1 });
45
46
// With options
47
const color = tinycolor("#ff0000", { format: "hex" });
48
49
// From existing tinycolor (creates copy)
50
const copy = tinycolor(red);
51
```
52
53
### Static Creation Methods
54
55
#### From Ratio Values
56
57
Creates a tinycolor instance from ratio-based color values (0-1 range).
58
59
```javascript { .api }
60
/**
61
* Creates a tinycolor from ratio values (0-1 range)
62
* @param color - Color object with ratio values
63
* @param opts - Optional configuration object
64
* @returns tinycolor instance
65
*/
66
tinycolor.fromRatio(color, opts);
67
```
68
69
**Usage Examples:**
70
71
```javascript
72
// RGB ratios (0-1 instead of 0-255)
73
const red = tinycolor.fromRatio({ r: 1, g: 0, b: 0 });
74
const halfRed = tinycolor.fromRatio({ r: 0.5, g: 0, b: 0 });
75
76
// HSL ratios
77
const blue = tinycolor.fromRatio({ h: 0.67, s: 1, l: 0.5 });
78
79
// With alpha
80
const transparentRed = tinycolor.fromRatio({ r: 1, g: 0, b: 0, a: 0.5 });
81
```
82
83
#### Random Color Generation
84
85
Generates a random color.
86
87
```javascript { .api }
88
/**
89
* Generates a random color
90
* @returns tinycolor instance with random color
91
*/
92
tinycolor.random();
93
```
94
95
**Usage Examples:**
96
97
```javascript
98
const randomColor = tinycolor.random();
99
console.log(randomColor.toHexString()); // e.g., "#a3f7b2"
100
101
// Generate multiple random colors
102
const palette = Array.from({ length: 5 }, () => tinycolor.random());
103
```
104
105
## Supported Input Formats
106
107
### Hex Formats
108
- **3-character hex**: `#rgb` (e.g., `#f00`)
109
- **6-character hex**: `#rrggbb` (e.g., `#ff0000`)
110
- **4-character hex with alpha**: `#rgba` (e.g., `#f00f`)
111
- **8-character hex with alpha**: `#rrggbbaa` (e.g., `#ff0000ff`)
112
- **Without hash**: `rgb`, `rrggbb`, `rgba`, `rrggbbaa`
113
114
### String Formats
115
- **RGB**: `rgb(r, g, b)` where r,g,b are 0-255
116
- **RGBA**: `rgba(r, g, b, a)` where r,g,b are 0-255 and a is 0-1
117
- **HSL**: `hsl(h, s%, l%)` where h is 0-360, s and l are percentages
118
- **HSLA**: `hsla(h, s%, l%, a)` where h is 0-360, s and l are percentages, a is 0-1
119
- **HSV**: `hsv(h, s%, v%)` where h is 0-360, s and v are percentages
120
- **HSVA**: `hsva(h, s%, v%, a)` where h is 0-360, s and v are percentages, a is 0-1
121
122
### Object Formats
123
- **RGB Object**: `{r: number, g: number, b: number, a?: number}`
124
- **HSL Object**: `{h: number, s: number, l: number, a?: number}`
125
- **HSV Object**: `{h: number, s: number, v: number, a?: number}`
126
127
### Named Colors
128
Supports all 147 CSS named colors including:
129
- Basic colors: `red`, `green`, `blue`, `yellow`, `black`, `white`, `transparent`
130
- Extended colors: `aliceblue`, `antiquewhite`, `aqua`, `aquamarine`, etc.
131
132
### Special Cases
133
- **Empty/null input**: Returns black color with `isValid()` returning `false`
134
- **Invalid input**: Returns black color with `isValid()` returning `false`
135
- **TinyColor instance**: Returns the same instance (no copy made unless explicitly cloned)
136
137
## Validation
138
139
All created colors can be validated using the `isValid()` method:
140
141
```javascript
142
const valid = tinycolor("red");
143
const invalid = tinycolor("not-a-color");
144
145
console.log(valid.isValid()); // true
146
console.log(invalid.isValid()); // false
147
```