tessl/npm-randomcolor
A tiny script for generating attractive random colors with customizable parameters
- Workspace
- tessl
- Visibility
- Public
- Created
- Last updated
- Describes
To install, run
npx @tessl/cli install tessl/npm-randomcolor@0.6.0index.mddocs/
randomColor
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.
Package Information
- Package Name: randomcolor
- Package Type: npm
- Language: JavaScript
- Installation:
npm install randomcolor
Core Imports
var randomColor = require('randomcolor');For AMD:
define(['randomcolor'], function(randomColor) {
// Use randomColor here
});For browser (global):
<script src="randomColor.js"></script>
<script>
var color = randomColor();
</script>Basic Usage
var randomColor = require('randomcolor');
// Generate a random attractive color (returns hex by default)
var color = randomColor(); // e.g. '#a3e2c4'
// Generate multiple colors
var colors = randomColor({
count: 5,
hue: 'blue'
}); // Returns array of 5 blue colors
// Control luminosity and format
var brightRgb = randomColor({
luminosity: 'bright',
format: 'rgb'
}); // e.g. 'rgb(225, 200, 20)'Capabilities
Color Generation
Generate single or multiple attractive random colors with extensive customization options.
/**
* Generate attractive random colors with customizable parameters
* @param {Object} options - Configuration object (optional)
* @param {string|number} options.hue - Color hue: 'red', 'orange', 'yellow', 'green', 'blue', 'purple', 'pink', 'monochrome', hex string, or numeric (0-360)
* @param {string} options.luminosity - Brightness control: 'bright', 'light', 'dark', or 'random'
* @param {number} options.count - Number of colors to generate (returns array when > 1)
* @param {number|string} options.seed - Seed for reproducible results (integer or string)
* @param {string} options.format - Output format: 'hex' (default), 'rgb', 'rgba', 'rgbArray', 'hsl', 'hsla', 'hslArray', 'hsvArray'
* @param {number} options.alpha - Alpha value (0-1) for rgba/hsla formats
* @returns {string|Array} Single color string or array of colors (when count > 1)
* @throws {TypeError} When seed value is not an integer or string
*/
function randomColor(options);Usage Examples:
// Basic usage - returns hex string
randomColor(); // '#a3e2c4'
// Specify hue by name
randomColor({ hue: 'red' }); // '#d73527'
// Specify numeric hue (0-360)
randomColor({ hue: 180 }); // Cyan hues
// Specify hue by hex color (extracts hue)
randomColor({ hue: '#00FFFF' }); // Colors with cyan hue
randomColor({ hue: '#FF0000' }); // Colors with red hue
// Control brightness
randomColor({ luminosity: 'bright' }); // Bright color
randomColor({ luminosity: 'light' }); // Light color
randomColor({ luminosity: 'dark' }); // Dark color
// Generate multiple colors
randomColor({ count: 3 }); // ['#a3e2c4', '#d73527', '#4f81bd']
// Reproducible colors with seed
randomColor({ seed: 12345 }); // Always same color
randomColor({ seed: 'hello' }); // String seeds also work
// Different output formats
randomColor({ format: 'rgb' }); // 'rgb(163, 226, 196)'
randomColor({ format: 'rgba' }); // 'rgba(163, 226, 196, 0.845)'
randomColor({ format: 'hsl' }); // 'hsl(154, 44%, 76%)'
randomColor({ format: 'hsla' }); // 'hsla(154, 44%, 76%, 0.612)'
randomColor({ format: 'rgbArray' }); // [163, 226, 196]
randomColor({ format: 'hslArray' }); // [154, 44, 76]
randomColor({ format: 'hsvArray' }); // [154, 28, 89]
// Control alpha for transparent formats
randomColor({
format: 'rgba',
alpha: 0.5
}); // 'rgba(163, 226, 196, 0.5)'
// Combine options
randomColor({
hue: 'blue',
luminosity: 'bright',
count: 5,
format: 'hex'
}); // Array of 5 bright blue hex colorsHue Options
Control the color hue using various input methods:
- Named colors:
'red','orange','yellow','green','blue','purple','pink','monochrome'(grayscale) - Hex strings:
'#FF0000','#00FFFF'(extracts hue value) - Numeric values:
0-360(degrees on color wheel)
Luminosity Options
Control the brightness and saturation characteristics:
'bright': High saturation, good brightness'light': Lower saturation, higher brightness'dark': Higher saturation, lower brightness'random': Full random brightness and saturation range
Format Options
Support for multiple color format outputs:
'hex':'#a3e2c4'(default)'rgb':'rgb(163, 226, 196)''rgba':'rgba(163, 226, 196, 0.845)''rgbArray':[163, 226, 196]'hsl':'hsl(154, 44%, 76%)''hsla':'hsla(154, 44%, 76%, 0.612)''hslArray':[154, 44, 76]'hsvArray':[154, 28, 89]
Batch Generation
Generate multiple colors at once with intelligent distribution:
// When options.count is specified, returns Array instead of string
randomColor({ count: 10 }); // Returns array of 10 colorsThe library automatically distributes colors across the specified hue range to avoid clustering and ensure variety in generated color sets.
Reproducible Generation
Use seeds for consistent, reproducible color generation:
// Integer seeds
randomColor({ seed: 12345 });
// String seeds (converted to integer internally)
randomColor({ seed: 'my-app-session' });Same seed values will always produce the same color sequence, making it perfect for consistent theming or deterministic color assignment.
Error Handling
The library throws a TypeError when an invalid seed is provided:
// These will throw TypeError
randomColor({ seed: {} }); // Object not allowed
randomColor({ seed: [] }); // Array not allowed
randomColor({ seed: true }); // Boolean not allowed
// These are valid
randomColor({ seed: 42 }); // Integer
randomColor({ seed: '42' }); // String
randomColor({ seed: null }); // null (no seed)
randomColor({ seed: undefined }); // undefined (no seed)