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

npm install --save khroma

Usage

import {red, isDark, darken, change} from 'khroma';

red ( '#ffffff' ); // => 255
isDark ( 'white' ); // => false
darken ( 'hsl(0, 5%, 100%)', 50 ); // => 'hsl(0, 5%, 50%)'
change ( '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	Get channel	Get more	Edit channel	Edit more
hex	channel	luminance	saturate	adjust
rgb	red	isDark	desaturate	change
rgba	green	isLight	lighten	invert
hsl	blue	isValid	darken	mix
hsla	hue		opacify	scale
	saturation		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.

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

rgba ( 255, 204, 0 ); // => '#ffcc00'
rgba ( 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.

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

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

Get _channel

These functions get a single channel from the provided color.

channel

Gets any single channel of the color.

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

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

red

Gets the red channel of the color.

function red ( color: string ): number;

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

green

Gets the green channel of the color.

function green ( color: string ): number;

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

blue

Gets the blue channel of the color.

function blue ( color: string ): number;

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

hue

Gets the hue channel of the color.

function hue ( color: string ): number;

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

saturation

Gets the saturation channel of the color.

function saturation ( color: string ): number;

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

lightness

Gets the lightness channel of the color.

function lightness ( color: string ): number;

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

alpha

Gets the alpha channel of the color.

function alpha ( color: string ): number;

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

opacity

Alias for alpha.

Get _more

These functions get some other information from the provided color.

luminance

Gets the relative luminance of the color.

function luminance ( color: string ): number;

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

isDark

Checks if the provided color is a dark color.

function isDark ( color: string ): number;

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

isLight

Checks if the provided color is a light color.

function isLight ( color: string ): number;

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

isValid

Checks if the provided color is a valid color.

function isLight ( color: string ): boolean;

isValid ( 'black' ); // => true
isLight ( '#ffcc00' ); // => true
isValid ( '#wtf' ); // => false

Edit _channel

These functions change a single channel of the provided color.

saturate

Increases the saturation channel of the color.

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

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

desaturate

Decreases the saturation channel of the color.

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

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

lighten

Increases the lightness channel of the color.

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

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

darken

Decreases the lightness channel of the color.

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

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

opacify

Increases the opacity channel of the color.

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

opacify ( '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.

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

transparentize ( '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.

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

rgba ( '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.

function complement ( color: string ): string;

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

grayscale

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

function grayscale ( color: string ): string;

grayscale ( '#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.

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

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

change

Sets a new value for any channel of the color.

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

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

invert

Gets the inverse of the color.

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

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

mix

Mixes two colors together.

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

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

scale

Scales any channel of the color.

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

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

License

MIT © Fabio Spampinato, Andrew Maney