@lost-types/colorista

Colorista

Helper functions to work with Color.

Usage

In the terminal:

% npm install @lost-types/colorista

Then in the module:

// JavaScript modules
import Colorista from '@lost-types/colorista';

// CommonJS
const Colorista = require('@lost-types/colorista');

const backgroundColor = Colorista.mix('gray', 'white', 0.5);
const primaryColor = Colorista.findByContrast(294, 0.8, backgroundColor, 4.5);

Motivation

Motivation is fairly simple, I’ve created a Color type and rather than keep methods directly on the class, decided to extract them into a separate tree-shakable library called Colorista. The main purpose at the moment revolves around the contrast, I wanted to be able to find colors with specific hue values that have certain contrast relative to the base color, as well as the ability to generate random colors with certain contrast value:

const targetContrast = 4.5;
const randomColor = Colorista.randomByContrast(targetContrast, '#fafefd');

randomColor.toHexString(); // #b45c41
Colorista.contrast(randomColor, '#fafefd'); // 4.54

API

Methods

Colorista.contrast()

Calcurates absolute contrast factor of 1 between two colors. Returns number in [1...21] range, regardless of the order of arguments. Output will be rounded to 2 decimal point digits.

Parameter	Type	Default value	Notes
color	AnyColor		Color to be compared
base	AnyColor		Base color to be compared against

NOTE: AnyColor here means string in rgb, hsl, #-hex notation or named color, RGB(A) array or Color instance.

Colorista.contrast('white', 'hsl(0, 0%, 0%)'); // 21
Colorista.contrast('black', 'rgb(255, 255, 255)'); // 21

Colorista.contrast('blue', 'salmon'); // 3.43

---

Colorista.cooler()

Returns cooler version of the provided color with given intensity and optional filter color. Does not modify input color. Returns Color instance.

Parameter	Type	Default value	Notes
color	AnyColor		Any color to transform
intensity	number	0.2	Intensity (opacity) of the filter
filter	AnyColor	RGBArray<[67, 162, 237]>	Optional cool filter

const coolOrange = cooler('orange');
const coolerOrange = cooler('orange', 0.35);
const coolestOrange = cooler('orange', 0.45, 'blue');

coolOrange.toHexString(); // #fba505
coolerOrange.toRgbString(); // rgb(249, 165, 7)
coolestOrange.toHslString(); // hsl(38, 90%, 50%)

---

Colorista.getHueByOffset()

Returns hue value by provided hue group and hue group offset. Number in [0...359] range, representing hue angle on the color wheel, where 0 is red. More information about hue groups here: https://github.com/snigo/color#colorhuegroup

Parameter	Type	Default value	Notes
hueGroup	number		Desired hue group
hueGroupOffset	number	0	Hue offset within provided hue group

Colorista.getHueByOffset(10, 5); // 300
Colorista.getHueByOffset(1, 15); // 0
Colorista.getHueByOffset(9, 0); // 225

---

Colorista.getTone()

Returns Color instance representing the tone of the color.

Parameter	Type	Default value	Notes
color	AnyColor		Any color

Colorista.getTone('hsl(34, 80%, 12%)').toHslString(); // hsl(34, 80%, 50%)
Colorista.getTone('lightblue').toHslString(); // hsl(195, 53%, 50%)
Colorista.getTone('rgb(0% 0% 0%)').name; // gray

---

Colorista.findByContrast()

Tries best to find and return Color instance with provided hue and saturation and given contrast ratio relative to given base color.

Parameter	Type	Default value	Notes
hue	number		Hue value of the output color
saturation	number		Saturation value of the output color
baseColor	AnyColor		Base / Background color
targetContrast	number		Contrast between output and base colors

const hue = 294;
const saturation = 0.85;
const myColor = Colorista.findByContrast(hue, saturation, 'white', 6);

myColor.toHslString(); // hsl(294, 85%, 39%)
Colorista.contrast(myColor, 'white'); // 6.17

NOTE: Due to the fact there is no formula to achive the result in mathematical way, at least to my knowledge, method uses binary search (aka divide and conquer) to match the closest color. Matching criteria is 0.05 delta and if it's not met algorithm outputs the last color it tries, even if semi-last was actually closer. For example, considering the code above, contrast between white and hsl(294, 85%, 40%) is 5.94 which is closer to 6, but still out of matching criteria.

---

Colorista.hueShift()

Shifts the hue of the with provided angle and returns new instance of Color woth shifted hue.

Parameter	Type	Default value	Notes
color	AnyColor		Source color
angle	number		Angle the hue to be shifted by

const shifted = Colorista.hueShift('yellow', 90);
shifted.toHslString(); // hsl(150, 100%, 50%)

Colorista.hueShift('hsl(0, 45%, 50%)', -100).hue; // 260

---

Colorista.invert()

Inverts color. Returns new instance of Color representing inverted color.

Parameter	Type	Default value	Notes
color	AnyColor		Source color

Colorista.invert('white').toHexString(); // #000000

const invertedPink = Colorista.invert('pink');
invertedPink.toRgbString(); // rgb(0, 63, 52)

Colorista.invert(invertedPink).name; // pink

---

Colorista.mix()

Mixes two colors with optional alpha value. Returns new mixed Color.

Parameter	Type	Default value	Notes
color	AnyColor		Source color to be mixed
base	AnyColor		Source color to be mixed
alpha	number		Optional alpha value for the color, number in [0...1] range

Colorista.mix('pink', 'blue', 0.3).toHexString(); // #4d3aef
Colorista.mix('white', 'black', 0.5).name; // gray
Colorista.mix([56, 255, 123, 0.5], { hue: 223, saturation: 0.8, lightness: 0.45 }).toRgbString(); // rgb(40, 165, 165)

---

Colorista.offsetHue()

Returns new color within the same hue group but with the new provided hue group offset

Parameter	Type	Default value	Notes
color	AnyColor		Source color
offsetValue	number		Hue group offset, number in [0...29] range

const themeHueGroupOffset = 4;
const green = new Color('#0f0');
green.hueGroupOffset; // 15

const themedGreen = Colorista.offsetHue('#0f0', themeHueGroupOffset);
themedGreen.toHslString(); // hsl(109, 100%, 50%)
themedGreen.hueGroupOffset; // 4

---

Colorista.opposite()

Return opposite color on the color wheel keeping saturation and lightness values

Parameter	Type	Default value	Notes
color	AnyColor		Source color

const redish = new Color('hsl(345, 80%, 45%)');
redish.hue; // 345

Colorista.opposite(redish).toHslString(); // hsl(165, 80%, 45%)

---

Colorista.randomByContrast()

Generates random color with target contrast to the provided base color and with saturation within given range

Parameter	Type	Default value	Notes
targetContrast	number	4.5	Target contrast to be aimed to
base	AnyColor	[255, 255, 255]	Base color the target contrast to be check on
saturationRange	`number	number[]`	[0, 1]

const defaultRandom = Colorista.randomByContrast();
Colorista.contrast(defaultRandom, 'white'); // 4.54

const lowContrastRandom = Colorista.randomByContrast(1.8, 'black', [0.5, 1]);
lowContrastRandom.saturation; // 0.79
Colorista.contrast(lowContrastRandom, 'black'); // 1.79

const fixedSaturationRandom = Colorista.randomByContrast(7, 'pink', 0.8);
fixedSaturationRandom.saturation; // 0.8
Colorista.contrast(fixedSaturationRandom, 'pink'); // 6.62

Note: due to rounding to whole number of red, green and blue values, randomByContrast() will give closest possible color with given contrast target value to base color.

---

Colorista.randomHslColor()

Generates random color with provided hue, saturation and lightness ranges

Parameter	Type	Default value	Notes
hueRange	`number	number[]`	[0, 359]
saturationRange	`number	number[]`	[0, 1]
lightnessRange	`number	number[]`	[0, 1]

const totallyRandom = Colorista.randomHslColor();
totallyRandom.toHslString(); // hsl(233, 25%, 54%)

const fixedSaturationRandomBlue = Colorista.randomHslColor([210, 270], 0.8, [0.4, 0.65]);
fixedSaturationRandomBlue.toHslString(); // hsl(262, 80%, 53%)

---

Colorista.randomRgbColor()

Generates random color with provided red, green and blue ranges.

Parameter	Type	Default value	Notes
redRange	`number	number[]`	[0, 255]
greenRange	`number	number[]`	[0, 255]
blueRange	`number	number[]`	[0, 255]

const totallyRandom = Colorista.randomRgbColor();
totallyRandom.toRgbString(); // rgb(159, 74, 79)

const fixedRedRandom = Colorista.randomRgbColor(0, [0, 255], [0, 12]);
fixedRedRandom.toRgbString(); // rgb(0, 108, 6);

---

Colorista.warmer()

Returns warmer version of the provided color with given factor and filter.

Parameter	Type	Default value	Notes
color	AnyColor		Any color to transform
intensity	number	0.2	Intensity (opacity) of the filter
filter	AnyColor	RGBArray<[247, 166, 115]>	Optional warm filter

const coolSalmon = cooler('salmon');
const coolerSalmon = cooler('salmon', 0.35);
const coolestSalmon = cooler('salmon', 0.45, 'blue');

coolSalmon.toHexString(); // #f68174
coolerSalmon.toRgbString(); // rgb(245, 129, 118)
coolestSalmon.toHslString(); // hsl(1, 77%, 70%)