khroma

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

Usage no npm install needed!

<script type="module">
  import khroma from 'https://cdn.skypack.dev/khroma';
</script>

README

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 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 isValid 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)'

Convert

These functions convert supported colors to a specific format.

toKeyword

Convert a color to the keyword format, when possible.

function toKeyword ( color: string ): string | undefined;
channel ( '#ff0000' ); // => 'red'
channel ( '#ffcc00' ); // => undefined

toHex

Convert a color to the HEX format.

function toHex ( color: string ): string;
channel ( 'red' ); // => '#ff0000'
channel ( '#ff0000' ); // => '#ff0000'

toRgba

Convert a color to the RGBA format.

function toRgba ( color: string ): string;
channel ( 'red' ); // => 'rgb(255, 0, 0)'
channel ( '#ff0000' ); // => 'rgb(255, 0, 0)'
channel ( '#00000088' ); // => 'rgba(0, 0, 0, 0.5333333333)'

toHsla

Convert a color to the HSLA format.

function toHsla ( color: string ): string;
channel ( 'red' ); // => 'hsl(0, 100%, 50%)'
channel ( '#ff0000' ); // => 'hsl(0, 100%, 50%)'
channel ( '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.

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.

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.

function contrast ( color1: string, color2: string ): number;
contrast ( '#000000', '#000000' ); // => 1
contrast ( '#000000', '#ffffff' ); // => 10
contrast ( '#888888', '#ffffff' ); // => 4.0617165366

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