Minimalist Color Manipulation Library – color2k

Preview:

Description:

A minimalist color manipulation library written in pure JavaScript.

color2k is a tiny (1.4kb), modular, feature-rich JavaScript color library to parse and manipulate colors in your web app.

Created with the use case of CSS-in-JS in mind and supports only RGBa and HSLa as outputs.

Installation:

# NPM
$ npm install color2k --save

How to use it:

• Adjust Hue
• Darken
• Desaturate
• Get Contrast
• Get Luminance
• Get Scale
• Guard
• Has Bad Contraste
• HSLA
• Lighten
• Mix
• Opacify
• Parse To Hsla
• Parse To Rgba
• Readable Color
• Readable Color Is Black
• RGBA
• Saturate
• Transparentize
• toHex
• toHsla
• toRgba

Adjust Hue Module:

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

• color: input color
• degrees: degrees to adjust the input color, accepts degree integers (0 – 360) and wraps around on overflow

import { adjustHue } from 'color2k';

// example
test('red 180', () => {
  expect(adjustHue('red', 180)).toMatchInlineSnapshot(
    `"hsla(180, 100%, 50%, 1)"`
  );
});

Darken Module:

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

• color: input color
• amount: amount the amount to darken, given as a decimal between 0 and 1

import { darken } from 'color2k';

test('darken black (no-op)', () => {
  expect(darken('black', 0.1)).toMatchInlineSnapshot(`"hsla(0, 0%, 0%, 1)"`);
});

Desaturate Module:

Desaturates the input color by the given amount via subtracting from the `s` in `hsla`. Possible parameters:

• color: input color
• amount: amount to desaturate, given as a decimal between 0 and 1

import { desaturate } from 'color2k';

test('red 10%', () => {
  expect(desaturate('red', 0.5)).toMatchInlineSnapshot(
    `"hsla(0, 50%, 50%, 1)"`
  );
});

Get Contrast Module:

Returns the contrast ratio between two colors. Possible parameters:

• color: input color

import { getContrast } from 'color2k';

it('should return the color contrast of two hex colors', () => {
  expect(getContrast('#444', '#fff')).toMatchInlineSnapshot(
    `9.739769120526205`
  );
});

Get Luminance Module:

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

• color: input color

import { getLuminance } from 'color2k';

it('should return the luminance of a hex color', () => {
  expect(getLuminance('#444')).toMatchInlineSnapshot(`0.05780543019106723`);
});

Get Scale Module:

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. Possible parameters:

• color: input color

import { getScale } from 'color2k';

test('red, green, blue', () => {
  const scale = getScale('red', 'yellow', 'green');
  expect(scale(0)).toMatchInlineSnapshot(`"rgba(255, 0, 0, 1)"`);
  expect(scale(0.1)).toMatchInlineSnapshot(`"rgba(255, 51, 0, 1)"`);
  expect(scale(0.2)).toMatchInlineSnapshot(`"rgba(255, 102, 0, 1)"`);
  expect(scale(0.3)).toMatchInlineSnapshot(`"rgba(255, 153, 0, 1)"`);
  expect(scale(0.4)).toMatchInlineSnapshot(`"rgba(255, 204, 0, 1)"`);
  expect(scale(0.5)).toMatchInlineSnapshot(`"rgba(255, 255, 0, 1)"`);
  expect(scale(0.6)).toMatchInlineSnapshot(`"rgba(204, 230, 0, 1)"`);
  expect(scale(0.7)).toMatchInlineSnapshot(`"rgba(153, 204, 0, 1)"`);
  expect(scale(0.8)).toMatchInlineSnapshot(`"rgba(102, 179, 0, 1)"`);
  expect(scale(0.9)).toMatchInlineSnapshot(`"rgba(51, 153, 0, 1)"`);
  expect(scale(1)).toMatchInlineSnapshot(`"rgba(0, 128, 0, 1)"`);
});

Guard Module:

A simple guard function. Possible parameters:

• low
• high
• value

import { guard } from 'color2k';

test('0 1 2', () => {
  expect(guard(0, 1, 2)).toBe(1);
});

Has Bad Contraste Module:

Returns whether or not a color has bad contrast according to a given standard. Possible parameters:

• color: input color
• standard: ‘decorative’ | ‘readable’ | ‘aa’ | ‘aaa’ = ‘aa’
• background: string = ‘#fff’

import { hasBadContrast } from 'color2k';

test('blue', () => {
  // blue should be fine for all of these
  expect(hasBadContrast('blue', 'decorative')).toBe(false);
  expect(hasBadContrast('blue', 'readable')).toBe(false);
  expect(hasBadContrast('blue', 'aa')).toBe(false);
  expect(hasBadContrast('blue', 'aaa')).toBe(false);
});

HSLA Module:

Takes in hsla parts and constructs an hsla string. Possible parameters:

• hue: The color circle (from 0 to 360) – 0 (or 360) is red, 120 is green, 240 is blue
• saturation: Percentage of saturation, given as a decimal between 0 and 1
• lightness: Percentage of lightness, given as a decimal between 0 and 1
• alpha: Percentage of opacity, given as a decimal between 0 and 1

import { hsla } from 'color2k';

test('hsla white', () => {
  expect(hsla(0, 1, 1, 1)).toMatchInlineSnapshot(`"hsla(0, 100%, 100%, 1)"`);
});

Lighten Module:

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

• color: input color
• amount: amount the amount to lighten, given as a decimal between 0 and 1

import { lighten } from 'color2k';

test('black', () => {
  expect(lighten('black', 0.1)).toMatchInlineSnapshot(`"hsla(0, 0%, 10%, 1)"`);
});

Mix Module:

Mixes two colors together. Taken from sass’s implementation. Possible parameters:

• Color 1
• Color 2
• Weight (number)

import { mix } from 'color2k';

test('mix red with white', () => {
  expect(mix('red', 'white', 0.5)).toMatchInlineSnapshot(
    `"rgba(255, 128, 128, 1)"`
  );
});

Opacify Module:

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

• color: input color
• amount: the amount to darken, given as a decimal between 0 and 1

import { opacify } from 'color2k';

it('works', () => {
  expect(opacify('rgba(255, 255, 255, 0.5)', 0.1)).toMatchInlineSnapshot(
    `"rgba(255, 255, 255, 0.6)"`
  );
});

Parse To Hsla Module:

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

• color: input color

import { parseToHsla } from 'color2k';

test('white', () => {
  expect(parseToHsla('white')).toMatchInlineSnapshot(`
    Array [
      0,
      0,
      1,
      1,
    ]
  `);
});

Parse To RGBA Module:

import { parseToRgba } from 'color2k';

test('white', () => {
  expect(parseToRgba('#0f08')).toMatchInlineSnapshot(`
    Array [
      0,
      255,
      0,
      0.5333333333333333,
    ]
  `);
});

Readable Color Module:

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

• color: input color

import { readableColor } from 'color2k';

it('readableColor white', () => {
  expect(readableColor('white')).toMatchInlineSnapshot(`"#000"`);
});

Readable Color Is Black Module:

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

• color: input color

import { readableColorIsBlack } from 'color2k';

test('contrastsWithWhite white', () => {
  expect(readableColorIsBlack('white')).toBe(true);
});

RGBA Module:

Takes in rgba parts and returns an RGB string. Possible parameters:

• red: The amount of red in the red channel, given in a number between 0 and 255 inclusive
• green: The amount of green in the red channel, given in a number between 0 and 255 inclusive
• blue: The amount of blue in the red channel, given in a number between 0 and 255 inclusive
• alpha: Percentage of opacity, given as a decimal between 0 and 1

import { rgba } from 'color2k';

test('red', () => {
  expect(rgba(255, 0, 0, 1)).toMatchInlineSnapshot(`"rgba(255, 0, 0, 1)"`);
});

Saturate Module:

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

• color: input color
• amount: the amount to darken, given as a decimal between 0 and 1

import { saturate } from 'color2k';

test('red 50%', () => {
  expect(saturate('hsl(0, 50%, 50%)', 0.1)).toMatchInlineSnapshot(
    `"hsla(0, 60%, 50%, 1)"`
  );
});

Transparentize Module:

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

• color: input color
• amount: the amount to darken, given as a decimal between 0 and 1

import { transparentize } from 'color2k';

it('works', () => {
  expect(transparentize('white', 0.1)).toMatchInlineSnapshot(
    `"rgba(255, 255, 255, 0.9)"`
  );
});

Convert color into Hex:

import { toHex } from 'color2k';

test('hex w/ transparency', () => {
  expect(toHex('#0000ff55')).toMatchInlineSnapshot(`"#0000ff55"`);
});

Convert color into Hsla:

import { toHsla } from 'color2k';

test('hex w/ transparency', () => {
  expect(toHsla('#00ff0080')).toMatchInlineSnapshot(
    `"hsla(120, 100%, 50%, 0.502)"`);
});

Convert color into Rgba:

import { Rgba } from 'color2k';

test('hex w/ transparency', () => {
  expect(toRgba('#00ff0080')).toMatchInlineSnapshot(`"rgba(0, 255, 0, 0.502)"`);
})

Changelog:

v2.0.3 (12/08/2023)

• corrected threshold for luminance

v2.0.2 (01/29/2023)

• bugfix

v2.0.1 (01/06/2023)

• Bugfix

v2.0.0 (02/13/2022)

• allow custom bg color in hasBadContrast
• conditional exports
• This package now includes conditional package exports. Most consumers should be able to upgrade without any issues, however, package exports limits the allowed entry points inside of Node.js and also affects consumption in other bundlers.

v1.2.5 (01/02/2022)

• Bug Fixes mix: return valid colors with transparent values at weight extremes

v1.2.4 (02/23/2021)

• fixednode 6 compatibility, again.

v1.2.3 (02/23/2021)

• fixednode 6 compatibility

v1.2.2 (02/01/2021)

• build: remove exports field for node.js stability

v1.2.1 (01/31/2021)

• fix incorrect common js main import

v1.2.0 (01/30/2021)

• Bug Fixes

v1.1.1 (10/31/2020)

• fixed toHex sometimes returns the wrong color

v1.1.0 (07/20/2020)

• adds 3 new functions to help you display any color as a string

v1.0.0 (07/20/2020)

• stable