0
# Building Block Components
1

2
Reusable UI components for creating custom color pickers. These components handle specific parts of the color selection process and can be combined to build custom picker interfaces.
3

4
## Capabilities
5

6
### CustomPicker (ColorWrap HOC)
7

8
Higher-order component that wraps any component with color state management, normalization, and change handling. This is the foundation for all color picker components.
9

10
```javascript { .api }
11
/**
12
 * Higher-order component for creating custom color pickers
13
 * @param Component - React component to wrap with color functionality
14
 * @returns Enhanced component with color state management
15
 */
16
const CustomPicker: (Component: React.ComponentType) => React.ComponentType<ColorPickerProps>;
17
```
18

19
**Usage Example:**
20

21
```javascript
22
import React from 'react';
23
import { CustomPicker, Alpha, Hue } from 'react-color';
24

25
const MyCustomPicker = ({ hex, hsl, onChange }) => (
26
  <div>
27
    <div style={{ background: hex, width: 100, height: 100 }} />
28
    <Hue hsl={hsl} onChange={onChange} />
29
    <Alpha rgb={hsl} hsl={hsl} onChange={onChange} />
30
  </div>
31
);
32

33
export default CustomPicker(MyCustomPicker);
34
```
35

36
### Alpha
37

38
Alpha channel (transparency) slider component that allows users to control the opacity of the selected color.
39

40
```javascript { .api }
41
/**
42
 * Alpha channel slider component
43
 * @param props - Alpha component configuration
44
 */
45
const Alpha: React.ComponentType<AlphaProps>;
46

47
interface AlphaProps {
48
  /** RGB color values */
49
  rgb: { r: number; g: number; b: number; a: number };
50
  /** HSL color values */
51
  hsl: { h: number; s: number; l: number; a: number };
52
  /** Custom pointer component */
53
  pointer?: React.ComponentType;
54
  /** Rendering functions for custom elements */
55
  renderers?: object;
56
  /** Color change callback */
57
  onChange: (color: ColorState) => void;
58
  /** Slider direction */
59
  direction?: 'horizontal' | 'vertical';
60
  /** Custom styles */
61
  style?: object;
62
}
63
```
64

65
**Usage Example:**
66

67
```javascript
68
import { Alpha } from 'react-color';
69

70
<Alpha
71
  rgb={{ r: 255, g: 0, b: 0, a: 0.5 }}
72
  hsl={{ h: 0, s: 1, l: 0.5, a: 0.5 }}
73
  onChange={handleColorChange}
74
  direction="horizontal"
75
/>
76
```
77

78
### Hue
79

80
Hue slider component that allows users to select the hue (color) value on the color spectrum.
81

82
```javascript { .api }
83
/**
84
 * Hue slider component
85
 * @param props - Hue component configuration
86
 */
87
const Hue: React.ComponentType<HueProps>;
88

89
interface HueProps {
90
  /** HSL color values */
91
  hsl: { h: number; s: number; l: number; a: number };
92
  /** Custom pointer component */
93
  pointer?: React.ComponentType;
94
  /** Color change callback */
95
  onChange: (color: ColorState) => void;
96
  /** Slider direction */
97
  direction?: 'horizontal' | 'vertical';
98
  /** Custom styles */
99
  style?: object;
100
}
101
```
102

103
**Usage Example:**
104

105
```javascript
106
import { Hue } from 'react-color';
107

108
<Hue
109
  hsl={{ h: 180, s: 1, l: 0.5, a: 1 }}
110
  onChange={handleColorChange}
111
  direction="horizontal"
112
/>
113
```
114

115
### Saturation
116

117
Saturation and lightness picker area component that provides a 2D interface for selecting color saturation and lightness values.
118

119
```javascript { .api }
120
/**
121
 * Saturation/lightness picker area
122
 * @param props - Saturation component configuration
123
 */
124
const Saturation: React.ComponentType<SaturationProps>;
125

126
interface SaturationProps {
127
  /** HSL color values */
128
  hsl: { h: number; s: number; l: number; a: number };
129
  /** HSV color values */
130
  hsv: { h: number; s: number; v: number; a: number };
131
  /** Custom pointer component */
132
  pointer?: React.ComponentType;
133
  /** Color change callback */
134
  onChange: (color: ColorState) => void;
135
  /** Custom styles */
136
  style?: object;
137
}
138
```
139

140
**Usage Example:**
141

142
```javascript
143
import { Saturation } from 'react-color';
144

145
<Saturation
146
  hsl={{ h: 180, s: 0.5, l: 0.5, a: 1 }}
147
  hsv={{ h: 180, s: 1, v: 1, a: 1 }}
148
  onChange={handleColorChange}
149
/>
150
```
151

152
### Checkboard
153

154
Transparent background pattern component that displays a checkboard pattern behind transparent colors to visualize alpha transparency.
155

156
```javascript { .api }
157
/**
158
 * Transparent background checkboard pattern
159
 * @param props - Checkboard component configuration
160
 */
161
const Checkboard: React.ComponentType<CheckboardProps>;
162

163
interface CheckboardProps {
164
  /** Border radius for rounded corners */
165
  borderRadius?: string;
166
  /** Size of checkboard squares */
167
  size?: number;
168
  /** Color of white squares */
169
  white?: string;
170
  /** Color of grey squares */
171
  grey?: string;
172
  /** Custom rendering functions */
173
  renderers?: object;
174
}
175
```
176

177
**Usage Example:**
178

179
```javascript
180
import { Checkboard } from 'react-color';
181

182
<div style={{ position: 'relative', width: 100, height: 100 }}>
183
  <Checkboard borderRadius="4px" />
184
  <div style={{ 
185
    position: 'absolute', 
186
    top: 0, 
187
    left: 0, 
188
    right: 0, 
189
    bottom: 0, 
190
    background: 'rgba(255, 0, 0, 0.5)' 
191
  }} />
192
</div>
193
```
194

195
### EditableInput
196

197
Editable text input component with validation for color values. Supports different input formats and provides real-time validation.
198

199
```javascript { .api }
200
/**
201
 * Editable text input with color validation
202
 * @param props - EditableInput component configuration
203
 */
204
const EditableInput: React.ComponentType<EditableInputProps>;
205

206
interface EditableInputProps {
207
  /** Current input value */
208
  value: string | number;
209
  /** Label for the input */
210
  label?: string;
211
  /** Change callback */
212
  onChange: (value: string | number, event: Event) => void;
213
  /** Custom styles */
214
  style?: { input?: object; label?: object; wrap?: object };
215
  /** Placeholder text */
216
  placeholder?: string;
217
  /** Arrow offset for positioning */
218
  arrowOffset?: number;
219
  /** Drag label for draggable inputs */
220
  dragLabel?: boolean;
221
  /** Maximum drag value */
222
  dragMax?: number;
223
}
224
```
225

226
**Usage Example:**
227

228
```javascript
229
import { EditableInput } from 'react-color';
230

231
<EditableInput
232
  value="#ff0000"
233
  label="Hex"
234
  onChange={(value) => handleHexChange(value)}
235
  style={{ input: { width: 80 } }}
236
/>
237
```
238

239
### Swatch
240

241
Individual color swatch component that displays a clickable color sample.
242

243
```javascript { .api }
244
/**
245
 * Individual color swatch component
246
 * @param props - Swatch component configuration
247
 */
248
const Swatch: React.ComponentType<SwatchProps>;
249

250
interface SwatchProps {
251
  /** Color value to display */
252
  color: string;
253
  /** Custom styles */
254
  style?: object;
255
  /** Click callback */
256
  onClick?: (color: string, event: Event) => void;
257
  /** Hover callback */
258
  onHover?: (color: string, event: Event) => void;
259
  /** Swatch title/tooltip */
260
  title?: string;
261
  /** Child elements */
262
  children?: React.ReactNode;
263
  /** Focus state */
264
  focus?: boolean;
265
  /** Focus styles */
266
  focusStyle?: object;
267
}
268
```
269

270
**Usage Example:**
271

272
```javascript
273
import { Swatch } from 'react-color';
274

275
<Swatch
276
  color="#ff0000"
277
  onClick={(color) => handleColorSelect(color)}
278
  onHover={(color) => handleColorHover(color)}
279
  title="Red"
280
  style={{ width: 20, height: 20 }}
281
/>
282
```
283

284
### Raised
285

286
Container component that provides elevation styling with shadow effects for a "raised" appearance.
287

288
```javascript { .api }
289
/**
290
 * Container with raised/elevated appearance
291
 * @param props - Raised component configuration
292
 */
293
const Raised: React.ComponentType<RaisedProps>;
294

295
interface RaisedProps {
296
  /** Custom styles */
297
  style?: object;
298
  /** ReactCSS styles object */
299
  styles?: object;
300
  /** Shadow depth level (0-5) */
301
  zDepth?: 0 | 1 | 2 | 3 | 4 | 5;
302
  /** Border radius */
303
  radius?: number;
304
  /** Background color */
305
  background?: string;
306
  /** Child elements */
307
  children?: React.ReactNode;
308
}
309
```
310

311
**Default Props:**
312
- `background`: '#fff'
313
- `zDepth`: 1
314
- `radius`: 2
315

316
**Usage Example:**
317

318
```javascript
319
import { Raised } from 'react-color';
320

321
<Raised zDepth={2} radius={4} background="#fff">
322
  <div>Content with elevated appearance</div>
323
</Raised>
324
```
325

326
## Creating Custom Pickers
327

328
Building block components can be combined with the CustomPicker HOC to create entirely custom color picker interfaces:
329

330
```javascript
331
import React from 'react';
332
import { CustomPicker, Saturation, Hue, Alpha, EditableInput } from 'react-color';
333

334
const MyPicker = ({ hex, hsl, hsv, rgb, onChange }) => (
335
  <div style={{ width: 300 }}>
336
    {/* Saturation/lightness area */}
337
    <div style={{ height: 200, position: 'relative' }}>
338
      <Saturation hsl={hsl} hsv={hsv} onChange={onChange} />
339
    </div>
340
    
341
    {/* Hue slider */}
342
    <div style={{ height: 20, marginTop: 10 }}>
343
      <Hue hsl={hsl} onChange={onChange} />
344
    </div>
345
    
346
    {/* Alpha slider */}
347
    <div style={{ height: 20, marginTop: 10 }}>
348
      <Alpha rgb={rgb} hsl={hsl} onChange={onChange} />
349
    </div>
350
    
351
    {/* Color inputs */}
352
    <div style={{ display: 'flex', marginTop: 10 }}>
353
      <EditableInput
354
        style={{ input: { width: 60 } }}
355
        label="hex"
356
        value={hex}
357
        onChange={onChange}
358
      />
359
      <EditableInput
360
        style={{ input: { width: 40 } }}
361
        label="r"
362
        value={rgb.r}
363
        onChange={onChange}
364
      />
365
      <EditableInput
366
        style={{ input: { width: 40 } }}
367
        label="g"
368
        value={rgb.g}
369
        onChange={onChange}
370
      />
371
      <EditableInput
372
        style={{ input: { width: 40 } }}
373
        label="b"
374
        value={rgb.b}
375
        onChange={onChange}
376
      />
377
    </div>
378
  </div>
379
);
380

381
export default CustomPicker(MyPicker);
382
```
383

384
## Component Props
385

386
All building block components receive color data and change handlers as props. The CustomPicker HOC automatically provides normalized color data to wrapped components:
387

388
```javascript { .api }
389
interface WrappedComponentProps {
390
  /** Hex color string */
391
  hex: string;
392
  /** RGB color object */
393
  rgb: { r: number; g: number; b: number; a: number };
394
  /** HSL color object */
395
  hsl: { h: number; s: number; l: number; a: number };
396
  /** HSV color object */
397
  hsv: { h: number; s: number; v: number; a: number };
398
  /** Previous hue value */
399
  oldHue: number;
400
  /** Color change source */
401
  source: string;
402
  /** Change callback */
403
  onChange: (color: ColorState) => void;
404
  /** Swatch hover callback (if onSwatchHover provided) */
405
  onSwatchHover?: (color: ColorState) => void;
406
}
407
```