A JavaScript library, written in TypeScript, to convert among different color models

Demo

https://elchininet.github.io/ColorTranslator/

Installation

Using NPM

1npm install colortranslator

Using PNPM

1pnpm add colortranslator

Using Yarn

1yarn add colortranslator

In the browser

It is possible to include a compiled version of the package directly in an HTML file. It will create a global colortranslator object containing all the exported modules that can be accessed from anywhere in your JavaScript code.

1. Copy the JavaScript file colortranslator.js, located in the dist/web/ folder
2. Put it in the folder that you prefer in your web server
3. Include it in your HTML file

1<script src="wherever/you/installed/colortranslator.js"></script>

1/* There will be a global variable named colortranslator containing all the modules */
2colortranslator.ColorTranslator;
3colortranslator.Harmony;
4colortranslator.Mix;

Importing using CommonJS

1const { ColorTranslator, Harmony, Mix } = require('colortranslator');

Importing using ES6 modules

1import { ColorTranslator, Harmony, Mix } from 'colortranslator';

Scripts

build

npm run build

Transpiles the TypeScript code and creates three bundles in the dist folder (index.js for commonjs, esm/index.js for ESM, and web/colortranslator.js to use directly in the browser).

test

npm run test

Runs multiple dynamic tests converting from / to all the color models available (excepting CMYK) using a table of colors.

lint

npm run lint

Runs eslint in source files.

demo

npm run demo

Opens a development server that provides live reloading using webpack-dev-server. Some demo examples located in the @demo folder will be shown. You can modify the code of the demos and the changes will be live reloaded in the browser.

API

Notes:

• The conversion to a CMYK color is made taking a random value of black as a base (in this case, taking the greater value from red, green or blue). When a value of black is assumed, the rest of the colors can be calculated from it. The result will be visually similar to the original light color, but if you try to convert it back you will not obtain the same original value.
• The conversion to a CIE L*a*b or LCH colors may introduce a small amount of rounding error, as far as you maintain enough decimals for the calculation it should not be noticeable, but you can expect that the values change some of their decimals during the conversions.

Input

The most wonderful thing about colortranslator is that you don‘t need to specify the input that you are using, the library will recognise it automatically. The input can be a CSS string or an object:

CSS string inputs

Example of CSS string inputs	Description
fuchsia	Color keyword
#FF00FF	Hexadecimal color
#F0F	Shorthand hexadecimal color
#FF00FF80	Hexadecimal color with alpha
#F0FF	Shorthand hexadecimal color with alpha
rgb(255 0 255)	Functional RGB notation
rgb(100% 0% 100%)	Functional RGB notation with values in percentages
rgb(255 0 255 / 0.5)	Functional RGB notation with alpha
rgb(255 0 255 / 50%)	Functional RGB notation CSS with alpha in percenatages
rgb(100% 0% 100% / 0.5)	Functional RGB notation with values in percentages and alpha
rgb(100% 0% 100% / 50%)	Functional RGB notation with values and alpha in percentages
rgb(255, 0, 255)	Functional RGB legacy notation
rgba(255, 0, 255, 0.5)	Functional RGB legacy notation with alpha
rgb(from #F00 r g b)	Functional RGB notation in relative color syntax
rgb(from hsl(0 100% 50%) calc(r + 5) g b / calc(alpha / 2))	Functional RGB notation in relative color syntax with alpha
hsl(300 100% 50%)	Functional HSL notation
hsl(300 100 50)	Functional HSL notation without percentages
hsl(300deg 100% 50%)	Functional HSL notation with hue in degrees
hsl(270grad 100% 50%)	Functional HSL notation with hue in gradians
hsl(5.24rad 100% 50%)	Functional HSL notation with hue in radians
hsl(0.83turn 100% 50%)	Functional HSL notation with hue in turns
hsl(300 100% 50% / 0.5)	Functional HSL notation with alpha
hsl(300 100% 50% / 50%)	Functional HSL notation with alpha in percentages
hsl(300, 100%, 50%)	Functional HSL legacy notation
hsl(300deg, 100%, 50%)	Functional HSL legacy notation with hue in degrees
hsl(270grad, 100%, 50%)	Functional HSL legacy notation with hue in gradians
hsl(5.24rad, 100%, 50%)	Functional HSL legacy notation with hue in radians
hsl(0.83turn, 100%, 50%)	Functional HSL legacy notation with hue in turns
hsla(300, 100%, 50%, 0.5)	Functional HSL legacy notation with alpha
hsl(from hsl(0 100 50) h s l)	Functional HSL notation in relative color syntax
hsl(from hsl(0 100 50) calc(h + 5) s l / calc(alpha / 2))	Functional HSL notation in relative color syntax with alpha
hwb(0 0% 0%)	Functional HWB notation
hwb(0 0% 0% / 0.5)	Functional HWB notation with alpha
hwb(0deg 0% 0%)	Functional HWB notation with hue in degrees
hwb(0grad 0% 0%)	Functional HWB notation with hue in gradians
hwb(0rad 0% 0%)	Functional HWB notation with hue in radians
hwb(0turn 0% 0%)	Functional HWB notation with hue in turns
hwb(from hwb(0 0% 0%) h w b)	Functional HWB notation in relative color syntax
hwb(from hwb(0 0% 0%) calc(h + 2) w b / calc(alpha / 2))	Functional HWB notation in relative color syntax with alpha
lab(54 81 70)	Functional LAB notation without percentages
lab(54 81 70 / 1)	Functional LAB notation without percentages and alpha
lab(54% 65% 56%)	Functional LAB notation with percentages
lab(54% 65% 56% / 1)	Functional LAB notation with percentages and alpha
lab(54 81 70 / 93%)	Functional LAB notation without percentages and alpha in percentages
lab(54% 65% 56% / 93%)	Functional LAB notation with alpha parcentages
lab(54% 65% 56% / 93%)	Functional LAB notation with alpha parcentages
lab(from #F00 l a b)	Functional LAB notation in relative color syntax
lab(from #F00 calc(l + 5) a b / calc(alpha / 2))	Functional LAB notation in relative color syntax with alpha
lch(54 107 41)	Functional LCH notation
lch(54% 71% 41)	Functional LCH notation with percentages
lch(54 107 41 / 0.5)	Functional LCH notation with alpha
lch(54% 71% 41 / 0.5)	Functional LCH notation with percentages and alpha
lch(54 107 41deg)	Functional LCH notation with hue in degrees
lch(54 107 46grad)	Functional LCH notation with hue in gradians
lch(54 107 1rad)	Functional LCH notation with hue in radians
lch(54 107 0turn)	Functional LCH notation with hue in turns
lch(from lch(54 107 41) l c h)	Functional LCH notation in relative color syntax
lch(from lch(54 107 41) calc(l + 2) c h / calc(alpha / 2))	Functional LCH notation in relative color syntax and alpha
device-cmyk(0% 100% 100% 0%)	Device-dependent functional CMYK notation with percentages
device-cmyk(0% 100% 100% 0% / 1)	Device-dependent functional CMYK notation with percentages and alpha
device-cmyk(0% 100% 100% 0% / 100%)	Device-dependent functional CMYK notation with percentages and alpha in percentages
device-cmyk(0%, 100%, 100%, 0%)	Device-dependent functional CMYK legacy notation with percentages
device-cmyk(0%, 100%, 100%, 0%, 1)	Device-dependent functional CMYK legacy notation with percentages and alpha
device-cmyk(0 1 1 0)	Device-dependent functional CMYK notation without percentages
device-cmyk(0 1 1 0 / 1)	Device-dependent functional CMYK notation without percentages and alpha
device-cmyk(0 1 1 0 / 100%)	Device-dependent functional CMYK notation without percentages and alpha in percentages
device-cmyk(0, 1, 1, 0)	Device-dependent functional CMYK legacy notation without percentages
device-cmyk(0, 1, 1, 0, 1)	Device-dependent functional CMYK legacy notation without percentages and alpha
cmyk(0% 100% 100% 0%)	Functional CMYK notation with percentages
cmyk(0% 100% 100% 0% / 1)	Functional CMYK notation with percentages and alpha
cmyk(0% 100% 100% 0% / 100%)	Functional CMYK notation with percentages and alpha in percentages
cmyk(0 1 1 0)	Functional CMYK notation without percentages
cmyk(0 1 1 0 / 1)	Functional CMYK notation without percentages and alpha
cmyk(0 1 1 0 / 100%)	Functional CMYK notation without percentages and alpha in percentages
cmyk(0%, 100%, 100%, 0%)	Functional CMYK legacy notation with percentages
cmyk(0%, 100%, 100%, 0%, 1)	Functional CMYK legacy notation with percentages and alpha
cmyk(0, 1, 1, 0)	Functional CMYK legacy notation without percentages
cmyk(0, 1, 1, 0, 1)	Functional CMYK legacy notation without percentages and alpha

Object inputs

Example of object inputs	Description
{R: "0xFF", G: "0x00", B: "0xFF"}	Hexadecimal color
{R: "0xF", G: "0x0", B: "0xF"}	Shorthand hexadecimal color
{R: "0xFF", G: "0x00", B: "0xFF", A: "0x80"}	Hexadecimal color with alpha
{R: "0xF", G: "0x0", B: "0xF", A: "0xF"}	Shorthand hexadecimal color with alpha
{R: 255, G: 0, B: 255}	RGB notation
{R: 255, G: 0, B: 255, A: 0.5}	RGB notation with alpha
{R: 255, G: 0, B: 255, A: 0.5}	RGB notation with alpha
{H: 300, S: "100%", L: "50%"}	HSL notation using percentages
{H: 300, S: 100, L: 50}	HSL notation using numbers
{H: 300, S: "100%", L: "50%", A: 0.5}	HSL notation with alpha using percentages
{H: 300, S: 100, L: 50, A: 0.5}	HSL notation with alpha using numbers
{H: 0, W: 0, B: 0}	HWB notation
{H: 0, W: 0, B: 0, A: 0.5}	HWB notation with alpha
{L: 54, a: 81, b: 70}	LAB notation using numbers
{L: 54, a: 81, b: 70, A: 1}	LAB notation using numbers with alpha
{L: '54%', a: '65%', b: '56%'}	LAB notation using percentages
{L: '54%', a: '65%', b: '56%', A: '100%'}	LAB notation using percentages with alpha
{L: 54, C: 107, H: 41}	LCH notation
{L: 54, C: 107, H: 41, A: 0.5}	LCH notation with alpha
{C: "0%", M: "100%", Y: "100%", K: "0%"}	CMYK notation using percentages
{C: 0, M: 1, Y: 1, K: 0}	CMYK notation using numbers

Class instantiation

1ColorTranslator(color: ColorInput, options?: Options)

It is possible to instantiate the class using any of the previous inputs.

Options object

1interface Options {
2  decimals?: number;  // defaults to 6
3  legacyCSS?: boolean; // defaults to false 
4  spacesAfterCommas?: boolean; // defaults to false
5  anglesUnit?: 'none' | 'deg' | 'grad' | 'rad' | 'turn'; // defaults to 'none'
6  rgbUnit?: 'none' | 'percent'; // defaults to 'none'
7  labUnit?: 'none' | 'percent'; // defaults to 'none'
8  lchUnit?: 'none' | 'percent'; // defaults to 'none'
9  cmykUnit?: 'none' | 'percent'; // defaults to 'percent'
10  alphaUnit?: 'none' | 'percent'; // defaults to 'none'
11  cmykFunction?: 'device-cmyk' | 'cmyk'; // defaults to 'device-cmyk'
12}

Option	Only for CSS output	Description
decimals	no	This option sets what is the maximum number of decimals for the outputs
legacyCSS	yes	This option decides if the CSS output should be CSS Level 3 (legacy) or CSS Level 4
spacesAfterCommas	yes	This option only takes place if legacyCSS is set to true. It decides if the comas should have a space after
anglesUnit	yes	This option only takes place if the output is an HSL CSS output. It sets the degrees units of the HSL hue angle. If none is used, the output will not have any unit but its value will be the deg one (degrees)
rgbUnit	yes	This option only takes place if the output is an RGB CSS output. It sets the color units of the RGB and RGBA CSS outputs. If none is used the color values will be decimal between 0 and 255. If percent is used, the color values will be decimal with percentages between 0% and 100%.
labUnit	yes	This option only takes place if the output is a CIE L*a*b CSS output. It sets the color units of the CIELab and CIELabA CSS outputs. If none is used it will be a decimal number between 0 and 100 for the CIE Lightness and a decimal number between -125 and 125 for the a and b axis of the CIE L*a*b colorspace. If percent is used, it will be a decimal number between 0 and 100 with percentages for all the color values.
lchUnit	yes	This option only takes place if the output is a LCH CSS output. It sets the color units of the LCH and LCHA CSS outputs. If none is used it will be a decimal number between 0 and 100 for the lightness, between 0 and 150 for the chroma, and between 0 and 360 for the hue. If percent is used, it will be a decimal number between 0 and 100 for the lightness and the chrome and between 0 and 360 for the hue.
cmykUnit	yes	This option sets the color units of the CMYK and CMYKA CSS outputs. If none is used the color values will be decimal between 0 and 1. If percent is used, the color values will be decimal with percentages between 0% and 100%.
alphaUnit	yes	This option only takes place if the output is a CSS Level 4 output (legacyCSS has not been set, or it has been set to false or it has been autodetected as false). This option sets the alpha units of the CSS Level 4 outputs. If none is used the alpha values will be decimal between 0 and 1. If percent is used, the alpha values will be decimal with percentages between 0% and 100%.
cmykFunction	yes	This option sets the cmyk function of the CMYK and CMYKA CSS outputs.

Note: the library tries to detect some options automatically if you don‘t send them in the options object. These are the rules for this autodetection:

• legacyCSS: if this option is set, then its value prevails, if it is not set, and the CSS input is provided in CSS Level 3, then this option will be true, otherwise it will take its default value which is false.
• spacesAfterCommas: if this option is set, then its value prevails, if it is not set, and the CSS input is provided with spaces after the commas, then this option will be true. If the input is not consistent in this aspect, then it will take its default value which is false (This option only takes place if legacyCSS is true or it has been autodetected as true)
• anglesUnit: if this option is set, then its value prevails, if it is not set, and the HSL, HWB or LCH CSS inputs are provided with an angle unit, then it will take that value, otherwise it will use the default one wich is none.
• rgbUnit: if this option is set, then its value prevails, if it is not set, and the RGB CSS input is provided with percentages in its color values, then it will take the percent value, otherwise it will use the default one wich is none.
• labUnit: if this option is set, then its value prevails, if it is not set, and the CIE L*a*b CSS input is provided with percentages in its color values, then it will take the percent value, otherwise it will use the default one wich is none.
• lchUnit: if this option is set, then its value prevails, if it is not set, and the LCH CSS input is provided with percentages in lightness and chroma, then it will take the percent value, otherwise it will use the default one wich is none.
• cmykUnit: if this option is set, then its value prevails, if it is not set, and the CMYK CSS input is provided without percentages in its color values, then it will take the none value, otherwise it will use the default one wich is percent.
• alphaUnit: if this option is set, then its value prevails, if it is not set, and the CSS input (must be CSS Level 4) is provided with percentages in its alpha value, then it will take the percent value, otherwise it will use the default one wich is none.
• cmykFunction: if this option is set, then its value prevails, if it is not set, and the CMYK CSS input is provided using the cmyk function, then it will take the cmyk value, otherwise it will use the default one wich is device-cmyk.

Class instantiation examples

1const keyword = new ColorTranslator('deeppink');
2
3const hex = new ColorTranslator('#FF00FF');
4
5const rgb = new ColorTranslator('rgb(255, 0, 0)');
6
7const hsl = new ColorTranslator('hsl(50 20% 90% / 0.5)');
8
9const lab = new ColorTranslator('lab(54 81 70)');
10
11const lab = new ColorTranslator('hwb(from red h calc(w * 1.25) calc(b * 1.25) / calc(alpha / 2))');
12
13const hsla = new ColorTranslator({ R: 115, G: 200, B: 150, A: 0.5 });
14
15const cmyk = new ColorTranslator({ C: 100, M: 100, Y: 0, K: 0 });

Configuration options examples

1// Decimals
2new ColorTranslator('#F43227').HSL; // hsl(3.219512 90.30837% 55.490196%)
3new ColorTranslator('#F43227', { decimals: 4 }).HSL; // hsl(3.2195 90.3084% 55.4902%)
4new ColorTranslator('#F43227', { decimals: 0 }).HSL; // hsl(3 90% 55%)
5new ColorTranslator('#F43227', { decimals: 2 }).HSLObject; // {H: 3.22, S: 90.31, L: 55.49}
6
7// legacyCSS
8new ColorTranslator('#FFF').RGBA; // rgb(255 255 255 / 1)
9new ColorTranslator('#FFF', { legacyCSS: false }).RGBA; // rgb(255 255 255 / 1)
10new ColorTranslator('#FFF', { legacyCSS: true }).RGBA; // rgba(255,255,255,1)
11new ColorTranslator('hsla(100,30%,20%,0.5)').RGBA; // rgba(45.9,66.3,35.7,0.5)
12new ColorTranslator('hsl(100 30% 20% / 0.5)').RGBA; // rgb(45.9 66.3 35.7 / 0.5)
13
14// spacesAfterCommas
15new ColorTranslator('#F00', { legacyCSS: true }).RGB; // rgb(255,0,0)
16new ColorTranslator('#F00', { legacyCSS: true, spacesAfterCommas: true }).RGB; // rgb(255, 0, 0)
17new ColorTranslator('hsla(100,30%,20%,0.25)').RGB; // rgb(45.9,66.3,35.7)
18new ColorTranslator('hsl(100, 30%, 20%, 0.25)').RGB; // rgb(45.9, 66.3, 35.7)
19
20// anglesUnit
21new ColorTranslator('#0F0').HSL; // hsl(120 100% 50%)
22new ColorTranslator('#0F0', { anglesUnit: 'none' }).HSL; // hsl(120 100% 50%)
23new ColorTranslator('#0F0', { anglesUnit: 'none' }).HWB; // hwb(120 0% 0%)
24new ColorTranslator('#0F0', { anglesUnit: 'none' }).LCH; // lch(87.818128 113.339731 134.391246)
25new ColorTranslator('#0F0', { anglesUnit: 'deg' }).HSL; // hsl(120deg 100% 50%)
26new ColorTranslator('#0F0', { anglesUnit: 'deg' }).HWB; // hwb(120deg 0% 0%)
27new ColorTranslator('#0F0', { anglesUnit: 'deg' }).LCH; // lch(87.818128 113.339731 134.391246deg)
28new ColorTranslator('#0F0', { anglesUnit: 'grad' }).HSL; // hsl(133.333333grad 100% 50%)
29new ColorTranslator('#0F0', { anglesUnit: 'grad' }).HWB; // hwb(133.333333grad 0% 0%)
30new ColorTranslator('#0F0', { anglesUnit: 'grad' }).LCH; // lch(87.818128 113.339731 149.323607grad)
31new ColorTranslator('#0F0', { anglesUnit: 'rad' }).HSL; // hsl(2.094395rad 100% 50%)
32new ColorTranslator('#0F0', { anglesUnit: 'rad' }).HWB; // hwb(2.094395rad 0% 0%)
33new ColorTranslator('#0F0', { anglesUnit: 'rad' }).LCH; // lch(87.818128 113.339731 2.34557rad)
34new ColorTranslator('#0F0', { anglesUnit: 'turn' }).HSL; // hsl(0.333333turn 100% 50%)
35new ColorTranslator('#0F0', { anglesUnit: 'turn' }).HWB; // hwb(0.333333turn 0% 0%)
36new ColorTranslator('#0F0', { anglesUnit: 'turn' }).LCH; // lch(87.818128 113.339731 0.373309turn)
37new ColorTranslator('hsl(0.5turn 100% 50% / 0.5)').HSL; // hsl(0.5turn 100% 50%)
38new ColorTranslator('lch(54 107 41)').HWB; // hwb(0turn 0% 0%)
39new ColorTranslator('lch(54 107 0turn)').LCH; // lch(55.806124 84.221697 0.003517turn)
40
41// rgbUnit
42new ColorTranslator('#0F0').RGB; // rgb(0 255 0)
43new ColorTranslator('#0F0', { rgbUnit: 'none' }).RGB; // rgb(0 255 0)
44new ColorTranslator('#0F0', { rgbUnit: 'percent' }).RGB; // rgb(0% 100% 0%)
45new ColorTranslator('rgb(255 255 51 / 0.5)').RGB; // rgb(255 255 51)
46new ColorTranslator('rgb(20% 100% 0% / 0.5)').RGB; // rgb(20% 100% 0%)
47
48// labUnit
49new ColorTranslator('#0F0').CIELab; // lab(87.818128 -79.287281 80.990256)
50new ColorTranslator('#0F0', { labUnit: 'none' }).CIELab; // lab(87.818128 -79.287281 80.990256)
51new ColorTranslator('#0F0', { labUnit: 'percent' }).CIELab; // lab(87.818128% -63.429825% 64.792205%)
52new ColorTranslator('lab(88 -79 81)').CIELabA; // lab(87.863151 -78.89437 80.892902 / 1)
53new ColorTranslator('lab(54.291734% 64.649964% 55.908032% / 1)').CIELabA; // lab(54.291736% 64.649953% 55.90801% / 1)
54
55// lchUnit
56new ColorTranslator('#0F0').LCH; // lch(87.818128 113.339731 134.391246)
57new ColorTranslator('#0F0', { lchUnit: 'none' }).LCH; // lch(87.818128 113.339731 134.391246)
58new ColorTranslator('#0F0', { lchUnit: 'percent' }).LCH; // lch(87.818128% 75.559821% 134.391246)
59new ColorTranslator('lch(88 113 134)').LCH; // lch(87.919219 112.827026 134.029641)
60new ColorTranslator('lch(88% 75% 134)').LCH; // lch(87.953899% 74.965844% 133.999475)
61
62// cmykUnit
63new ColorTranslator('#0F0').CMYK; // device-cmyk(100% 0% 100% 0%)
64new ColorTranslator('#0F0', { cmykUnit: 'percent' }).CMYK; // device-cmyk(100% 0% 100% 0%)
65new ColorTranslator('#0F0', { cmykUnit: 'none' }).CMYK; // device-cmyk(1 0 1 0)
66
67// alphaUnit
68new ColorTranslator('#0F0').RGBA; // rgb(0 255 0 / 1)
69new ColorTranslator('#0F0', { alphaUnit: 'none' }).RGBA; // rgb(0 255 0 / 1)
70new ColorTranslator('#0F0', { alphaUnit: 'percent' }).HSLA; // hsl(120 100% 50% / 100%)
71new ColorTranslator('hsl(100 50% 20% / 0.25)').RGBA; // rgb(42.5 76.5 25.5 / 0.25)
72new ColorTranslator('rgb(0 0 0 / 50%)').HSLA; // hsl(0 0% 0% / 50%)
73
74// cmykFunction
75new ColorTranslator('#00F').CMYKA; // device-cmyk(100% 100% 0% 0% / 1)
76new ColorTranslator('#00F', { cmykFunction: 'device-cmyk' }).CMYK; // device-cmyk(100% 100% 0% 0%)
77new ColorTranslator('#00F', { cmykFunction: 'cmyk' }).CMYKA; // cmyk(100% 100% 0% 0% / 1)

Class public methods

There are 20 chainable public methods and 19 of them accept a number as input. The last one accepts an options object:

Public methods	Input	Description
setR	0 ≤ input ≤ 255	Sets the red value of the color
setG	0 ≤ input ≤ 255	Sets the green value of the color
setB	0 ≤ input ≤ 255	Sets the blue value of the color
setH	0 ≤ input ≤ 360	Sets the color hue
setS	0 ≤ input ≤ 100	Sets the color saturation percentage
setL	0 ≤ input ≤ 100	Sets the color lightness percentage
setWhiteness	0 ≤ input ≤ 100	Sets the color whiteness percentage
setBlackness	0 ≤ input ≤ 100	Sets the color blackness percentage
setCIEL	0 ≤ input ≤ 100	Sets the CIE Lightness value of the color
setCIEa	-125 ≤ input ≤ 125	Sets the a axis in the CIE L*a*b colorspace
setCIEb	-125 ≤ input ≤ 125	Sets the b axis in the CIE L*a*b colorspace
setLCHL	0 ≤ input ≤ 100	Sets the color lightness percentage
setLCHC	0 ≤ input ≤ 150	Sets the color chroma
setLCHH	0 ≤ input ≤ 360	Sets the lch color hue
setC	0 ≤ input ≤ 100	Sets the CMYK cyan percentage value of the color
setM	0 ≤ input ≤ 100	Sets the CMYK magenta percentage value of the color
setY	0 ≤ input ≤ 100	Sets the CMYK yellow percentage value of the color
setK	0 ≤ input ≤ 100	Sets the CMYK black percentage value of the color
setA	0 ≤ input ≤ 1	Sets the alpha value of the color
setOptions	Options	Sets an object that would work as configuration options

Class public methods examples

You can also consult the demo 1 and the demo 2 to check the use of the public methods.

1const color = new ColorTranslator('#FF00FF');
2
3color
4  .setH(120)
5  .setS(80)
6  .setA(0.5);
7
8color
9  .setR(255)
10  .setG(150)
11  .setA(0.25);

Class public readonly properties

There are 14 properties to get the CSS representation of the color:

Property	Description
HEX	Gets the css hex representation of the color
HEXA	Gets the css hex representation of the color with alpha
RGB	Gets the css rgb representation of the color
RGBA	Gets the css rgb representation of the color with alpha
HSL	Gets the css hsl representation of the color
HSLA	Gets the css hsl representation of the color with alpha
HWB	Gets the css hwb representation of the color
HWBA	Gets the css hwb representation of the color with alpha
CIELab	Gets the css CIE L*a*b representation of the color
CIELabA	Gets the css CIE L*a*b representation of the color with alpha
LCH	Gets the css lch representation of the color
LCHA	Gets the css lch representation of the color with alpha
CMYK	Gets css cmyk representation of the color
CMYKA	Gets css cmyk representation of the color with alpha

There are 14 properties to get the object representation of the color:

Property	Description
HEXObject	Gets the object hex representation of the color
HEXAObject	Gets the object hex representation of the color with alpha
RGBObject	Gets the object rgb representation of the color
RGBAObject	Gets the object rgb representation of the color with alpha
HSLObject	Gets the object hsl representation of the color
HSLAObject	Gets the object hsl representation of the color with alpha
HWBObject	Gets the object HWB representation of the color
HWBAObject	Gets the object HWB representation of the color with alpha
CIELabObject	Gets the object CIE L*a*b representation of the color
CIELabAObject	Gets the object CIE L*a*b representation of the color with alpha
LCHObject	Gets the object lch representation of the color
LCHAObject	Gets the object lch representation of the color with alpha
CMYKObject	Gets the object cmyk representation of the color
CMYKAObject	Gets the object cmyk representation of the color with alpha

There are 19 properties to get the individual color values:

Property	Description
R	Gets the red value of the color
G	Gets the green value of the color
B	Gets the blue value of the color
H	Gets the color hue
S	Gets the color saturation percentage
L	Gets the color lightness percentage
Whiteness	Gets the color whiteness percentage
Blackness	Gets the color blackness percentage
CIEL	Gets the CIE Lightness value of the color
CIEa	Gets the a axis in the CIE L*a*b colorspace of the color
CIEb	Gets the b axis in the CIE L*a*b colorspace of the color
LCHL	Gets the lch color lightness
LCHC	Gets the color chroma
LCHH	Gets the lch color hue
C	Gets the CMYK cyan percentage value of the color
M	Gets the CMYK magenta percentage value of the color
Y	Gets the CMYK yellow percentage value of the color
K	Gets the CMYK black percentage value of the color
A	Gets the alpha value of the color

And a property to get the options object that acts as a configuration object for the outputs

Property	Description
options	Get the configuration object value

Class public properties examples

You can also consult the demo 1 and the demo 2 to check the use of the public properties.

1const color = new ColorTranslator('#FF00FF', { decimals: 2 });
2
3color.R; // 255
4color.G; // 0
5color.B; // 255
6color.RGB; // rgb(255 0 255)
7color.HSLA; // hsl(300 100% 50% / 1)
8color.CIELabObject; // {L: 60.17, a: 93.55, b: -60.5}
9color.options; // { decimals: 2 }

Class static methods

For the static methods, it is not needed to specify the input color model, the API will detect the format automatically. It is only needed to specify to which color model one wants to convert calling the specific static method.

There are 79 static methods available, 28 of them to convert colors, 24 to create color blends, 24 to mix colors, one to get shades, one to get tints, and one to create color harmonies.

Note: The static methods also count with the options-autodetection feature that was explained in the options object section, but in this case it scans all the inputs that are CSS, and it tries to detect the options in each one of them. If one of the autodetected options is consistent in all the inputs, then it takes the autodetected value, otherwise it will use the default one.

Color conversion static methods

The static methods to convert colors accept any of the mentioned inputs as the first parameter, the second parameter is optional and it is an options object (this second option is not present in the methods to generate HEX colors):

1convertColorStaticMethod(
2  color: string | object,
3  options?: Options
4)

Color conversion static methods description

Static method	Description
toHEX	Converts to an hexadecimal notation
toHEXObject	Converts to an object in hexadecimal notation
toHEXA	Converts to an hexadecimal notation with alpha
toHEXAObject	Converts to an object in hexadecimal notation with alpha
toRGB	Converts to an rgb notation
toRGBObject	Converts to an object in rgb notation
toRGBA	Converts to an rgb notation with alpha
toRGBAObject	Converts to an object in rgb notation with alpha
toHSL	Converts to an hsl notation
toHSLObject	Converts to an object in hsl notation
toHSLA	Converts to an hsl notation with alpha
toHSLAObject	Converts to an object in hsl notation with alpha
toHWB	Converts to an hwb notation
toHWBObject	Converts to an object in hwb notation
toHWBA	Converts to an hwb notation with alpha
toHWBAObject	Converts to an object in hwb notation with alpha
toCIELab	Converts to a CIE L*a*b notation
toCIELabObject	Converts to an object in the CIE L*a*b notation
toCIELabA	Converts to a CIE L*a*b notation with alpha
toCIELabAObject	Converts to an object in the CIE L*a*b notation with alpha
toLCH	Converts to a lch notation
toLCHObject	Converts to an object in lch notation
toLCHA	Converts to a lch notation with alpha
toLCHAObject	Converts to an object in lch notation with alpha
toCMYK	Converts to a CMYK notation
toCMYKA	Converts to a CMYK notation with alpha
toCMYKObject	Converts to an object in CMYK notation
toCMYKAObject	Converts to an object in CMYK notation with alpha

Color conversion static methods examples

1ColorTranslator.toHEX('gold'); // #FFD700
2
3ColorTranslator.toRGB('#FF00FF'); // rgb(255 0 255)
4
5ColorTranslator.toRGBA(
6  'hsl(50, 20%, 90%)',
7  { decimals: 0 }
8); // rgba(235,233,224,1)
9
10ColorTranslator.toHSL('rgb(255 0 0)'); // hsl(0 100% 50%)
11
12ColorTranslator.toHSLA('rgba(0, 255, 255, 0.5)'); // hsla(180,100%,50%,0.5)
13
14ColorTranslator.toCMYKObject('#F0F'); // {C: 0, M: 100, Y: 0, K: 0}
15
16ColorTranslator.toCMYK('#F0F'); // cmyk(0% 100% 0% 0%)
17
18ColorTranslator.toRGB(
19  { h: 115, s: '70%', l: '45%' },
20  { decimals: 0 }
21); // rgb(48 195 34)
22
23ColorTranslator.toHSLA(
24  { r: 115, g: 200, b: 150, a: 0.5 },
25  { decimals: 1 }
26); // hsl(144.7 43.6% 61.8% / 0.5)
27
28ColorTranslator.toHSLA(
29  { r: 95, g: 23, b: 12, a: Math.SQRT1_2 },
30  { decimals: 4 }
31); // hsl(7.9518 77.5701% 20.9804% / 0.7071)
32
33ColorTranslator.toCIELab(
34  '#00F',
35  { decimals: 2 }
36); // lab(29.57 68.3 -112.03)

You can also consult the demo 3, the demo 4 and the demo 5 to check the use of these static methods.

Color blends static methods

The static methods to create color blends accept any of the mentioned inputs as the first and second parameter, the third parameter is optional and it is the number of steps of the blending. And the fourth parameter is also optional and it is an options object (this fourth option is not present in the methods to generate HEX colors):

1// If steps is not sent, the default will be 5
2getBlendColorsStaticMethod(
3  fromColor: string | object,
4  toColor: string | object,
5  options?: Options
6)
7
8// Specifying the number of steps
9getBlendColorsStaticMethod(
10  fromColor: string | object,
11  toColor: string | object,
12  steps: number,
13  options?: Options
14)

Color blends static methods description

Static method	Description
getBlendHEX	Creates an array relative to the blend between two colors in hexadecimal notation
getBlendHEXObject	Creates an array of objects relative to the blend between two colors in hexadecimal notation
getBlendHEXA	Creates an array relative to the blend between two colors in hexadecimal notation with alpha
getBlendHEXAObject	Creates an array of objects relative to the blend between two colors in hexadecimal notation with alpha
getBlendRGB	Creates an array relative to the blend between two colors in rgb notation
getBlendRGBObject	Creates an array of objects relative to the blend between two colors in rgb notation
getBlendRGBA	Creates an array relative to the blend between two colors in rgb notation with alpha
getBlendRGBAObject	Creates an array of objects relative to the blend between two colors in rgb notation with alpha
getBlendHSL	Creates an array relative to the blend between two colors in hsl notation
getBlendHSLObject	Creates an array of objects relative to the blend between two colors in hsl notation
getBlendHSLA	Creates an array relative to the blend between two colors in hsl notation with alpha
getBlendHSLAObject	Creates an array of objects relative to the blend between two colors in hsl notation with alpha
getBlendHWB	Creates an array relative to the blend between two colors in hwb notation
getBlendHWBObject	Creates an array of objects relative to the blend between two colors in hwb notation
getBlendHWBA	Creates an array relative to the blend between two colors in hwb notation with alpha
getBlendHWBAObject	Creates an array of objects relative to the blend between two colors in hwb notation with alpha
getBlendCIELab	Creates an array relative to the blend between two colors in CIE L*a*b notation
getBlendCIELabObject	Creates an array of objects relative to the blend between two colors in CIE L*a*b notation
getBlendCIELabA	Creates an array relative to the blend between two colors in CIE L*a*b notation with alpha
getBlendCIELabAObject	Creates an array of objects relative to the blend between two colors in CIE L*a*b notation with alpha
getBlendLCH	Creates an array relative to the blend between two colors in lch notation
getBlendLCHObject	Creates an array of objects relative to the blend between two colors in lch notation
getBlendLCHA	Creates an array relative to the blend between two colors in lch notation with alpha
getBlendLCHAObject	Creates an array of objects relative to the blend between two colors in lch notation with alpha

Color blends static methods examples

1ColorTranslator.getBlendHEX('#FF0000', '#0000FF', 5);
2
3// [
4//   "#FF0000",
5//   "#BF003F",
6//   "#7F007F",
7//   "#3F00BF",
8//   "#0000FF"
9// ]
10
11ColorTranslator.getBlendHSLA('#FF000000', '#0000FFFF', 3);
12
13// [
14//   "hsl(0 100% 50% / 0)",
15//   "hsl(300 100% 25% / 0.5)",
16//   "hsl(240 100% 50% / 1)"
17// ]
18
19ColorTranslator.getBlendRGBAObject('#F000', 'rgba(0,0,255,1)', 5);
20
21// [
22//   {R: 255, G: 0, B: 0, A: 0},
23//   {R: 191.25, G: 0, B: 63.75, A: 0.25},
24//   {R: 127.5, G: 0, B: 127.5, A: 0.5},
25//   {R: 63.75, G: 0, B: 191.25, A: 0.75},
26//   {R: 0, G: 0, B: 255, A: 1}
27// ]

You can also consult the demo 6 to check the use of these static methods.

Color mix static methods

The static methods to mix colors accept an array of any of the mentioned inputs as the first parameter. The second parameter is optional and specifies the mixing mode (by default it will be ADDITIVE). And the third parameter is also optional and it is an options object (this third option is not present in the methods to generate HEX colors):

Note: The subtractive mix simulates the mixing of pigments, to achieve this, the rgb colors are converted to ryb color model, the addition is performed in this mode and at the end the result is converted back to rgb. The result is OK most of the time, but as this is not a real mix of pigments, sometimes the result could differ from the reality.

1// If mode is not sent, the default will be "ADDITIVE"
2getMixColorsStaticMethod(
3  colors: [string | object][],
4  options?: Options
5)
6
7// Specifying the mix mode
8getMixColorsStaticMethod(
9  colors: [string | object][],
10  mode: 'ADDITIVE' | 'SUBTRACTIVE',
11  options?: Options
12)

Color mix static methods description

Static method	Description
getMixHEX	Gets the mix of the input colors in hexadecimal notation
getMixHEXObject	Gets the mix of the input colors in an object in hexadecimal notation
getMixHEXA	Gets the mix of the input colors in hexadecimal notation with alpha
getMixHEXAObject	Gets the mix of the input colors in an object in hexadecimal notation with alpha
getMixRGB	Gets the mix of the input colors in rgb notation
getMixRGBObject	Gets the mix of the input colors in an object in rgb notation
getMixRGBA	Gets the mix of the input colors in rgb notation with alpha
getMixRGBAObject	Gets the mix of the input colors in an object in rgb notation with alpha
getMixHSL	Gets the mix of the input colors in hsl notation
getMixHSLObject	Gets the mix of the input colors in an object in hsl notation
getMixHSLA	Gets the mix of the input colors in hsl notation with alpha
getMixHSLAObject	Gets the mix of the input colors in an object in hsl notation with alpha
getMixHWB	Gets the mix of the input colors in hwb notation
getMixHWBObject	Gets the mix of the input colors in an object in hwb notation
getMixHWBA	Gets the mix of the input colors in hwb notation with alpha
getMixHWBAObject	Gets the mix of the input colors in an object in hwb notation with alpha
getMixCIELab	Gets the mix of the input colors in CIE L*a*b color notation
getMixCIELabObject	Gets the mix of the input colors in an object in CIE L*a*b color notation
getMixCIELabA	Gets the mix of the input colors in CIE L*a*b color notation with alpha
getMixCIELabAObject	Gets the mix of the input colors in an object in CIE L*a*b color notation with alpha
getMixLCH	Gets the mix of the input colors in lch notation
getMixLCHObject	Gets the mix of the input colors in an object in lch notation
getMixLCHA	Gets the mix of the input colors in lch notation with alpha
getMixLCHAObject	Gets the mix of the input colors in an object in lch notation with alpha

Color mix static methods examples

1ColorTranslator.getMixHEX(['#FF0000', '#0000FF']);
2
3// #FF00FF
4
5ColorTranslator.getMixHSL(['rgba(255, 0, 0, 1)', '#00FF00']);
6
7// hsl(60 100% 50%)
8
9ColorTranslator.getMixHEXAObject(['#F00', 'rgb(0, 0, 255)'], 'ADDITIVE');
10
11// { R: '0xFF', G: '0x00', B: '0xFF', A: '0xFF' }
12
13ColorTranslator.getMixHEX(['#FF0', '#F00'], 'SUBTRACTIVE');
14
15// #FF8800

You can also consult the demo 8 and demo 9 to check the use of these static methods.

Color shades and color tints static methods

The static methods to get shades or tints of a color accept any of the mentioned inputs as the first parameter. The second parameter specifies the number of shades or tints that should be returned and the third parameter is optional and it is an options object. This method will return the colors in the same format that was sent as input:

1// If shades is not sent, the default will be 5
2getShades(
3  color: string | object,
4  options?: Options
5)
6
7// Specifying the shades number
8getShades(
9  color: string | object,
10  shades: number,
11  options?: Options
12)
13
14// If tints is not sent, the default will be 5
15getTints(
16  color: string | object,
17  options?: Options
18)
19
20// Specifying the tints number
21getTints(
22  color: string | object,
23  tints: number,
24  options?: Options
25)

Color shades and color tints static methods description

Static method	Description
getShades	Gets shades of a colour (mix the color with black increasing its darkness)
getTints	Gets tints of a colour (mix the color with white increasing its lightness)

Color shades and color tints static methods examples

1ColorTranslator.getShades('#FF0000', 5);
2
3// [
4//   "#D40000",
5//   "#AA0000",
6//   "#800000",
7//   "#550000",
8//   "#2A0000"
9// ]
10
11ColorTranslator.getTints({r: 255, g: 0, b: 0, a: 0.5}, 5);
12
13// [
14//   {R: 255, G: 42.5, B: 42.5, A: 0.5},
15//   {R: 255, G: 85, B: 85, A: 0.5},
16//   {R: 255, G: 127.5, B: 127.5, A: 0.5},
17//   {R: 255, G: 170, B: 170, A: 0.5},
18//   {R: 255, G: 212.5, B: 212.5, A: 0.5}
19// ]

You can also consult the demo 7 to check the use of these static methods.

Color harmonies static method

The static method to create color harmonies accepts four parmeters, the first one could be any of the mentioned inputs, the second one is optional and it is to specify the kind of harmony (by default it will be "COMPLEMENTARY"), the third one is also optional and it specifies if the returned harmony is based on additive or subtractive colors (by default it will be "ADDITIVE"), and the fourth parameter is also optional and it is an options object. This method will return the colors in the same format that was sent as input:

1// If harmony is not sent, the default will be "COMPLEMENTARY"
2// If mode is not sent, the default will be "ADDITIVE"
3getHarmony(
4  color: string | object,
5  options?: Options
6)
7
8// If mode is not sent, the default will be "ADDITIVE"
9getHarmony(
10  color: string | object,
11  harmony: 'ANALOGOUS' | 'COMPLEMENTARY' | 'SPLIT_COMPLEMENTARY' | 'TRIADIC' | 'TETRADIC' | 'SQUARE',
12  options?: Options
13)
14
15// If harmony is not sent, the default will be "COMPLEMENTARY"
16getHarmony(
17  color: string | object,
18  mode: 'ADDITIVE' | 'SUBTRACTIVE',
19  options?: Options
20)
21
22getHarmony(
23  color: string | object,
24  harmony: 'ANALOGOUS' | 'COMPLEMENTARY' | 'SPLIT_COMPLEMENTARY' | 'TRIADIC' | 'TETRADIC' | 'SQUARE',
25  mode: 'ADDITIVE' | 'SUBTRACTIVE',
26  options?: Options
27)

Color harmonies static method description

Static method	Description
getHarmony	Returns an array of colors representing the harmony requested. The color output will be the same that was sent as input

Available armonies

Harmony	Description	Returned colors
ANALOGOUS	Returns the same color plus the two relative analogous colours	3
COMPLEMENTARY	Returns the same color plus the relative complementary color	2
SPLIT_COMPLEMENTARY	Returns the same color plus the two relative split complementary colours	3
SQUARE	Returns the same color plus the three relative evenly square colours	4
TETRADIC	Returns the same color plus the three relative tetradic colours	4
TRIADIC	Returns the same color plus the two relative evenly triadic colors	3

Color harmonies static method examples

1ColorTranslator.getHarmony('#FF00FF');
2
3// ["#FF00FF", "#00FF00"]
4
5ColorTranslator.getHarmony('rgba(0 255 255 / 0.5)', 'ANALOGOUS');
6
7// [
8//   "rgba(0 255 255 / 0.5)",
9//   "rgba(0 127.5 255 / 0.5)",
10//   "rgba(0 255 127.5 / 0.5)"
11// ]
12
13ColorTranslator.getHarmony(
14  { r: 115, g: 200, b: 150, a: 0.5 },
15  'COMPLEMENTARY',
16  'ADDITIVE',
17  { decimals: 2 }
18);
19
20// [
21//   {R: 115, G: 200, B: 150, A: 0.5},
22//   {R: 200, G: 123.75, B: 115, A: 0.5}
23// ]
24
25ColorTranslator.getHarmony('#FF0000', 'COMPLEMENTARY', 'SUBTRACTIVE');
26
27// ["#FF0000", "#00FF00"]
28

You can also consult the demo 10 and demo 11 to check the use of this static method.

TypeScript Support

The package has its own type definitions, so it can be used in a TypeScript project without any issues. The next enums and interfaces are exposed and can be imported in your project:

Harmony and Mix

You can send these values as strings and it will be checked by TypeScript if the string is correct. But for comodity, you can use the Harmony and Mix enums exported in the library.

1Harmony.COMPLEMENTARY === 'COMPLEMENTARY';
2Mix.ADDITIVE === 'ADDITIVE'

InputOptions

This is the type of the options object that can be sent to the class constructor or to the static methods.

1interface InputOptions {
2    decimals?: number;
3    legacyCSS?: boolean;
4    spacesAfterCommas?: boolean;
5    anglesUnit?: 'none' | 'deg' | 'grad' | 'rad' | 'turn';
6    rgbUnit?: 'none' | 'percent';
7    labUnit?: 'none' | 'percent';
8    lchUnit?: 'none' | 'percent';
9    cmykUnit?: 'none' | 'percent';
10    alphaUnit?: 'none' | 'percent';
11    cmykFunction?: 'device-cmyk' | 'cmyk';
12}

HEXObject

This type is returned by the HEXObject, and HEXAObject properties, the toHEXObject, toHEXAObject, getBlendHEXObject, getBlendHEXAObject, getMixHEXObject, and the getMixHEXAObject methods, and the getShades, getTints, and getHarmony methods (when the input is an HEXObject).

1interface HEXObject {
2    R: string;
3    G: string;
4    B: string;
5    A?: string;
6}

RGBObject

This type is returned by the RGBObject, and RGBAObject properties, the toRGBObject, toRGBAObject, getBlendRGBObject, getBlendRGBAObject, getMixRGBObject, and the getMixRGBAObject methods, and the getShades, getTints, and getHarmony methods (when the input is an RGBObject).

1interface RGBObject {
2    R: number;
3    G: number;
4    B: number;
5    A?: number;
6}

HSLObject

This type is returned by the HSLObject, and HSLAObject properties, the toHSLObject, toHSLAObject, getBlendHSLObject, getBlendHSLAObject, getMixHSLObject, and the getMixHSLAObject methods, and the getShades, getTints, and getHarmony methods (when the input is an HSLObject).

1interface HSLObject {
2    H: number;
3    S: number;
4    L: number;
5    A?: number;
6}

HWBObject

This type is returned by the HWBObject, and HWBAObject properties, the toHWBObject, toHWBAObject, getBlendHWBObject, getBlendHWBAObject, getMixHWBObject, and the getMixHWBAObject methods, and the getShades, getTints, and getHarmony methods (when the input is an HWBObject).

1interface HWBObject {
2    H: number;
3    W: number;
4    B: number;
5    A?: number;
6}

CIELabObject

This type is returned by the CIELabObject, and CIELabAObject properties, the toCIELabObject, toCIELabAObject, getBlendCIELabObject, getBlendCIELabAObject, getMixCIELabObject, and the getMixCIELabAObject methods, and the getShades, getTints, and getHarmony methods (when the input is an CIELabObject).

1interface CIELabObject {
2    L: number;
3    a: number;
4    b: number;
5    A?: number;
6}

LCHObject

This type is returned by the LCHObject, and LCHAObject properties, the toLCHObject, toLCHAObject, getBlendLCHObject, getBlendLCHAObject, getMixLCHObject, and the getMixLCHAObject methods, and the getShades, getTints, and getHarmony methods (when the input is an LCHObject).

1interface LCHObject {
2    L: number;
3    C: number;
4    H: number;
5    A?: number;
6}

CMYKObject

This type is returned by the CMYKObject property, and the toCMYKObject and toCMYKAObject methods.

1interface CMYKObject {
2    C: number;
3    M: number;
4    Y: number;
5    K: number;
6}