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’

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:

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