0
# React Colorful
1

2
React Colorful is a tiny (2.8 KB), lightweight color picker component library for React and Preact applications. It offers a comprehensive collection of color picker components supporting multiple color formats (HEX, RGB, RGBA, HSL, HSLA, HSV, HSVA) along with their string representations. The library is designed with performance and accessibility in mind, featuring zero dependencies, TypeScript support, and WAI-ARIA compliance.
3

4
## Package Information
5

6
- **Package Name**: react-colorful
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-colorful`
10
- **Peer Dependencies**: React >=16.8.0, React DOM >=16.8.0
11

12
## Core Imports
13

14
```typescript
15
import { HexColorPicker, RgbColorPicker, HslColorPicker } from "react-colorful";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { HexColorPicker, RgbColorPicker, HslColorPicker } = require("react-colorful");
22
```
23

24
Tree-shakeable imports (recommended):
25

26
```typescript
27
import { HexColorPicker } from "react-colorful";
28
import { RgbaColorPicker } from "react-colorful";
29
import { HexColorInput } from "react-colorful";
30
```
31

32
## Basic Usage
33

34
```typescript
35
import React, { useState } from "react";
36
import { HexColorPicker } from "react-colorful";
37

38
const ColorPickerApp = () => {
39
  const [color, setColor] = useState("#aabbcc");
40

41
  return (
42
    <div>
43
      <HexColorPicker color={color} onChange={setColor} />
44
      <p>Selected color: {color}</p>
45
    </div>
46
  );
47
};
48
```
49

50
## Architecture
51

52
React Colorful is built around several key components:
53

54
- **Color Picker Components**: 15 components for different color formats (basic, alpha channel, string formats)
55
- **Input Components**: Text input with validation for hexadecimal colors
56
- **Type System**: Complete TypeScript interfaces for all color formats and component props
57
- **Color Models**: Internal conversion system between different color representations
58
- **CSP Support**: Content Security Policy compliance via nonce utilities
59

60
## Capabilities
61

62
### Basic Color Pickers
63

64
Color pickers for basic color formats without alpha channel support.
65

66
```typescript { .api }
67
/**
68
 * Color picker for hexadecimal color values (6-digit format)
69
 * @param props - ColorPickerBaseProps with string color type
70
 */
71
function HexColorPicker(props: Partial<ColorPickerBaseProps<string>>): JSX.Element;
72

73
/**
74
 * Color picker for RGB color objects
75
 * @param props - ColorPickerBaseProps with RgbColor type
76
 */
77
function RgbColorPicker(props: Partial<ColorPickerBaseProps<RgbColor>>): JSX.Element;
78

79
/**
80
 * Color picker for HSL color objects
81
 * @param props - ColorPickerBaseProps with HslColor type
82
 */
83
function HslColorPicker(props: Partial<ColorPickerBaseProps<HslColor>>): JSX.Element;
84

85
/**
86
 * Color picker for HSV color objects
87
 * @param props - ColorPickerBaseProps with HsvColor type
88
 */
89
function HsvColorPicker(props: Partial<ColorPickerBaseProps<HsvColor>>): JSX.Element;
90
```
91

92
**Usage Examples:**
93

94
```typescript
95
import { HexColorPicker, RgbColorPicker, HslColorPicker } from "react-colorful";
96

97
// Hex color picker
98
<HexColorPicker color="#ff6b6b" onChange={setHexColor} />
99

100
// RGB color picker
101
<RgbColorPicker 
102
  color={{ r: 255, g: 107, b: 107 }} 
103
  onChange={setRgbColor} 
104
/>
105

106
// HSL color picker
107
<HslColorPicker 
108
  color={{ h: 0, s: 75, l: 71 }} 
109
  onChange={setHslColor} 
110
/>
111
```
112

113
### Alpha Channel Color Pickers
114

115
Color pickers that include alpha (transparency) channel support.
116

117
```typescript { .api }
118
/**
119
 * Color picker for hexadecimal colors with alpha (8-digit format)
120
 * @param props - ColorPickerBaseProps with string color type
121
 */
122
function HexAlphaColorPicker(props: Partial<ColorPickerBaseProps<string>>): JSX.Element;
123

124
/**
125
 * Color picker for RGBA color objects
126
 * @param props - ColorPickerBaseProps with RgbaColor type
127
 */
128
function RgbaColorPicker(props: Partial<ColorPickerBaseProps<RgbaColor>>): JSX.Element;
129

130
/**
131
 * Color picker for HSLA color objects
132
 * @param props - ColorPickerBaseProps with HslaColor type
133
 */
134
function HslaColorPicker(props: Partial<ColorPickerBaseProps<HslaColor>>): JSX.Element;
135

136
/**
137
 * Color picker for HSVA color objects
138
 * @param props - ColorPickerBaseProps with HsvaColor type
139
 */
140
function HsvaColorPicker(props: Partial<ColorPickerBaseProps<HsvaColor>>): JSX.Element;
141
```
142

143
**Usage Examples:**
144

145
```typescript
146
import { HexAlphaColorPicker, RgbaColorPicker } from "react-colorful";
147

148
// Hex with alpha
149
<HexAlphaColorPicker color="#ff6b6b80" onChange={setHexAlphaColor} />
150

151
// RGBA color picker
152
<RgbaColorPicker 
153
  color={{ r: 255, g: 107, b: 107, a: 0.5 }} 
154
  onChange={setRgbaColor} 
155
/>
156
```
157

158
### String Format Color Pickers
159

160
Color pickers that work with CSS string representations of colors.
161

162
```typescript { .api }
163
/**
164
 * Color picker for RGB color strings (e.g., "rgb(255, 107, 107)")
165
 * @param props - ColorPickerBaseProps with string color type
166
 */
167
function RgbStringColorPicker(props: Partial<ColorPickerBaseProps<string>>): JSX.Element;
168

169
/**
170
 * Color picker for RGBA color strings (e.g., "rgba(255, 107, 107, 0.5)")
171
 * @param props - ColorPickerBaseProps with string color type
172
 */
173
function RgbaStringColorPicker(props: Partial<ColorPickerBaseProps<string>>): JSX.Element;
174

175
/**
176
 * Color picker for HSL color strings (e.g., "hsl(0, 75%, 71%)")
177
 * @param props - ColorPickerBaseProps with string color type
178
 */
179
function HslStringColorPicker(props: Partial<ColorPickerBaseProps<string>>): JSX.Element;
180

181
/**
182
 * Color picker for HSLA color strings (e.g., "hsla(0, 75%, 71%, 0.5)")
183
 * @param props - ColorPickerBaseProps with string color type
184
 */
185
function HslaStringColorPicker(props: Partial<ColorPickerBaseProps<string>>): JSX.Element;
186

187
/**
188
 * Color picker for HSV color strings (e.g., "hsv(0, 58%, 100%)")
189
 * @param props - ColorPickerBaseProps with string color type
190
 */
191
function HsvStringColorPicker(props: Partial<ColorPickerBaseProps<string>>): JSX.Element;
192

193
/**
194
 * Color picker for HSVA color strings (e.g., "hsva(0, 58%, 100%, 0.5)")
195
 * @param props - ColorPickerBaseProps with string color type
196
 */
197
function HsvaStringColorPicker(props: Partial<ColorPickerBaseProps<string>>): JSX.Element;
198
```
199

200
### Color Input Components
201

202
Text input components with validation for color values.
203

204
```typescript { .api }
205
/**
206
 * Text input for hexadecimal color values with validation
207
 * @param props - HexColorInputProps including validation options
208
 */
209
function HexColorInput(props: HexColorInputProps): JSX.Element;
210

211
interface HexColorInputProps extends ColorInputBaseProps {
212
  /** Current hex color value (optional) */
213
  color?: string;
214
  /** Color change callback (optional) */
215
  onChange?: (newColor: string) => void;
216
  /** Enables "#" prefix displaying */
217
  prefixed?: boolean;
218
  /** Allows #rgba and #rrggbbaa color formats */
219
  alpha?: boolean;
220
}
221
```
222

223
**Usage Examples:**
224

225
```typescript
226
import { HexColorInput } from "react-colorful";
227

228
// Basic hex input
229
<HexColorInput color={color} onChange={setColor} />
230

231
// With prefix display
232
<HexColorInput color={color} onChange={setColor} prefixed />
233

234
// With alpha support
235
<HexColorInput color={color} onChange={setColor} alpha />
236
```
237

238
### Content Security Policy Support
239

240
Utility functions for CSP compliance in applications with strict content security policies.
241

242
```typescript { .api }
243
/**
244
 * Signs style tags with a base64-encoded nonce for CSP compliance
245
 * Must be called before any picker is rendered if not using Webpack for CSP
246
 * @param hash - Base64-encoded nonce string
247
 */
248
function setNonce(hash: string): void;
249
```
250

251
**Usage Example:**
252

253
```typescript
254
import { setNonce } from "react-colorful";
255

256
// Set nonce before rendering any color pickers
257
setNonce("your-csp-nonce-here");
258
```
259

260
## Types
261

262
### Color Object Interfaces
263

264
```typescript { .api }
265
/** RGB color representation with red, green, blue values (0-255) */
266
interface RgbColor {
267
  r: number;
268
  g: number;
269
  b: number;
270
}
271

272
/** RGBA color representation extending RGB with alpha (0-1) */
273
interface RgbaColor extends RgbColor {
274
  a: number;
275
}
276

277
/** HSL color representation with hue (0-360), saturation (0-100), lightness (0-100) */
278
interface HslColor {
279
  h: number;
280
  s: number;
281
  l: number;
282
}
283

284
/** HSLA color representation extending HSL with alpha (0-1) */
285
interface HslaColor extends HslColor {
286
  a: number;
287
}
288

289
/** HSV color representation with hue (0-360), saturation (0-100), value (0-100) */
290
interface HsvColor {
291
  h: number;
292
  s: number;
293
  v: number;
294
}
295

296
/** HSVA color representation extending HSV with alpha (0-1) */
297
interface HsvaColor extends HsvColor {
298
  a: number;
299
}
300

301
/** Union type of all color object types */
302
type ObjectColor = RgbColor | HslColor | HsvColor | RgbaColor | HslaColor | HsvaColor;
303

304
/** Union type of string and object color types */
305
type AnyColor = string | ObjectColor;
306
```
307

308
### Component Props Interfaces
309

310
```typescript { .api }
311
/** Base props for color picker components */
312
interface ColorPickerBaseProps<T extends AnyColor> extends Omit<React.HTMLAttributes<HTMLDivElement>, "color" | "onChange" | "onChangeCapture"> {
313
  /** Current color value */
314
  color: T;
315
  /** Color change callback */
316
  onChange: (newColor: T) => void;
317
}
318

319
/** Base props for color input components */
320
interface ColorInputBaseProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "onChange" | "value"> {
321
  /** Current color value (optional) */
322
  color?: string;
323
  /** Color change callback (optional) */
324
  onChange?: (newColor: string) => void;
325
}
326
```
327

328
### Internal Color Model Interface
329

330
```typescript { .api }
331
/** Color model configuration interface (internal use) */
332
interface ColorModel<T extends AnyColor> {
333
  defaultColor: T;
334
  toHsva: (defaultColor: T) => HsvaColor;
335
  fromHsva: (hsva: HsvaColor) => T;
336
  equal: (first: T, second: T) => boolean;
337
}
338
```
339

340
## Color Value Formats
341

342
### Supported Input/Output Formats by Component
343

344
- **HexColorPicker**: `"#ffffff"` (6-digit hex)
345
- **HexAlphaColorPicker**: `"#ffffff88"` (8-digit hex with alpha)
346
- **RgbColorPicker**: `{ r: 255, g: 255, b: 255 }`
347
- **RgbaColorPicker**: `{ r: 255, g: 255, b: 255, a: 1 }`
348
- **RgbStringColorPicker**: `"rgb(255, 255, 255)"`
349
- **RgbaStringColorPicker**: `"rgba(255, 255, 255, 1)"`
350
- **HslColorPicker**: `{ h: 0, s: 0, l: 100 }`
351
- **HslaColorPicker**: `{ h: 0, s: 0, l: 100, a: 1 }`
352
- **HslStringColorPicker**: `"hsl(0, 0%, 100%)"`
353
- **HslaStringColorPicker**: `"hsla(0, 0%, 100%, 1)"`
354
- **HsvColorPicker**: `{ h: 0, s: 0, v: 100 }`
355
- **HsvaColorPicker**: `{ h: 0, s: 0, v: 100, a: 1 }`
356
- **HsvStringColorPicker**: `"hsv(0, 0%, 100%)"`
357
- **HsvaStringColorPicker**: `"hsva(0, 0%, 100%, 1)"`
358

359
## Key Features
360

361
- **Tree-shakeable**: All components can be imported individually to reduce bundle size
362
- **TypeScript support**: Complete type definitions for all components and color formats
363
- **Accessibility**: WAI-ARIA compliant with keyboard navigation and screen reader support
364
- **Mobile-friendly**: Touch screen support with responsive design
365
- **Zero dependencies**: No external runtime dependencies
366
- **Lightweight**: Only 2.8 KB gzipped
367
- **CSP compatible**: Content Security Policy support via setNonce utility
368
- **Cross-browser compatibility**: Supports all modern browsers
369
- **Framework agnostic**: Works with both React and Preact