ac-colors

ac-colors is a reactive JavaScript color library that can freely convert between sRGB, HSL, HEX, XYZ, LAB, LCHab, LUV, and LCHuv, as well as handle random color generation and contrast ratio calculation. A live color picker running on ac-colors can be found at http://colors.acutecomponents.com/.

• Installation
  • Node.js
  • Browser
• Making a Color object
  • color
  • type
  • precision
  • capitalize
  • Color object reactivity
• Color class API
  • Object properties
    • rgb
    • rgbString
    • hex
    • hexString
    • hsl
    • hslString
    • xyz
    • xyzString
    • lab
    • labString
    • lchab
    • lchabString
    • luv
    • luvString
    • lchuv
    • lchuvString
    • precision
    • capitalize
  • Static methods
    • Color.rgbToHsl
    • Color.hslToRgb
    • Color.rgbToHex
    • Color.hexToRgb
    • Color.rgbToXyz
    • Color.xyzToRgb
    • Color.xyzToLab
    • Color.labToXyz
    • Color.labToLCHab
    • Color.lchABToLab
    • Color.xyzToLuv
    • Color.luvToXyz
    • Color.luvToLCHuv
    • Color.lchUVToLuv
    • Color.luminance
    • Color.random
    • Color.randomFromString
    • Color.randomOfType
    • Color.randomOfTypeFormatted
    • Color.contrastTextColor
    • Color.contrastRatio
    • Color.blend
• Acknowledgements
• License

Installation

Node.js

npm install --save ac-colors

Browser

Download

Download the minified transpiled ac-colors.min.js and include it in a <script> tag

<script src="ac-colors.min.js"></script>

CDN

Alternatively add this <script> tag to your body to load the minified version from a CDN.

<script src="https://cdn.jsdelivr.net/npm/ac-colors@1/dist/ac-colors.min.js"></script>

Making a Color object

The easiest way to get started with color conversion in ac-colors is by creating a Color object. The constructor takes an object with up to four deconstructed properties which help determine how to convert and format color output:

• color: An array (or string if type is hex) containing the three numbers for the color (ex. [r,g,b]). Defaults to [0,0,0].
• type: The format for the color being inputted. A full list of types can be found below. Defaults to "rgb".
• precision: The number of decimals to be outputted from the string output methods. Defaults to 3.
• capitalize: A boolean flag for whether or not to capitalize the string output. Defaults to true.

// Node.js users will need to import the module
const Color = require("ac-colors");
let black = new Color();
console.log(black.hex); // #000000

color

The color property is usually a three element array containing the three RGB, HSL, LAB, XYZ, LUV, LCHuv, or LCHab digits, but can also be a string containing a 3 or 6 digit hexcode. The default color, [0,0,0,] evaluates to black when used with the default type of "rgb".

let red = new Color({"color":[255,0,0]});
console.log(red.rgbString); // RGB(255, 0, 0)

Hex colors can be specified with 3 or six digits and with or without the leading '#'.

let grey = new Color({"color":"#333","type":"hex"});
console.log(grey.hsl); // [0, 0, 20]

type

The type property is a string with the following possible values:

• "rgb" (Default)
• "hex"
• "hsl"
• "xyz"
• "lab"
• "lchab"
• "luv"
• "lchuv"

The type merely specifies the format of the incoming color. Once the type is specified, all of the below properties will be set.

let blue = new Color({"color":"#0000FF","type":"hex"});
console.log(blue.rgb); // [0,0,255]

precision

The precision property specifies how many decimal places to return in the string format of the color in representations where decimals are allowed, and defaults to 3 places.

let green = new Color({"color":"#00FF00","type":"hex", "precision":1});
// The hslString property allows for decimal values
console.log(green.hslString); // HSL(120.0, 100.0, 50.0)
// The rgbString property does not
console.log(green.rgbString); // RGB(0, 255, 0)

capitalize

The capitalize property specifies whether or not to capitalize the string of the returned by the output functions.

// capitalize: true
let yellowCaps = new Color({"color":[53.418,96.735,48.039],"type":"hsl", "precision":1, "capitalize":true});
// capitalize: false
let yellowNoCaps = new Color({"color":[53.418,96.735,48.039],"type":"hsl", "precision":1, "capitalize":false});

console.log(yellowCaps.hexString); // #F1D704
console.log(yellowNoCaps.hexString); // #f1d704

Color object reactivity

Each Color object has six reactive color members and two reactive formatting members, precision and capitalize. This means that setting the value of any of the properties will automatically trigger updates of all the other values, so conversion between all the possible types is done simultaneously.

const green = new Color({"color":"#00FF00","type":"hex"});
console.log(green.rgbString); // RGB(0, 255, 0)
green.rgb = [255,0,0]
console.log(green.hslString); // HSL(0.000, 100.000, 50.000)
green.capitalize = false;
console.log(green.hexString); // #ff0000
green.lab = [32.297, 79.194, -107.859];
green.precision = 5;
console.log(green.lchabString); // lchAB(32.29701, 133.81132, 306.28752)

Color class API

The color object contains two main sets of data members which can be used for color conversion. There are the reactive properties which can be accessed from each Color instance, but there are also static methods which can be used for general color conversion without creating a Color object.

Object properties

There are 14 primary instance properties, as well as two formatting properties (precision and capitalize) in each Color object that can be used for color conversion. The 14 main conversion properties can be divided into two categories: Reactive members and their complementary formatted string outputs. | Reactive members | Formatted string outputs | |:--:|:--:| | rgb | rgbString | | hex | hexString | | hsl | hslString | | xyz | xyzString | | lab | labString | | lchab | lchabString | | luv | luvString | | lchuv | lchuvString |

rgb

The rgb property is a reactive getter and setter for the three element array representing the colors [r,g,b] values.

let black = new Color();
console.log(black.rgb); // [0,0,0]
black.rgb = [255,255,255];
console.log(black.hex); // #ffffff

rgbString

The rgbString property is a formatted string output for the rgb color. It is not impacted by the Color object's precision, but is affected by its capitalize value.

let black = new Color();
console.log(black.rgbString); // RGB(0, 0, 0)
black.capitalize = false;
console.log(black.rgbString); // rgb(0, 0, 0)

hex

The hex property is a reactive getter and setter for the string representing the colors three or six digit hex code.

let black = new Color();
console.log(black.hex); // #000000
black.hex = "#FFF";
console.log(black.rgbString); // RGB(255, 255, 255)

hexString

The hexString property is a formatted string output for the hex color. It is not impacted by the Color object's precision, but is affected by its capitalize value.

let white = new Color({"color":[255,255,255]});
console.log(white.hexString) // #FFFFFF
white.capitalize = false;
console.log(white.hexString) // #ffffff

hsl

The hsl property is a reactive getter and setter for the three element array representing the colors [h,s,l] values.

let black = new Color();
console.log(black.hsl); // [0,0,0]
black.hsl = [240,20.863,27.255];
console.log(black.rgbString); // RGB(55, 55, 84)

hslString

The hslString property is a formatted string output for the hsl color. It is impacted by the Color object's precision and capitalize values.

let white = new Color({"color":[255,255,255]});
console.log(white.hslString) // HSL(0.000, 0.000, 100.000)
white.capitalize = false;
console.log(white.hslString) // hsl(0.000, 0.000, 100.000)

xyz

The xyz property is a reactive getter and setter for the three element array representing the colors [x,y,z] values.

let black = new Color();
console.log(black.xyz); // [0,0,0]
black.xyz = [4.542,4.185,8.954];
console.log(black.rgbString); // RGB(55, 55, 84)

xyzString

The xyzString property is a formatted string output for the xyz color. It is impacted by the Color object's precision and capitalize values.

let white = new Color({"color":[255,255,255]});
console.log(white.xyzString) // XYZ(95.047, 100.000, 100.000)
white.capitalize = false;
console.log(white.xyzString) // xyz(95.047, 100.000, 100.000)

lab

The lab property is a reactive getter and setter for the three element array representing the colors [l,a,b] values.

let black = new Color();
console.log(black.lab); // [0,0,0]
black.lab = [24.272,7.853,-17.538];
console.log(black.rgbString); // RGB(55, 55, 84)

labString

The labString property is a formatted string output for the lab color. It is impacted by the Color object's precision and capitalize values.

let white = new Color({"color":[255,255,255]});
console.log(white.labString) // LAB(100.000, 0.000, 0.000)
white.capitalize = false;
console.log(white.labString) // lab(100.000, 0.000, 0.000)

lchab

The lchab property is a reactive getter and setter for the three element array representing the colors [l,c,h] values.

let black = new Color();
console.log(black.lchab); // [0,0,0]
black.lchab = [24.272,7.853,294.121];
console.log(black.rgbString); // RGB(55, 55, 84)

lchabString

The lchabString property is a formatted string output for the lab color. It is impacted by the Color object's precision and capitalize values. However, the capitalization is inverted for the subscripted 'ab'.

let white = new Color({"color":[255,255,255]});
console.log(white.lchabString) // LCHab(100.000, 0.000,0.000)
white.capitalize = false;
console.log(white.lchabString) // lchAB(100.000, 0.000,0.000)

luv

The luv property is a reactive getter and setter for the three element array representing the colors [l,u,v] values.

let black = new Color();
console.log(black.luv); // [0,0,0]
black.luv = [24.272,7.853,-17.538];
console.log(black.rgbString); // RGB(70, 51, 78)

luvString

The luvString property is a formatted string output for the lab color. It is impacted by the Color object's precision and capitalize values.

let white = new Color({"color":[255,255,255]});
console.log(white.luvString) // LUV(100.000, 0.000, 0.000)
white.capitalize = false;
console.log(white.luvString) // luv(100.000, 0.000, 0.000)

lchuv

The lchuv property is a reactive getter and setter for the three element array representing the colors [l,c,h] values.

let black = new Color();
console.log(black.lchuv); // [0,0,0]
black.lchuv = [24.272,7.853,294.121];
console.log(black.rgbString); // RGB(63, 55, 66)

lchuvString

The lchuvString property is a formatted string output for the lab color. It is impacted by the Color object's precision and capitalize values. However, the capitalization is inverted for the subscripted 'uv'.

let white = new Color({"color":[255,255,255]});
console.log(white.lchuvString) // LCHuv(100.000, 0.000,0.000)
white.capitalize = false;
console.log(white.lchuvString) // lchUV(100.000, 0.000,0.000)

precision

The precision property is a reactive formatting property that controls the number of decimal places outputted from a formatted string property. It is set during object initialization, but can be updated at any time.

let white = new Color({"color":[255,255,255],"precision":3});
console.log(white.lchabString) // LCHab(100.000, 0.000,0.000)
white.precision = 1;
console.log(white.lchabString) // LCHab(100.0, 0.0,0.0))

capitalize

The capitalize property is a reactive formatting property that controls the capitalization of a formatted string property. It is set during object initialization, but can be updated at any time.

let white = new Color({"color":[255,255,255], "capitalize":false});
console.log(white.lchabString) // lchAB(100.000, 0.000,0.000)
white.capitalize = true;
console.log(white.lchabString) // LCHab(100.000, 0.000,0.000)

Static Methods

Although it is easier to handle color conversion by creating Color objects and making use of the automatic type conversion, ac-colors supports manual color conversion using the underlying static methods. In addition, static methods are provided for handling random color generation and color contrast ratio checking.

Color.rgbToHsl

This method takes in a three element array [r,g,b] representing a color's rgb values, and returns a three element array [h,s,l] representing the color's hsl values

// Color.rgbToHex(hex)
console.log(Color.rgbToHsl([85,46,58])); // [341.53846153846155,29.770992366412212,25.68627450980392]

Color.hslToRgb

This method takes in a three element array [h,s,l] representing a color's hsl values, and returns a three element array [r,g,b] representing the color's rgb values

// Color.hslToRgb(hsl)
console.log(Color.hslToRgb([341.538,29.771,25.686])); // [85,46,58]

Color.rgbToHex

This method takes in a three element array [r,g,b] representing a color's rgb values, and returns a string representing the color's hex code.

// Color.rgbToHex(rgb)
console.log(Color.rgbToHex([85,46,58])); // #552e3a

Color.hexToRgb

This method takes in a three or six digit hexcode and returns a three element array [r,g,b] representing a color's rgb values.

// Color.hexToRgb(hex)
console.log(Color.hexToRgb("#552e3a")); // [85,46,58]

Color.rgbToXyz

This method takes in a three element array [r,g,b] representing a color's rgb values, and returns a three element array [x,y,z] representing the color's xyz values

// Color.rgbToXyz(rgb)
console.log(Color.rgbToXyz([85,46,58])); // [5.487028215922665, 4.19077333446813, 4.522689110429709]

Color.xyzToRgb

This method takes in a three element array [x,y,z] representing the color's xyz values and returns a three element array [r,g,b] representing a color's rgb values.

// Color.xyzToRgb(xyz)
console.log(Color.xyzToRgb([5.487,4.191,4.522])); // [85,46,58]

Color.xyzToLab

This method takes in a three element array [x,y,z] representing the color's xyz values and returns a three element array [l,a,b] representing a color's lab values.

// Color.xyzToLab(xyz)
console.log(Color.xyzToLab([5.487,4.191,4.522])); // [24.293087120125165, 19.563162207233198, 0.21375272337743612]

Color.labToXyz

This method takes in a three element array [l,a,b] representing a color's lab values. and returns a three element array [x,y,z] representing the color's xyz values.

// Color.labToXyz(lab)
console.log(Color.labToXyz([24.294,19.570,0.211])); // [5.487917707204406, 4.191284860245909, 4.522847553083241]

Color.labToLCHab

This method takes in a three element array [l,a,b] representing a color's lab values. and returns a three element array [l,c,h] representing the color's LCHab values.

// Color.labToLCHab(lab)
console.log(Color.labToLCHab([24.294,19.570,0.211])); // [24.294, 19.57113744778264, 0.617728209288702]

Color.lchABToLab

This method takes in a three element array [l,c,h] representing a color's LCHab values. and returns a three element array [l,a,b] representing the color's lab values.

// Color.lchABToLab(lchAB)
console.log(Color.lchABToLab([24.294,19.571,0.617])); // [24.294, 19.56986524034229, 0.21074979203493507]

Color.xyzToLuv

This method takes in a three element array [x,y,z] representing the color's xyz values and returns a three element array [l,u,v] representing a color's luv values.

// Color.xyzToLuv(xyz)
console.log(Color.xyzToLuv([5.487,4.191,4.522])); // [24.293087120125165, 22.133854138128648, -2.4869700034790783]

Color.luvToXyz

This method takes in a three element array [l,u,v] representing a color's luv values. and returns a three element array [x,y,z] representing the color's xyz values.

// Color.luvToXyz(luv)
console.log(Color.luvToXyz([24.294,22.134,-2.487])); //  [5.487326075294226, 4.191284860245909, 4.522311066039963]

Color.luvToLCHuv

This method takes in a three element array [l,u,v] representing a color's lab values. and returns a three element array [l,c,h] representing the color's LCHuv values.

// Color.luvToLCHuv(luv)
console.log(Color.luvToLCHuv([24.294,22.134,-2.487])); // [24.294, 22.27328276208965, 353.5890738118895]

Color.lchUVToLuv

This method takes in a three element array [l,c,h] representing a color's LCHuv values. and returns a three element array [l,u,v] representing the color's luv values.

// Color.lchUVToLuv(lchUV)
console.log(Color.lchUVToLuv([24.294,22.273,353.589])); // [24.294, 22.133715802240754, -2.48699694122008]

Color.luminance

This method takes in a three element array and a string representing its type and returns its relative luminance. Default type is "rgb".

// Color.luminance(color,type)
console.log(Color.luminance([0,255,0])); // 0.7152
console.log(Color.luminance("#ff0000","hex")); // 0.2126

Color.random

This method returns a new Color instance with a random color selected.

// Color.random()
console.log(Color.random()); // Color {_rgb: Array(3), _hsl: Array(3), _hex: "#b3eeb6", _xyz: Array(3), _lab: Array(3), …}
console.log(Color.random()); // Color {_rgb: Array(3), _hsl: Array(3), _hex: "#85dd60", _xyz: Array(3), _lab: Array(3), …}

Color.randomFromString

This method returns a new Color instance with a deterministic random color derived from the given string. The string is hashed under the PJW-32 hash to achieve pseudorandom distribution of colors.

// Color.randomFromString(str)
console.log(Color.randomFromString("Hello World!")); // Color {_xyz: Array(3), _rgb: Array(3), _hsl: Array(3), _hex: "#712199", _lab: Array(3), …}
console.log(Color.randomFromString("Hello World!")); // Color {_xyz: Array(3), _rgb: Array(3), _hsl: Array(3), _hex: "#712199", _lab: Array(3), …}
console.log(Color.randomFromString("Foo Bar")); // Color {_xyz: Array(3), _rgb: Array(3), _hsl: Array(3), _hex: "#b20092", _lab: Array(3), …}

Color.randomOfType

This method takes in a type and returns a new three element array of the type selected, or six digit hex code if type is "hex". Default type is "rgb".

// Color.randomOfType(type)
console.log(Color.randomOfType()); // [24, 60, 77]
console.log(Color.randomOfType("hex")); // #4c4f92

Color.randomOfTypeFormatted

This method takes in a type, a capitalize flag, and a precision and returns a formatted string for the type specified. The capitalize flag determines whether or not the returned string will capitalized, and defaults to true. The precision flag determines how many decimal places to round the values returned, if applicable, and defaults to 3. Default type is "rgb".

// Color.randomOfTypeFormatted(type,capitalize,precision)
console.log(Color.randomOfTypeFormatted()); // RGB(237, 216, 88)
console.log(Color.randomOfTypeFormatted("hex")); // #FD3741
console.log(Color.randomOfTypeFormatted("rgb",false)); // rgb(120, 156, 72)
console.log(Color.randomOfTypeFormatted("hsl",true,1)); // HSL(296.9, 90.6, 79.2)

Color.contrastTextColor

This method takes in a three element array or string representing a color, and the type of the color, and return #FFFFFF or #000000 depending on which one has a higher contrast ratio with the color provided.

// Color.contrastTextColor(color,type)
console.log(Color.contrastTextColor([10,20,30])); // #FFFFFF
console.log(Color.contrastTextColor("#e8e9ea","hex")); // #000000

Color.contrastRatio

This method takes in two Color instances and returns the contrast ratio between the two.

// Color.contrastRatio(color1,color2)
const red = new Color({"color":"#ff0000","type":"hex"});
const white = new Color({"color":[255,255,255]})
console.log(Color.contrastRatio(red,white)); // 3.9984767707539985

Color.blend

This method takes in two Color instances and return their weighted average within a given colorspace. Default type is "rgb". Default weight is 0.5.

// Color.blend(color1, color2, type, weight)
const red = new Color({"color":"#ff0000","type":"hex"});
const white = new Color({"color":[255,255,255]})
console.log(Color.blend(red,white)); // Color {_xyz: Array(3), _rgb: Array(3), _hsl: Array(3), _hex: "#ff8080", _lab: Array(3), …}
console.log(Color.blend(red,white,'hsl')); // Color {_xyz: Array(3), _rgb: Array(3), _hsl: Array(3), _hex: "#df9f9f", _lab: Array(3), …}
console.log(Color.blend(red,white,'hex',0.75)); // Color {_xyz: Array(3), _rgb: Array(3), _hsl: Array(3), _hex: "#ff4040", _lab: Array(3), …}

Acknowledgements

Thanks to Jonas Jacek, ColorMine.org, and EasyRGB for providing some of the sample data used for testing the color conversion. Additional resources for implementing color space transformations, including the ones used in this library, are listed below:

• http://www.color.org/iccmax/profiles/sRGB_D65_colorimetric.icc
• https://graphics.stanford.edu/courses/cs148-10-summer/docs/2010--kerr--cie_xyz.pdf
• http://www.color.org/sRGB.pdf
• https://www.sis.se/api/document/preview/562720/
• http://coecsl.ece.illinois.edu/ge423/spring05/group8/finalproject/hsv_writeup.pdf
• https://www.cs.rit.edu/~ncs/color/t_convert.html#XYZ%20to%20CIELUV%20&%20CIELUV%20to%20XYZ
• http://docs-hoffmann.de/cielab03022003.pdf
• http://faculty.washington.edu/jokelly/gammaFaq1.htm
• http://www.brucelindbloom.com/index.html
• http://cs.haifa.ac.il/hagit/courses/ist/Lectures/Demos/ColorApplet/me/infoluv.html
• https://engineering.purdue.edu/~bouman/ece637/notes/pdf/ColorSpaces.pdf

License

Copyright 2020 Vinay Pillai

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.