0
# TinyColor2
1

2
TinyColor2 is a comprehensive JavaScript color manipulation and conversion library that provides fast, dependency-free color processing capabilities. It accepts multiple input formats (hex, RGB, HSL, HSV, named colors) and offers extensive conversion between color spaces, color analysis functions (brightness, contrast, readability), and color manipulation methods (lighten, darken, saturate, complement). The library is designed for maximum compatibility across environments including Node.js, browsers (both UMD and ESM formats), and Deno.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
import tinycolor from "tinycolor2";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const tinycolor = require("tinycolor2");
21
```
22

23
## Basic Usage
24

25
```javascript
26
import tinycolor from "tinycolor2";
27

28
// Create colors from various formats
29
const red = tinycolor("red");
30
const hex = tinycolor("#ff0000");
31
const rgb = tinycolor("rgb(255, 0, 0)");
32
const hsl = tinycolor({ h: 0, s: 1, l: 0.5 });
33

34
// Check color properties
35
console.log(red.isValid());        // true
36
console.log(red.isDark());         // true
37
console.log(red.getBrightness());  // 76.245
38

39
// Convert between formats
40
console.log(red.toHexString());    // "#ff0000"
41
console.log(red.toRgbString());    // "rgb(255, 0, 0)"
42
console.log(red.toHslString());    // "hsl(0, 100%, 50%)"
43

44
// Modify colors
45
const lightRed = red.lighten(20);
46
const darkRed = red.darken(20);
47
const complement = red.complement();
48
```
49

50
## Architecture
51

52
TinyColor2 is built around several key components:
53

54
- **Constructor Function**: Main `tinycolor()` function that creates color instances from various input formats
55
- **Instance Methods**: Color manipulation, conversion, and analysis methods available on color objects
56
- **Static Methods**: Utility functions for color comparison, mixing, and accessibility calculations
57
- **Color Parser**: Robust input parsing supporting hex, RGB, HSL, HSV, and named color formats
58
- **Constants**: Named color constants and hex-to-name lookup tables
59

60
## Capabilities
61

62
### Color Creation and Parsing
63

64
Core color creation functionality that accepts various input formats and creates tinycolor instances for manipulation.
65

66
```javascript { .api }
67
function tinycolor(color, opts);
68
```
69

70
[Color Creation](./color-creation.md)
71

72
### Color Information and Analysis
73

74
Methods for analyzing color properties including darkness, brightness, luminance, and validity checks.
75

76
```javascript { .api }
77
// Instance methods for color analysis
78
isDark(): boolean;
79
isLight(): boolean;
80
isValid(): boolean;
81
getBrightness(): number;
82
getLuminance(): number;
83
getAlpha(): number;
84
getOriginalInput(): any;
85
getFormat(): string;
86
```
87

88
[Color Analysis](./color-analysis.md)
89

90
### Color Format Conversion
91

92
Comprehensive conversion methods for transforming colors between different format representations (hex, RGB, HSL, HSV, named colors).
93

94
```javascript { .api }
95
// Instance methods for format conversion
96
toHex(allow3Char?: boolean): string;
97
toHexString(allow3Char?: boolean): string;
98
toHex8(allow4Char?: boolean): string;
99
toHex8String(allow4Char?: boolean): string;
100
toRgb(): {r: number, g: number, b: number, a: number};
101
toRgbString(): string;
102
toHsl(): {h: number, s: number, l: number, a: number};
103
toHslString(): string;
104
toHsv(): {h: number, s: number, v: number, a: number};
105
toHsvString(): string;
106
toName(): string | false;
107
toFilter(secondColor?: any): string;
108
toString(format?: string): string;
109
```
110

111
[Color Conversion](./color-conversion.md)
112

113
### Color Modification
114

115
Chainable methods for modifying color properties including lightening, darkening, saturation adjustments, and hue rotation.
116

117
```javascript { .api }
118
// Instance methods for color modification (all chainable)
119
setAlpha(value: number): tinycolor;
120
lighten(amount?: number): tinycolor;
121
darken(amount?: number): tinycolor;
122
brighten(amount?: number): tinycolor;
123
desaturate(amount?: number): tinycolor;
124
saturate(amount?: number): tinycolor;
125
greyscale(): tinycolor;
126
spin(amount: number): tinycolor;
127
clone(): tinycolor;
128
```
129

130
[Color Modification](./color-modification.md)
131

132
### Color Schemes and Combinations
133

134
Methods for generating color schemes including complements, triads, tetrads, analogous colors, and monochromatic variations.
135

136
```javascript { .api }
137
// Instance methods for color combinations
138
complement(): tinycolor;
139
analogous(results?: number, slices?: number): tinycolor[];
140
monochromatic(results?: number): tinycolor[];
141
splitcomplement(): tinycolor[];
142
triad(): tinycolor[];
143
tetrad(): tinycolor[];
144
```
145

146
[Color Schemes](./color-schemes.md)
147

148
### Accessibility and Readability
149

150
Static methods for calculating color contrast ratios and determining readability according to WCAG guidelines.
151

152
```javascript { .api }
153
// Static methods for accessibility
154
tinycolor.readability(color1: any, color2: any): number;
155
tinycolor.isReadable(color1: any, color2: any, wcag2?: object): boolean;
156
tinycolor.mostReadable(baseColor: any, colorList: any[], args?: object): tinycolor;
157
```
158

159
[Accessibility](./accessibility.md)
160

161
### Utility Functions
162

163
Additional utility functions for color comparison, mixing, random color generation, and working with ratio-based values.
164

165
```javascript { .api }
166
// Static utility methods
167
tinycolor.equals(color1: any, color2: any): boolean;
168
tinycolor.mix(color1: any, color2: any, amount?: number): tinycolor;
169
tinycolor.random(): tinycolor;
170
tinycolor.fromRatio(color: object, opts?: object): tinycolor;
171
```
172

173
[Utilities](./utilities.md)
174

175
## Constants
176

177
```javascript { .api }
178
// Named color constants
179
tinycolor.names: {[colorName: string]: string};
180

181
// Hex to name lookup
182
tinycolor.hexNames: {[hexValue: string]: string};
183
```
184

185
## Input Formats
186

187
TinyColor2 accepts colors in multiple formats:
188

189
- **Hex**: `#fff`, `#ffffff`, `#ffff`, `#ffffffff`
190
- **RGB**: `rgb(255, 0, 0)`, `rgba(255, 0, 0, 0.5)`
191
- **HSL**: `hsl(0, 100%, 50%)`, `hsla(0, 100%, 50%, 0.5)`
192
- **HSV**: `hsv(0, 100%, 100%)`, `hsva(0, 100%, 100%, 0.5)`
193
- **Named**: `red`, `blue`, `transparent`, and 147 CSS named colors
194
- **Objects**: `{r: 255, g: 0, b: 0}`, `{h: 0, s: 1, l: 0.5}`, `{h: 0, s: 1, v: 1}`
195
- **TinyColor instances**: Existing tinycolor objects
196

197
## Type Definitions
198

199
```javascript { .api }
200
// Color object formats
201
interface RgbColor {
202
  r: number;  // 0-255
203
  g: number;  // 0-255
204
  b: number;  // 0-255
205
  a?: number; // 0-1
206
}
207

208
interface HslColor {
209
  h: number;  // 0-360
210
  s: number;  // 0-1
211
  l: number;  // 0-1
212
  a?: number; // 0-1
213
}
214

215
interface HsvColor {
216
  h: number;  // 0-360
217
  s: number;  // 0-1
218
  v: number;  // 0-1
219
  a?: number; // 0-1
220
}
221

222
// Constructor options
223
interface TinyColorOptions {
224
  format?: string;
225
  gradientType?: string;
226
}
227

228
// WCAG readability options
229
interface WCAG2Options {
230
  level?: "AA" | "AAA";
231
  size?: "small" | "large";
232
}
233
```