Colorizr

Color conversion, manipulation, comparison, and analysis.

Highlights

• 🏖 Easy to use: Works with HSL and RGB, including CSS strings
• ♿️ Accessibility: WCAG analysis and comparison.
• 🛠 Small: Less than 6k (gzipped) and zero dependencies.
• 🟦 Modern: Written in Typescript.

Setup

Install

npm install --save colorizr

Usage

import { luminance } from 'colorizr';

const lux = luminance('#ff0044'); // 0.2168

Or you can create an instance to access all methods:

import Colorizr from 'Colorizr';

const colorizr = new Colorizr('#ff0044');

Methods

String inputs accept css values: hex, rgb(a), hsl(a) and named colors.

brightnessDifference(left: string, right: string): number
get the brightness difference between 2 colors

import { brightnessDifference } from 'colorizr';

brightnessDifference('#fff', 'rgb(255, 0, 68)'); // 171.003

chroma(input: string): number
get the chroma of a color

import { chroma } from 'colorizr';

chroma('#ff0044'); // 1
chroma('#ffc0cb'); // 0.2471

colorDifference(left: string, right: string): number
get the color difference between 2 colors

import { colorDifference } from 'colorizr';

colorDifference('hsl(0, 0%, 100%)', '#f04'); // 442

compare(left: string, right: string): Analysis
get the WCAG analysis for two colors

import { compare } from 'colorizr';

compare('#ff0044', '#fff');

{
  "brightnessDifference": 171.003,
  "colorDifference": 442,
  "compliant": 1,
  "contrast": 3.94,
  "largeAA": true,
  "largeAAA": false,
  "normalAA": false,
  "normalAAA": false,
}

contrast(left: string, right: string): number
get the WCAG contrast ratio between 2 colors

import { contrast } from 'colorizr';

contrast('hsl(0, 0%, 100%)', 'rgb(255, 0, 68)'); // 3.94

darken(input: string, amount = 10): string
get a color with decreased lightness

import { darken } from 'colorizr';

darken('#ff0044', 10); // #cc0036

desaturate(input: string, amount: number): string
get a color with decreased saturation

import { desaturate } from 'colorizr';

desaturate('#ff0044', 10); // #f20d4a

fade(input: string, amount: number = 10, output?: ColorTypes = 'rgb'): string
get a transparent color

import { fade } from 'colorizr';

fade('hsl(344, 100, 50)', 10); // rgba(255, 0, 68, 0.9)
fade('#ff0044', 50, 'hsl'); // hsla(344, 100%, 50%, 0.5)

formatCSS(input: HSL | RGB, options?: FormatOptions): string
get the css string for a color model object

import { formatCSS } from 'colorizr';

formatCSS({ h: 344, s: 100, l: 50 }, { model: 'rgb' }); // 'rgb(255, 0, 68)'
formatCSS({ r: 255, g: 0, b: 68 }, { alpha: 0.5, model: 'hsl' }); // 'hsla(344, 100%, 50%, 0.5)'

formatHex(input: string): string
format a short hex string of 3 (or 4) digits into 6 (or 8) digits.

import { formatHex } from 'colorizr';

formatHex('#07e'); // '#0077ee'
formatHex('#f058'); // '#ff005588'

hex2hsl(input: string): HSL
convert a hex string into an HSL object

import { hex2hsl } from 'colorizr';

hex2hsl('#ff0044'); // { h: 344, s: 100, l: 50 }

hex2rgb(input: string): RGB
convert a hex string into an RGB object

import { hex2rgb } from 'colorizr';

hex2rgb('#ff0044'); // { r: 255, g: 0, b: 68 }

hsl2hex(input: HSL): string
convert an HSL object into a hex string

import { hsl2hex } from 'colorizr';

hsl2hex({ h: 344, s: 100, l: 50 }); // '#ff0044'

hsl2rgb(input: HSL): RGB
convert an HSL object into an RGB object

import { hsl2rgb } from 'colorizr';

hsl2rgb({ h: 344, s: 100, l: 50 }); // { r: 255, g: 0, b: 68 }

isValidColor(input: any): boolean
check if the input can be parsed correctly

import { isValidColor } from 'colorizr';

isValidColor('#f04'); // true
isValidColor('#ff0044'); // true
isValidColor('#ff004400'); // true
isValidColor('rgb(100, 255, 0)'); // true
isValidColor('hsla(344, 100%, 50%)'); // true
isValidColor('blue'); // true
isValidColor('aliceblue'); // true
isValidColor('#mmff00'); // false
isValidColor('blue-ish'); // false

isValidHex(input: any): boolean
check if the input is a valid hex

import { isValidHex } from 'colorizr';

isValidHex('#f04'); // true

lighten(input: string, amount: number): string
get a color with increased lightness

import { lighten } from 'colorizr';

lighten('#ff0044', 10); // #ff3369

luminance(input: string): number
get the relative brightness according to the WCAG definition. Normalized to 0 for black and 1 for white.

import { luminance } from 'colorizr';

luminance('#ff0044'); // 0.2168

name(input: string): string
get the named color. return the hex code if it can't be named

import { name } from 'colorizr';

name('#ffc0cb', 10); // pink
name('rgb(176, 224, 230)'); // 'powderblue'
name('hsl(344, 100, 50)'); // #ff0044

palette(input: string, options?: PaletteOptions): string[]
get a palette for a color

import { palette } from 'colorizr';

palette('#ff0044');
// ['#ff0044', '#ff7700', '#88ff00', '#00ff77', '#0088ff', '#7700ff'];

palette('#ff0044', { type: 'monochromatic' });
// ['#ff99b4', '#ff5582', '#ff1150', '#cc0036', '#880024', '#440012']

parseCSS(input: string, output: ColorTypes = 'hex'): string | HSL | RGB
parse a css string to hex, hsl, or RGB

import { parseCSS } from 'colorizr';

parseCSS('hsl(270 60% 70%)'); // '#b385e0'
parseCSS('#ff0044', 'hsl'); // { h: 344, l: 50, s: 100 }

random(): string
get a random color

import { random } from 'colorizr';

random(); // '#b385e0'

rgb2hex(input: RGB | RGBArray): string
convert an RGB object into a hex string

import { rgb2hex } from 'colorizr';

rgb2hex({ r: 255, g: 55, b: 75 }); // '#ff374b'
rgb2hex([255, 0, 68]); // '#ff0044'

rgb2hsl(input: RGB | RGBArray): HSL
convert an RGB object into an HSL object

import { rgb2hsl } from 'colorizr';

rgb2hsl({ r: 255, g: 55, b: 75 }); // { h: 354, s: 100, l: 60.78 }
rgb2hsl([255, 0, 68]); // { h: 344, s: 100, l: 50 }

rotate(input: string, degrees = 15): string get a color with changed hue

import { rotate } from 'colorizr';

rotate('#ff0044', 30); // #ff3b00

saturate(input: string, amount: number): string
get a color with increased saturation

import { saturate } from 'colorizr';

saturate('#ff0044', 10); // #ff0044 (already at the maximum)
saturate('pink', 10); // #ffc0cb

scheme(input: string, type: Scheme): string[]
get the scheme for a color

import { scheme } from 'colorizr';

const complementary = scheme('rgb(255, 0, 68)'); // ['#ff0044', '#00ffbb']
const triadic = scheme('#ff0044', 'triadic'); // ['#ff0044', '#44ff00', '#0044ff']

textColor(input: string): string
get a contrasting color to use with the text

import { textColor } from 'colorizr';

textColor('#ff0044'); // #ffffff
textColor('#fff800'); // #000000

Instance API

import Colorizr from 'Colorizr';

const colorizr = new Colorizr('#ff0044');

colorizr.hex; // #ff0044
colorizr.hsl; // { h: 344, s: 100, l: 50 };
colorizr.rgb; // { r: 255, g: 0, b: 68 };

Getters

colorizr.hex
returns the hex

colorizr.hsl
returns the HSL object

colorizr.rgb
returns the RGB object

colorizr.hue
returns the color hue, between 0 and 360

colorizr.saturation
returns the color saturation, between 0 and 100

colorizr.lightness
returns the color lightness, between 0 and 100

colorizr.red
returns the color red level, between 0 and 255

colorizr.green
returns the color green level, between 0 and 255

colorizr.blue
returns the color blue level, between 0 and 255

colorizr.luminance

colorizr.chroma

colorizr.textColor

Manipulation

colorizr.lighten(percentage = 10)

colorizr.darken(percentage = 10)

colorizr.saturate(percentage = 10)

colorizr.saturate(percentage = 10)

colorizr.rotate(degrees = 15)

colorizr.invert()

colorizr.fade(percentage = 10)

Comparison

colorizr.compare(color: string)
returns an object with the analysis (check the compare output above)

References

calculating-color-contrast
Colour Contrast Check
Contrast Checker
Converting Color Spaces in typescript