davidfq / named-web-colors

Javascript utility to translate Hex color codes into human-friendly color names.

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Named Web colors

Javascript utility to translate Hex color codes into human-friendly color names. Given an input color, it uses a simple Euclidean distance algorithm to find the closest color among a curated colors list of 1,567 references.

Heavily inspired by Name that color JavaScript, Chirag Mehta, 2007 (CC BY 2.5). This project also includes a colors list from the beautiful and insipiring Werner’s Nomenclature of Colours by Nicholas Rougeux.

Install & usage

With npm:

$ npm install named-web-colors

It's built using the UMD pattern, only one function is exported and it can be used as follows:

// as ES2015 module
import getColorName from 'named-web-colors'

// as CommonJS module
const getColorName = require('../lib/named-web-colors.js')

// in the browser
<script src="../lib/named-web-colors.js"></script>
<script>console.log(getColorName('#fff'))</script>

Examples

import getColorName from 'named-web-colors'

getColorName('#0D1117').name, // 'Bunker'
getColorName('#0D1117').distance // 0, it's an exact match
getColorName('#0D1117').css // '--color-bunker: #0D1117'   

// small variation which also matches the "Bunker" color
getColorName('#0D1118').name // 'Bunker' 

// color with alpha channel
getColorName('#FFFFB440').name // 'Portafino'
getColorName('#FFFFB440').css // '--color-portafino-25: #FFFFB440'
getColorName('#FFFFB440').rgb, // 'rgba(255, 255, 180, 0.25)'

// alpha channel ignored option
const options = { ignoreAlphaChannel: true }
getColorName('#FFFFB440', options).name // 'Apricot White'
getColorName('#FFFFB440', options).css // '--color-apricot-white: #FFFEEC'

// "list" option
const options = { list: 'werner' }
getColorName('#004162FF', options).name // 'Prussian Blue'
getColorName('#004162FF', options).name // '--color-prussian-blue: #004162'

Options

First param is always the Hex code of the color you want to resolve (it also supports RGB and HSL color definitions). Second param is an options object with the following properties:

  • ignoreAlphaChannel - If true, it will ignore the alpha channel, blending the input color with black and white to get the nearest "solid" color.
  • list - It narrows down the output, instead of looking for matches within all the curated colors, it limits the search to CSS 4 spec named colors (options.list = 'web') or to a list containing the Werner's Nomenclature of Colours (options.list = 'werner').

Output object type definition

key value type
name Color name String
distance Calculated distance between the input and the closest color matched.
A value of 0 is an exact match.
Number
hex Hex color code String
css A CSS custom property alike definition, examples:
Solid color: --color-prussian-blue: #004162
Color with alpha channel: --color-prussian-blue-50: #00416280
String
rgb RGB definition (or RGBA if input contains alpha channel) String

Refs

Similar packages:

About

Javascript utility to translate Hex color codes into human-friendly color names.

License:MIT License


Languages

Language:JavaScript 99.5%Language:HTML 0.5%