0
# randomColor
1

2
randomColor is a tiny JavaScript library for generating attractive random colors with customizable parameters. It provides a comprehensive API for controlling color generation through hue selection, luminosity control, output format options, seeding for reproducible sequences, and batch generation capabilities.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
var randomColor = require('randomcolor');
15
```
16

17
For AMD:
18

19
```javascript
20
define(['randomcolor'], function(randomColor) {
21
  // Use randomColor here
22
});
23
```
24

25
For browser (global):
26

27
```html
28
<script src="randomColor.js"></script>
29
<script>
30
  var color = randomColor();
31
</script>
32
```
33

34
## Basic Usage
35

36
```javascript
37
var randomColor = require('randomcolor');
38

39
// Generate a random attractive color (returns hex by default)
40
var color = randomColor(); // e.g. '#a3e2c4'
41

42
// Generate multiple colors
43
var colors = randomColor({
44
  count: 5,
45
  hue: 'blue'
46
}); // Returns array of 5 blue colors
47

48
// Control luminosity and format
49
var brightRgb = randomColor({
50
  luminosity: 'bright',
51
  format: 'rgb'
52
}); // e.g. 'rgb(225, 200, 20)'
53
```
54

55
## Capabilities
56

57
### Color Generation
58

59
Generate single or multiple attractive random colors with extensive customization options.
60

61
```javascript { .api }
62
/**
63
 * Generate attractive random colors with customizable parameters
64
 * @param {Object} options - Configuration object (optional)
65
 * @param {string|number} options.hue - Color hue: 'red', 'orange', 'yellow', 'green', 'blue', 'purple', 'pink', 'monochrome', hex string, or numeric (0-360)
66
 * @param {string} options.luminosity - Brightness control: 'bright', 'light', 'dark', or 'random'
67
 * @param {number} options.count - Number of colors to generate (returns array when > 1)
68
 * @param {number|string} options.seed - Seed for reproducible results (integer or string)
69
 * @param {string} options.format - Output format: 'hex' (default), 'rgb', 'rgba', 'rgbArray', 'hsl', 'hsla', 'hslArray', 'hsvArray'
70
 * @param {number} options.alpha - Alpha value (0-1) for rgba/hsla formats
71
 * @returns {string|Array} Single color string or array of colors (when count > 1)
72
 * @throws {TypeError} When seed value is not an integer or string
73
 */
74
function randomColor(options);
75
```
76

77
**Usage Examples:**
78

79
```javascript
80
// Basic usage - returns hex string
81
randomColor(); // '#a3e2c4'
82

83
// Specify hue by name
84
randomColor({ hue: 'red' }); // '#d73527'
85

86
// Specify numeric hue (0-360)
87
randomColor({ hue: 180 }); // Cyan hues
88

89
// Specify hue by hex color (extracts hue)
90
randomColor({ hue: '#00FFFF' }); // Colors with cyan hue
91
randomColor({ hue: '#FF0000' }); // Colors with red hue
92

93
// Control brightness
94
randomColor({ luminosity: 'bright' }); // Bright color
95
randomColor({ luminosity: 'light' }); // Light color
96
randomColor({ luminosity: 'dark' }); // Dark color
97

98
// Generate multiple colors
99
randomColor({ count: 3 }); // ['#a3e2c4', '#d73527', '#4f81bd']
100

101
// Reproducible colors with seed
102
randomColor({ seed: 12345 }); // Always same color
103
randomColor({ seed: 'hello' }); // String seeds also work
104

105
// Different output formats
106
randomColor({ format: 'rgb' }); // 'rgb(163, 226, 196)'
107
randomColor({ format: 'rgba' }); // 'rgba(163, 226, 196, 0.845)'
108
randomColor({ format: 'hsl' }); // 'hsl(154, 44%, 76%)'
109
randomColor({ format: 'hsla' }); // 'hsla(154, 44%, 76%, 0.612)'
110
randomColor({ format: 'rgbArray' }); // [163, 226, 196]
111
randomColor({ format: 'hslArray' }); // [154, 44, 76]
112
randomColor({ format: 'hsvArray' }); // [154, 28, 89]
113

114
// Control alpha for transparent formats
115
randomColor({ 
116
  format: 'rgba', 
117
  alpha: 0.5 
118
}); // 'rgba(163, 226, 196, 0.5)'
119

120
// Combine options
121
randomColor({
122
  hue: 'blue',
123
  luminosity: 'bright',
124
  count: 5,
125
  format: 'hex'
126
}); // Array of 5 bright blue hex colors
127
```
128

129
### Hue Options
130

131
Control the color hue using various input methods:
132

133
- **Named colors**: `'red'`, `'orange'`, `'yellow'`, `'green'`, `'blue'`, `'purple'`, `'pink'`, `'monochrome'` (grayscale)
134
- **Hex strings**: `'#FF0000'`, `'#00FFFF'` (extracts hue value)
135
- **Numeric values**: `0-360` (degrees on color wheel)
136

137
### Luminosity Options
138

139
Control the brightness and saturation characteristics:
140

141
- **`'bright'`**: High saturation, good brightness
142
- **`'light'`**: Lower saturation, higher brightness  
143
- **`'dark'`**: Higher saturation, lower brightness
144
- **`'random'`**: Full random brightness and saturation range
145

146
### Format Options
147

148
Support for multiple color format outputs:
149

150
- **`'hex'`**: `'#a3e2c4'` (default)
151
- **`'rgb'`**: `'rgb(163, 226, 196)'`
152
- **`'rgba'`**: `'rgba(163, 226, 196, 0.845)'`
153
- **`'rgbArray'`**: `[163, 226, 196]`
154
- **`'hsl'`**: `'hsl(154, 44%, 76%)'`
155
- **`'hsla'`**: `'hsla(154, 44%, 76%, 0.612)'`
156
- **`'hslArray'`**: `[154, 44, 76]`
157
- **`'hsvArray'`**: `[154, 28, 89]`
158

159
### Batch Generation
160

161
Generate multiple colors at once with intelligent distribution:
162

163
```javascript { .api }
164
// When options.count is specified, returns Array instead of string
165
randomColor({ count: 10 }); // Returns array of 10 colors
166
```
167

168
The library automatically distributes colors across the specified hue range to avoid clustering and ensure variety in generated color sets.
169

170
### Reproducible Generation
171

172
Use seeds for consistent, reproducible color generation:
173

174
```javascript { .api }
175
// Integer seeds
176
randomColor({ seed: 12345 });
177

178
// String seeds (converted to integer internally)
179
randomColor({ seed: 'my-app-session' });
180
```
181

182
Same seed values will always produce the same color sequence, making it perfect for consistent theming or deterministic color assignment.
183

184
## Error Handling
185

186
The library throws a `TypeError` when an invalid seed is provided:
187

188
```javascript
189
// These will throw TypeError
190
randomColor({ seed: {} }); // Object not allowed
191
randomColor({ seed: [] }); // Array not allowed
192
randomColor({ seed: true }); // Boolean not allowed
193

194
// These are valid
195
randomColor({ seed: 42 }); // Integer
196
randomColor({ seed: '42' }); // String
197
randomColor({ seed: null }); // null (no seed)
198
randomColor({ seed: undefined }); // undefined (no seed)
199
```