color2k
bundlephobia github status checks codecov

a color parsing and manipulation lib served in 2kB or less (1.4kB to be more precise)

color2k is a color parsing and manipulation library with the objective of keeping the bundle size as small as possible while still satisfying all of your color manipulation needs in an sRGB space (wide-gamut is not supported).

The bundle size is currently 1.4kB

Size comparison

lib size
polished 11.2kB
chroma-js 13.7kB
color 7.6kB
tinycolor2 5kB
color2k 1.4kB 😎

Installation

npm i --save color2k

If you need to server-side render any colors, you also need to install the node/ssr compatibility package.

# needed in non-browser environments (e.g. gatsby, next.js)
npm i --save @color2k/compat

Usage

import { darken, transparentize } from 'color2k';

// e.g.
darken('blue', 0.1);
transparentize('red', 0.5);

How so small?

There are two secrets that keep this lib especially small:

  1. defer to the browser to parse colors via getComputedStyle
  2. only support two color models as outputs, namely rgba and hsla

Why getComputedStyle?

The browser already has the ability to parse colors via getComputedStyle. Other color libs use javascript to parse and transform colors. The result of making the browser parse the color is the removal of any code related to parsing colors resulting in a significantly smaller bundle.

Why not getComputedStyle?

Using getComputedStyle is slower than parsing via javascript.

On my 2019 MacBook Pro:

  • getComputedStyle: 594,499 ops/sec
  • JavaScript: 3,335,123 ops/sec

See here

In order to increase performance, already computed colors are cached.

Why only rgba and hsla as outputs?

This lib was created with the use case of CSS-in-JS in mind. At the end of the day, all that matters is that the browser can understand the color string you gave it as a background-color.

Because only those two color models are supported, we don't have to add code to deal with optional alpha channels or converting to non-browser supported color models (e.g. CMYK).

We believe that this lib is sufficient for all of your color manipulation needs. If we're missing a feature, feel free to open an issue 😎.

Credits

Heavy credits goes to polished.js and sass. Much of the implementation of this lib is copied from polished!

adjustHue(color, degrees): string

Adjusts the current hue of the color by the given degrees. Wraps around when over 360.

ParamTypeDescription
colorstringinput color
degreesnumberdegrees to adjust the input color, accepts degree integers (0 - 360) and wraps around on overflow
Go to implementation β†’

darken(color, amount): string

Darkens using lightness. This is equivalent to subtracting the lightness from the L in HSL.

ParamTypeDescription
colorstring
amountnumberthe amount to darken, given as a decimal between 0 and 1
Go to implementation β†’

desaturate(color, amount): string

Desaturates the input color by the given amount via subtracting from the s in hsla.

ParamTypeDescription
colorstring
amountnumberamount to desaturate, given as a decimal between 0 and 1
Go to implementation β†’

getContrast(color1, color2): number

Returns the contrast ratio between two colors based on W3's recommended equation for calculating contrast.

ParamType
color1string
color2string
Go to implementation β†’

getLuminance(color): number

Returns a number (float) representing the luminance of a color.

ParamType
colorstring
Go to implementation β†’

getScale(colors): (n: number) => string

Given a series colors, this function will return a scale(x) function that accepts a percentage as a decimal between 0 and 1 and returns the color at that percentage in the scale.

const scale = getScale('red', 'yellow', 'green');
console.log(scale(0)); // rgba(255, 0, 0, 1)
console.log(scale(0.5)); // rgba(255, 255, 0, 1)
console.log(scale(1)); // rgba(0, 128, 0, 1)

If you'd like to limit the domain and range like chroma-js, we recommend wrapping scale again.

const _scale = getScale('red', 'yellow', 'green');
const scale = x => _scale(x / 100);

console.log(scale(0)); // rgba(255, 0, 0, 1)
console.log(scale(50)); // rgba(255, 255, 0, 1)
console.log(scale(100)); // rgba(0, 128, 0, 1)
ParamType
colorsstring[]
Go to implementation β†’

guard(low, high, value): number

A simple guard function:

Math.min(Math.max(low, value), high)
ParamType
lownumber
highnumber
valuenumber
Go to implementation β†’

hasBadContrast(color, standard): boolean

Returns whether or not a color has bad contrast according to a given standard

ParamType
colorstring
standard'decorative' | 'readable' | 'aa' | 'aaa' = 'aa'
Go to implementation β†’

hsla(hue, saturation, lightness, alpha): string

Takes in hsla parts and constructs an hsla string

ParamTypeDescription
huenumberThe color circle (from 0 to 360) - 0 (or 360) is red, 120 is green, 240 is blue
saturationnumberPercentage of saturation, given as a decimal between 0 and 1
lightnessnumberPercentage of lightness, given as a decimal between 0 and 1
alphanumberPercentage of opacity, given as a decimal between 0 and 1
Go to implementation β†’

lighten(color, amount): string

Lightens a color by a given amount. This is equivalent to darken(color, -amount)

ParamTypeDescription
colorstring
amountnumberthe amount to darken, given as a decimal between 0 and 1
Go to implementation β†’

mix(color1, color2, weight): string

Mixes two colors together. Taken from sass's implementation.

ParamType
color1string
color2string
weightnumber
Go to implementation β†’

opacify(color, amount): string

Takes a color and un-transparentizes it. Equivalent to transparentize(color, -amount)

ParamTypeDescription
colorstring
amountnumberthe amount to darken, given as a decimal between 0 and 1
Go to implementation β†’

parseToHsla(color): [number, number, number, number]

Parses a color in hue, saturation, lightness, and the alpha channel.

Hue is a number between 0 and 360, saturation, lightness, and alpha are decimal percentages between 0 and 1

ParamType
colorstring
Go to implementation β†’

parseToRgba(color): [number, number, number, number]

Takes in any color and parses it in to red, green, blue, and alpha channels.

The red, green, and blue channels have values between 0 and 255. The alpha channel is returned as a decimal between 0 and 1.

ParamType
colorstring
Go to implementation β†’

readableColor(color): string

Returns black or white for best contrast depending on the luminosity of the given color.

ParamType
colorstring
Go to implementation β†’

readableColorIsBlack(color): boolean

An alternative function to readableColor. Returns whether or not the readable color (i.e. the color to be place on top the input color) should be black.

ParamType
colorstring
Go to implementation β†’

rgba(red, green, blue, alpha): string

Takes in rgba parts and returns an rgba string

ParamTypeDescription
rednumberThe amount of red in the red channel, given in a number between 0 and 255 inclusive
greennumberThe amount of green in the red channel, given in a number between 0 and 255 inclusive
bluenumberThe amount of blue in the red channel, given in a number between 0 and 255 inclusive
alphanumberPercentage of opacity, given as a decimal between 0 and 1
Go to implementation β†’

saturate(color, amount): string

Saturates a color by converting it to hsl and increasing the saturation amount. Equivalent to desaturate(color, -amount)

ParamTypeDescription
colorstringthe input color
amountnumberthe amount to darken, given as a decimal between 0 and 1
Go to implementation β†’

transparentize(color, amount): string

Takes in a color and makes it more transparent by convert to rgba and decreasing the amount in the alpha channel.

ParamTypeDescription
colorstring
amountnumberthe amount to darken, given as a decimal between 0 and 1
Go to implementation β†’