Skip to content

gilbarbara/colorizr

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

42 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Colorizr

NPM version npm bundle size CI Maintainability Test Coverage

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