Finds the closest color name to a given hex, rgb and hsl color (with and without alpha). It uses the Euclidean distance formula to calculate the distance between colors in the RGB color space
npm install color-2-namenpm run benchmark in the library folder. See benchmarks.
colord package is meant without the color definitions while color-2-name already has everything you need bundled inside
npm install color-2-name
`
Then you can import or require the color-2-name function e.g. closest function from the color-2-name package:
`js
// ESM (import) - tree shakable
import {closest, distance, rgbToHex} from 'color-2-name';
closest('hsla(210deg 10% 96%)') // white
// CJS (require)
var color2Name = require("color-2-name")
color2Name.closest('#abcdef')
`
$3
To run the script in the browser, add the color-2-name add it to the header or footer like below
`js
`
#### The script is available at:
- unpkg - https://www.unpkg.com/color-2-name
- jsdelivr - https://cdn.jsdelivr.net/npm/color-2-name@latest
---
This Package includes the following functions:
- closest()
- distance()
- rgbToHex()
- isLight()
- isDark()
- closestRGB()
- getColor()
$3
Returns the closest color name
`js
// Here is an example of how to use the findClosestColor function:
const closestColor = closest('#ff8800');
console.log(closestColor); // { name: 'red', color: 'rgb(255,0,0)' }
// You can also use your custom set as comparation
return closest('#ff8800', [
[255, 0, 0, 'red'],
[0, 255, 0, 'green']
]); // -> { name: 'red', color: 'rgb(255,0,0)' }
// Alternatively you can also get the closest color in different color spaces in the following way:
return closest('#ff00ff', undefined, {info: true});
// {
// name: 'magenta',
// color: 'rgb(255,0,255),
// hex: '#ff00ff',
// hsl: 'hsl(300deg 100% 50%)',
// distance: 0
// }
`
In this example, the hex color '#ff8800' (which is a shade of orange) is compared to the colors in the colors array. The function returns the object with the name and hex value of the color that is closest to it, which in this case is the
object for the color red.
Arguments:
- color: a string representing a color, accepts hexadecimal, rgb and hsl with and without alpha channel (e.g. #ff0000 for hex red).
- colors: (optional) you can provide to this function a custom list of color names to be used (replaces the default)
- args: (optional) an Object that contains setup for this module
- args.info: (optional) set to true to display additional information the found color, like the hex value and the distance from the original
RETURNS an object with the name and nearest color that is closest to the given color. (eg. { name: 'red', color: 'rgb(255,0,0)' })
---
#### 💡distance()
Computes the distance between two colors using the euclidean distance formula.
`js
// Here is an example on how get the distance between two colors
const colorDivergence = distance([120, 255, 200], [255, 255, 255])
console.log(colorDivergence); // 123.465
`
Arguments:
- rgb1: an array of values representing rgb of the first color to be compared
- rgb2: an array of values representing rgb of the second color to be compared
RETURNS the distance between two colors, the maximum distance is >441 and the color is exactly the same when the value is 0
---
#### rgbToHex
Convert a rgb color into hexadecimal color
`js
// note: the rgb value is converted without take into account the alpha channel
const hex = rgbToHex('rgb(255,255,255)')
const hex2 = rgbToHex('rgb(255 255 255 / .5)')
// prints the hex result
console.log(hex); // #FFFFFF
console.log(hex2); // #FFFFFF
`
Arguments:
- rgb: a valid css rgb or rgba value (eg. rgb(1,2,3))
RETURNS the hex value of the color
---
#### 💡getColor()
search into ColorSet for the given color
`js
// note: the rgb value is converted without take into account the alpha channel
const white = getColor('white') // {"hex": "#ffffff", "hsl": "hsl(0,0%,100%)", "rgb": "rgb(255,255,255)"}
const alertColor = getColor('red') // {"hex": "#ff0000", "hsl": "hsl(0,100%,50%)", "rgb": "rgb(255,0,0)"}
// prints the hex result
console.log(alertColor.hsl); // #FFFFFF
console.log(alertColor.hex); // #FF0000
console.log("transparent red: " + alertColor.hex + "88"); // #FF000088
`
Arguments:
- colorName: the name of a color you need find in the colorset
RETURNS an Object with the color requested converted into hex, rgb and hsl
---
$3
#### 💡isLight()
Check if the color is light (optically closer to white)
#### 💡isDark()
Check if the color is dark (optically closer to black)
#### 💡closestRGB()
returns the closest RGB color
Arguments:
- color: a valid css color string
Examples:
`js
// note: the rgb value is converted without take into account the alpha channel
isLight('#fff') // true
isDark('#fff') // false
closestRGB('#FF1234') // red
`
---
#### 💡Build your own color set
First thing, clone the color-2-name package with git clone https://github.com/wp-blocks/color-2-name.git then cd into color-2-name folder.
In order to build a color set you need a json object with the following properties:
- name - the name of the color (like "Orange")
- color - the hex color value (like #FFAA00)
save it into ./src/data/ as "myNewColorSet.json". the file will contain something like this:
`json
[
{ "name": "white", "color": "#FFFFFF" },
{ "name": "black", "color": "#000000" },
{ "name": "red", "color": "#FF0000" },
{ "name": "green", "color": "#008000" },
{ "name": "blue", "color": "#0000FF" }
]
`
`bash
then run the following command
$ node colorSetUtils.mjs myNewColorSet
``