JavaScripting

The definitive source of the best
JavaScript libraries, frameworks, and plugins.


  • ×

    ac-colors is a reactive JavaScript color library that can freely convert between RGB, HSL, HEX, XYZ, LAB, LCHab, LUV, and LCHuv, as well as handle random color generation and contrast ratio calculation.
    Filed under  › 

    • 🔾24%Overall
    • 271
    • 14.1 days
    • 🕩11
    • 👥3

    ac-colors

    NPM

    package release version badge minified size badge travis ci status badge Coveralls coverage badge dependency status badge mit license badge

    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

    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:

    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.

    Show All