🤹 color-math

ColorMath is an expression parser and evaluator dealing with color representations. Using special grammar it supports various color models, mixing, blending, channels manipulation, scaling, bezier interpolation and more. It also supports transpiling most of the expressions to less.js.

Install

npm i color-math -S

Usage Example

import * as ColorMath from "color-math"

// will return color which is result of mixing red and green colors
const result = ColorMath.evaluate("red | green")
// prints "#804000" ('result.result' is a chroma.js instance; see link below)
console.log(result.result.hex())

// set color's alpha channel to 30%
result = ColorMath.evaluate("red @a 30%")
console.log(result.result.css()) // prints "rgba(255, 0, 0, 0.3)"

// arithmetic operations with colors and numbers
result = ColorMath.evaluate("(#222 + #444) / 2")
console.log(result.resultStr) // prints "#333333"

// transpile to Less
result = ColorMath.evaluate("rgb 165 42 42 >> .2", { evaluator: new ColorMath.Evaluators.LessEvaluator() })
console.log(result.result) // prints "saturate(rgb(165, 42, 42), 20%, relative)"

chroma.js color library is used internally to manipulate colors and wrap results.

Expressions Cheatsheet

Click on expression to visualize result in ColorMath online parser.

Use parenthesis to control evaluation order and build complex expressions.

Ways to Define Color

Expression	Description
#ffcc00	hexadecimal color representation
ffcc00	hexadecimal color representation without hash symbol
#fc0	short hexadecimal color representation
fc0	short hexadecimal color representation without hash symbol
skyblue	color literals from W3C/X11 specification
rand	generate random color
num 33023	color from number
temp 3500	color by temperature in Kelvin
wl 560	color from wavelength value

Color Models

Expression	Description
rgb 127 255 212	RGB color model
rgba 135 206 235 75%	RGB color model with alpha channel
argb .7 255 99 71	RGB color model with alpha channel (first)
cmyk .43 .12 0 .8	CMYK color model
cmyka 0 .61 .72 0 60%	CMYK color model with alpha channel
cmy .5 0 .17	CMY color model
cmya 0 .61 .72 .65	CMY color model with alpha channel
hsl 159.8 100% 75%	HSL color model
hsla 197 .71 .73 55%	HSL color model with alpha channel
hsv 160 .5 1	HSV (also known as HSB) color model
hsb 197 .43 .92	HSB color model (alias for HSV)
hsva 9 .72 1 50%	HSV color model with alpha channel
hsi 161 .36 .78	HSI color model
hsia 196 .30 .75 45%	HSI color model with alpha channel
lab 92 (-46) 9.7	LAB color model
laba 79 (-14.8) (-21) 40%	LAB color model with alpha channel
lch 92 46.5 168	LCH color model
lcha 79 26 235 35%	LCH color model with alpha channel
hcl 168 46.5 92	HCL color model (reversed LCH)
hcla 235 26 79 35%	HCL color model with alpha channel

Color Operations

Expression	Description
#444 * 2	arithmetic operations with numbers
skyblue - 0xf	arithmetic operations with numbers
~red	invert color
red | green	mix colors
red | {25%} green	mix colors in variable proportion
red | {25% hsl} green	mix colors in variable proportion and specific color model
red | {hsl} green	mix colors in specific color model
hotpink << 50%	desaturate color
rgb 165 42 42 >> .2	saturate color
temp 4000 <<< 30%	darken color
#fc0 >>> 70%	lighten color
pink %% hotpink	compute WCAG contrast ratio between two colors

Color Blending

Expression	Description
#222 + #444	add
#ccc - #111	subtract
#ff6600 * #ccc	multiply
#222 / #444	divide
skyblue <<< tomato	darken
skyblue >>> tomato	lighten
#ff6600 !* #00ff00	screen
#ff6600 ** #999	overlay
olive <* pink	hard light
olive *> pink	soft light
ffcc00 ^* ccc	difference
ffcc00 ^^ ccc	exclusion
ffcc00 !^ ccc	negate
indigo << red	burn
indigo >> red	dodge

Color Channels Manipulation

Expression	Description
brown @red	get channel's value using its name or synonym
#ffcc00 @g	get channel's value using its name or synonym
t 5000 @cmyk.y	get channel's value using its name or synonym
aquamarine @a = .3	set channel's absolute value
rgb 5 7 9 @hsl.h 90	set channel's absolute value
#000 @lightness 50%	set channel's absolute value
red @a /= 2	set relative channel's value
ffcc00 @rgb.r -= 50	set relative channel's value
tomato @s *= 30%	set relative channel's value
olive @n	get color's numeric value
fff @n 0	set color's absolute numeric value
#0080ff @n /= 2	set color's relative numeric value
#ffe3cd @t	get color's temperature in Kelvin
red @t 3500	set color's absolute temperature
ffe3cd @t += 500	set color's relative temperature

Color Scales

Expression	Description
scale (red 0f0 blue)	scale list of colors (make gradient)
scale (yellow 008ae5) -> 20	grab n equi-distant colors from a color scale
scale (t 2000 t 6000)	scale list of colors
bezier (ff0 red #000)	perform bezier interpolate of list of colors
bezier (red 0f0)	perform bezier interpolate of list of colors
scale (red:.2 0f0:50%)	set position of each color (inline)
scale (red 0f0) @domain (.2 .5)	set position of each color (as a parameter)
scale (red 0f0) @pad .25	cut off a fraction of the gradient on both sides
bezier (red 0f0) @pad (.1 .3)	cut off a fraction of the gradient on both sides
cubehelix	Dave Green's cubehelix scaled color scheme
cubehelix @pad (0 .2)	cut off a fraction of the gradient on both sides
cubehelix @start 200	start for hue rotation
cubehelix @rot (-.5)	number of rotations
cubehelix @hue .5	controls how saturated colors of all hues are
cubehelix @hue (1 0)	controls how saturated colors of all hues are
cubehelix @gamma .7	emphasize low or high intensity values
cubehelix @lt (.3 .8)	adjust lightness (black to white)
cubehelix @start 200 @rot .5	parameters can be chained
+scale (black red yellow)	auto-correct lightness of a scale
+bezier (yellow 0f0 blue) -> 10	auto-correct lightness and grab n equi-distant colors

Numbers

Expression	Description
0b01101001	binary
0o151	octal
105	decinal
0x69	hexadecimal
55%	percent value
5 + 10	add numbers
-360 * 0.5 + (100 - 40)	arithmetic operations
0xf / 0b1010	division
4 ^ (2 / 4)	take expression to a specified power

Lists

Expression	Description
red 0f0 blue	define list of three colors
(pink >> .5) gold	define list of two colors

Brewer Constants

OrRd, PuBu, BuPu, Oranges, BuGn, YlOrBr, YlGn, Reds, RdPu, Greens, YlGnBu, Purples, GnBu, Greys, YlOrRd, PuRd, Blues, PuBuGn, Spectral, RdYlGn, RdBu, PiYG, PRGn, RdYlBu, BrBG, RdGy, PuOr, Set2, Accent, Set1, Set3, Dark2, Paired, Pastel2, Pastel1

Variables and Statements

Expression	Description
$col = rgb 255 204 0	assign color value to a variable
$num = 2^8 - 1	assign number value to a variable
$lst = #444 #888	assign list value to a variable
$my = yellow black; bezier $my	separate statements with semicolon

A read–eval–print loop (REPL)

npm start

Interpreter will start. Now you can type your expressions.

Demo and documentation

Please go to http://colormath.net/ to test your expressions, visualize results and read about all available features with examples.