Khrôma

A collection of functions for manipulating CSS colors, inspired by SASS.

Features

• Small: the entire library weighs ~5kb (min + gzip) and has no dependencies.
• Fast: in our benchmark suite functions are executed at ~0.0025ms per call on a mid-2014 MBP.
• Flexible: All valid CSS colors are supported.
• SASS-like: if you're familiar with SASS you should feel right at home.

Install

1npm install --save khroma

Usage

1import {red, isDark, darken, change} from 'khroma';
2
3red ( '#ffffff' ); // => 255
4isDark ( 'white' ); // => false
5darken ( 'hsl(0, 5%, 100%)', 50 ); // => 'hsl(0, 5%, 50%)'
6change ( 'rgb(255, 255, 255)', { a: 0.5 } ); // => 'rgba(255, 255, 255, 0.5)'

Functions

These are all the provided functions, for each of them below you can find a short description, its interface and examples.

Create	Convert	Get channel	Get more	Edit channel	Edit more
hex	toKeyword	channel	contrast	saturate	adjust
rgb	toHex	red	luminance	desaturate	change
rgba	toRgba	green	isDark	lighten	invert
hsl	toHsla	blue	isLight	darken	mix
hsla		hue	isTransparent	opacify	scale
		saturation	isValid	fadeIn
		lightness		transparentize
		alpha		fadeOut
		opacity		rgba (alt)
				complement
				grayscale

Create

These functions create a new color given the provided channels.

hex

Alias for rgba.

rgb

Alias for rgba.

rgba

Creates a new color given its rgba channels, the alpha channel is optional.

1function rgba ( r: string, g: number, b: number, a: number = 1 ): string;

1rgba ( 255, 204, 0 ); // => '#ffcc00'
2rgba ( 255, 204, 0, 0.5 ); // => 'rgba(255, 204, 0, 0.5)'

hsl

Alias for hsla.

hsla

Creates a new color given its hsla channels, the alpha channel is optional.

1function hsla ( h: number, s: number, l: number, a: number = 1 ): string;

1hsla ( 0, 50, 100 ); // => 'hsl(0, 50%, 100%)'
2hsla ( 10, 50, 100, 0.5 ); // => 'hsla(10, 50%, 100%, 0.5)'

Convert

These functions convert supported colors to a specific format.

toKeyword

Convert a color to the keyword format, when possible.

1function toKeyword ( color: string ): string | undefined;

1toKeyword ( '#ff0000' ); // => 'red'
2toKeyword ( '#ffcc00' ); // => undefined

toHex

Convert a color to the HEX format.

1function toHex ( color: string ): string;

1toHex ( 'red' ); // => '#ff0000'
2toHex ( '#ff0000' ); // => '#ff0000'

toRgba

Convert a color to the RGBA format.

1function toRgba ( color: string ): string;

1toRgba ( 'red' ); // => 'rgb(255, 0, 0)'
2toRgba ( '#ff0000' ); // => 'rgb(255, 0, 0)'
3toRgba ( '#00000088' ); // => 'rgba(0, 0, 0, 0.5333333333)'

toHsla

Convert a color to the HSLA format.

1function toHsla ( color: string ): string;

1toHsla ( 'red' ); // => 'hsl(0, 100%, 50%)'
2toHsla ( '#ff0000' ); // => 'hsl(0, 100%, 50%)'
3toHsla ( 'rgb(255, 0, 0)' ); // => 'hsl(0, 100%, 50%)'

Get _channel

These functions get a single channel from the provided color.

channel

Gets any single channel of the color.

1function channel ( color: string, channel: 'r' | 'g' | 'b' | 'h' | 's' | 'l' | 'a' ): number;

1channel ( '#ffcc00', 'r' ); // => 255
2channel ( '#ffcc00', 'h' ); // => 48
3channel ( '#ffcc00', 'a' ); // => 1

red

Gets the red channel of the color.

1function red ( color: string ): number;

1red ( '#ffcc00' ); // => 255

green

Gets the green channel of the color.

1function green ( color: string ): number;

1green ( '#ffcc00' ); // => 204

blue

Gets the blue channel of the color.

1function blue ( color: string ): number;

1blue ( '#ffcc00' ); // => 0

hue

Gets the hue channel of the color.

1function hue ( color: string ): number;

1hue ( 'hsl(0, 50%, 100%)' ); // => 0

saturation

Gets the saturation channel of the color.

1function saturation ( color: string ): number;

1saturation ( 'hsl(0, 50%, 100%)' ); // => 50

lightness

Gets the lightness channel of the color.

1function lightness ( color: string ): number;

1lightness ( 'hsl(0, 50%, 100%)' ); // => 100

alpha

Gets the alpha channel of the color.

1function alpha ( color: string ): number;

1alpha ( '#ffcc00' ); // => 1
2alpha ( 'rgba(255, 205, 0, 0.5)' ); // => 0.5

opacity

Alias for alpha.

Get _more

These functions get some other information from the provided color.

contrast

Gets the contrast in luminance between two colors.

Contrast values go between 1 and 10. 1 means same color, >= 4 means decent contrast, >= 7 means great contrast, 10 means great contrast.

1function contrast ( color1: string, color2: string ): number;

1contrast ( '#000000', '#000000' ); // => 1
2contrast ( '#000000', '#ffffff' ); // => 10
3contrast ( '#888888', '#ffffff' ); // => 4.0617165366

luminance

Gets the relative luminance of the color.

1function luminance ( color: string ): number;

1luminance ( 'black' ); // => 0
2luminance ( 'white' ); // => 1
3luminance ( '#ffcc00' ); // => 0.6444573127

isDark

Checks if the provided color is a dark color.

1function isDark ( color: string ): number;

1isDark ( 'black' ); // => true
2isDark ( 'white' ); // => false
3isDark ( '#ffcc00' ); // => false

isLight

Checks if the provided color is a light color.

1function isLight ( color: string ): number;

1isLight ( 'black' ); // => false
2isLight ( 'white' ); // => true
3isLight ( '#ffcc00' ); // => true

isTransparent

Checks if the provided color is a transparent color.

1function isTransparent ( color: string ): boolean;

1isTransparent ( 'transparent' ); // => true
2isTransparent ( '#ffcc0000' ); // => true
3isTransparent ( '#ffcc00' ); // => false

isValid

Checks if the provided color is a valid color.

1function isLight ( color: string ): boolean;

1isValid ( 'black' ); // => true
2isValid ( '#ffcc00' ); // => true
3isValid ( '#wtf' ); // => false

Edit _channel

These functions change a single channel of the provided color.

saturate

Increases the saturation channel of the color.

1function saturate ( color: string, amount: number ): string;

1saturate ( 'hsl(0, 50%, 50%)', 25 ); // => 'hsl(0, 75%, 50%)'

desaturate

Decreases the saturation channel of the color.

1function desaturate ( color: string, amount: number ): string;

1desaturate ( 'hsl(0, 50%, 50%)', 25 ); // => 'hsl(0, 25%, 50%)'

lighten

Increases the lightness channel of the color.

1function lighten ( color: string, amount: number ): string;

1lighten ( 'hsl(0, 50%, 50%)', 25 ); // => 'hsl(0, 50%, 75%)'

darken

Decreases the lightness channel of the color.

1function darken ( color: string, amount: number ): string;

1darken ( 'hsl(0, 50%, 50%)', 25 ); // => 'hsl(0, 50%, 25%)'

opacify

Increases the opacity channel of the color.

1function opacify ( color: string, amount: number ): string;

1opacify ( 'rgba(255, 204, 0, 0.5)', 0.25 ); // => 'rgba(255, 204, 0, 0.75)'

fadeIn

Alias for opacify.

transparentize

Decreases the opacity channel of the color.

1function transparentize ( color: string, amount: number ): string;

1transparentize ( 'rgba(255, 204, 0, 0.5)', 0.25 ); // => 'rgba(255, 204, 0, 0.25)'

fadeOut

Alias for transparentize.

rgba (alt)

Sets a new value for the opacity channel.

1function rgba ( color: string, amount: number ): string;

1rgba ( 'rgba(255, 204, 0, 0.5)', 0.1 ); // => 'rgba(255, 204, 0, 0.1)'

complement

Gets the complement of the color, rotating its hue channel by 180 degrees.

1function complement ( color: string ): string;

1complement ( '#ffcc00' ); // => 'hsl(228, 100%, 50%)'

grayscale

Gets the grayscale version of the color, setting its saturation to 0.

1function grayscale ( color: string ): string;

1grayscale ( '#ffcc00' ); // => 'hsl(48, 0%, 50%)'

Edit _more

These functions can/will change more than a single channel at once of the provided color.

adjust

Increases or decreases the value of any channel of the color.

1function adjust ( color: string, channels: Record<'r' | 'g' | 'b' | 'h' | 's' | 'l' | 'a', number> ): string;

1adjust ( '#ffcc00', { r: -10, g: 200 } ); // => '#f5ff00'
2adjust ( '#ffcc00', { a: -0.5 } ); // => 'rgba(255, 204, 0, 0.5)'
3adjust ( '#ffcc00', { h: 50, l: -30 } ); // => 'hsl(98, 100%, 20%)'

change

Sets a new value for any channel of the color.

1function change ( color: string, channels: Record<'r' | 'g' | 'b' | 'h' | 's' | 'l' | 'a', number> ): string;

1change ( '#ffcc00', { r: 10, g: 200 } ); // => '#0ac800'
2change ( '#ffcc00', { a: 0.5 } ); // => 'rgba(255, 204, 0, 0.5)'
3change ( '#ffcc00', { h: 50, l: 30 } ); // => 'hsl(50, 100%, 30%)'

invert

Gets the inverse of the color.

1function invert ( color: string, weight: number = 100 ): string;

1invert ( '#ffcc00' ); // => '#0033ff'
2invert ( '#ffcc00', 50 ); // => '#808080'

mix

Mixes two colors together.

1function mix ( color1: string, color2: string, weight: number = 50 ): string;

1mix ( 'red', 'blue' ); // => '#800080'
2mix ( 'red', 'blue', 15 ); // => '#2600d9'

scale

Scales any channel of the color.

1function scale ( color: string, channels: Record<'r' | 'g' | 'b' | 'h' | 's' | 'l' | 'a', number> ): string;

1scale ( '#ffcc00', { r: -50, b: 10 } ); // => '#80cc1a'

License

MIT © Fabio Spampinato, Andrew Maney