@lost-types/colorista v1.2.1

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.

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.

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

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.

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.

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.

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.

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.

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

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

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

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

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.

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.

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%)