🌈 color2k#

a color parsing and manipulation lib served in roughly 2kB or less (2.8kB 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.

The full bundle size is currently 2.8kB but gets as small as 2.1k with tree shaking.

Table of contents#

• Size comparison
• Installation
• Usage
• How so small?
• Trust and publishing
• Credits
• API

Size comparison#

👋 Compare tree-shaken bundle outputs on bundlejs.com

Installation#

Install with a package manager such as npm

npm i color2k

OR use with skypack.dev in supported environments (e.g. deno, modern browsers).

import { darken, transparentize } from 'https://cdn.skypack.dev/color2k?min';

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. Simplicity — only handles basic color manipulation functions
2. Less branching in code — only support two color models as outputs, namely rgba and hsla

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 😎.

Trust and publishing#

color2k is intentionally small and boring:

• Zero runtime dependencies.
• A narrow published package surface, limited to dist, README.md, LICENSE, and package.json.
• npm provenance is configured through trusted publishing for release builds.
• The README and docs site are generated from the JSDoc comments in src/*.ts.
• Security issues can be reported through the process in SECURITY.md.

Before publishing, maintainers should run the checks in docs/release-checklist.md.

Credits#

Heavy credit goes to polished.js and Sass. Much of the implementation of this lib is copied from polished.

API#

This section is generated from the JSDoc comments in src/*.ts.

adjustHue(color, degrees)#

function adjustHue(color: string, degrees: number): string

Rotates a color's hue by the given number of degrees and returns the result as an hsla string. Hue values wrap around the 0 to 360 degree color wheel.

adjustHue('red', 180); // 'hsla(180, 100%, 50%, 1)'

Parameters#

Returns#

string - The adjusted color as an hsla string.

Source

ColorError#

class ColorError extends Error

Error thrown when color2k cannot parse an input color.

new ColorError('nope').message; // 'Failed to parse color: "nope"'

Constructor Parameters#

Source

darken(color, amount)#

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

Darkens a color by subtracting from the lightness channel in HSL space.

darken('white', 0.1); // 'hsla(0, 0%, 90%, 1)'

Parameters#

Returns#

string - The darkened color as an hsla string.

Source

desaturate(color, amount)#

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

Desaturates a color by subtracting from the saturation channel in HSL space.

desaturate('red', 0.5); // 'hsla(0, 50%, 50%, 1)'

Parameters#

Returns#

string - The desaturated color as an hsla string.

Source

getContrast(color1, color2)#

function getContrast(color1: string, color2: string): number

Returns the contrast ratio between two colors based on the WCAG contrast ratio formula.

getContrast('#444', '#fff'); // 9.739769120526205

Parameters#

Returns#

number - The contrast ratio between the two colors.

Source

getLuminance(color)#

function getLuminance(color: string): number

Returns the relative luminance of a color using the WCAG formula.

getLuminance('papayawhip'); // 0.877971001998354

Parameters#

Returns#

number - A number between 0 for darkest black and 1 for lightest white.

Source

getScale(colors)#

function getScale(colors: string[]): (n: number) => string

Returns a scale function that interpolates through a list of colors.

The returned function accepts 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)

Parameters#

Returns#

(n: number) => string - A function that maps a decimal percentage to an rgba color.

Source

guard(low, high, value)#

function guard(low: number, high: number, value: number): number

Clamps a number between a lower and upper bound.

guard(0, 1, 2); // 1

Parameters#

Returns#

number - The clamped number.

Source

hasBadContrast(color, standard, background)#

function hasBadContrast(color: string, standard: 'decorative' | 'readable' | 'aa' | 'aaa' = 'aa', background: string = '#fff'): boolean

Returns whether a color fails a contrast threshold against a background.

The supported standards are decorative, readable, aa, and aaa.

hasBadContrast('red', 'aa'); // true

Parameters#

Returns#

boolean - true when the contrast ratio is below the selected standard.

Source

hsla(hue, saturation, lightness, alpha)#

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

Builds an hsla color string from hue, saturation, lightness, and alpha channel values.

hsla(0, 1, 0.5, 1); // 'hsla(0, 100%, 50%, 1)'

Parameters#

Returns#

string - An hsla color string.

Source

lighten(color, amount)#

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

Lightens a color by adding to the lightness channel in HSL space.

This is equivalent to darken(color, -amount).

lighten('black', 0.1); // 'hsla(0, 0%, 10%, 1)'

Parameters#

Returns#

string - The lightened color as an hsla string.

Source

mix(color1, color2, weight)#

function mix(color1: string, color2: string, weight: number): string

Mixes two colors together using the Sass mix algorithm and returns an rgba color string.

mix('red', 'blue', 0.5); // 'rgba(128, 0, 128, 1)'

Parameters#

Returns#

string - The mixed color as an rgba string.

Source

opacify(color, amount)#

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

Makes a color more opaque by increasing the alpha channel.

This is equivalent to transparentize(color, -amount).

opacify('rgba(255, 255, 255, 0.5)', 0.1); // 'rgba(255, 255, 255, 0.6)'

Parameters#

Returns#

string - The more opaque color as an rgba string.

Source

parseToHsla(color)#

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

Parses a color into hue, saturation, lightness, and alpha channel values.

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

parseToHsla('red'); // [0, 1, 0.5, 1]

Parameters#

Returns#

[number, number, number, number] - A tuple of hue, saturation, lightness, and alpha values.

Source

parseToRgba(color)#

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

Parses a color into red, green, blue, and alpha channel values.

Supports hex, RGB, RGBA, HSL, HSLA, CSS named colors, and transparent.

parseToRgba('rgba(255, 0, 0, 0.5)'); // [255, 0, 0, 0.5]

Parameters#

Returns#

[number, number, number, number] - A tuple of red, green, blue, and alpha channel values.

Source

readableColor(color)#

function readableColor(color: string): string

Returns black or white, whichever has better contrast against the given color.

readableColor('white'); // '#000'

Parameters#

Returns#

string - #000 or #fff.

Source

readableColorIsBlack(color)#

function readableColorIsBlack(color: string): boolean

Returns whether black is the more readable color to place on top of the input color.

This is the boolean form of readableColor.

readableColorIsBlack('white'); // true

Parameters#

Returns#

boolean - true when black is the more readable foreground color.

Source

rgba(red, green, blue, alpha)#

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

Builds an rgba color string from red, green, blue, and alpha channel values.

rgba(255, 0, 0, 1); // 'rgba(255, 0, 0, 1)'

Parameters#

Returns#

string - An rgba color string.

Source

saturate(color, amount)#

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

Saturates a color by adding to the saturation channel in HSL space.

This is equivalent to desaturate(color, -amount).

saturate('hsl(0, 50%, 50%)', 0.1); // 'hsla(0, 60%, 50%, 1)'

Parameters#

Returns#

string - The saturated color as an hsla string.

Source

toHex(color)#

function toHex(color: string): string

Converts a color to a hex color string.

Includes an alpha channel when the input color is not fully opaque.

toHex('palevioletred'); // '#db7093'

Parameters#

Returns#

string - A hex color string.

Source

toHsla(color)#

function toHsla(color: string): string

Converts a color to an hsla color string.

toHsla('peachpuff'); // 'hsla(28, 100%, 86%, 1)'

Parameters#

Returns#

string - An hsla color string.

Source

toRgba(color)#

function toRgba(color: string): string

Converts a color to an rgba color string.

toRgba('midnightblue'); // 'rgba(25, 25, 112, 1)'

Parameters#

Returns#

string - An rgba color string.

Source

transparentize(color, amount)#

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

Makes a color more transparent by decreasing the alpha channel.

transparentize('white', 0.1); // 'rgba(255, 255, 255, 0.9)'

Parameters#

Returns#

string - The more transparent color as an rgba string.

Source