colorblender

A powerful and fully typed color library.

Features

• Fully typed - Written in TypeScript
• Tiny - Less than 3kb gzipped (without plugins)
• Fast - 3x faster than the most popular color library
• Simple - Chainable methods
• Complete - Supports a lot of color models
• Conversion - Convert between any of the supported color models
• Extension - Extend the library with others color models, manipulation, and analysis methods
• Support - Support all browsers and Node.js

Installation

npm install colorblender

Import

import { colorblender } from 'colorblender';

Usage

Create colorblender instance

// Random Color
colorblender();
// HEX
colorblender('#FFF');
colorblender('#FFFFFF');
colorblender('#FFFFFFFF');
// RGB
colorblender({ r: 255, g: 255, b: 255 });
colorblender({ r: 255, g: 255, b: 255, a: 1 });
// HSL
colorblender({ h: 360, s: 100, l: 100 });
colorblender({ h: 360, s: 100, l: 100, a: 1 });
// HSV
colorblender({ h: 360, s: 100, v: 100 });
colorblender({ h: 360, s: 100, v: 100, a: 1 });
// Gray
colorblender({ gray: 100 });
// HWB (with extension hwb)
colorblender({ h: 0, w: 100, b: 0 });
colorblender({ h: 0, w: 100, b: 0, a: 1 });
// HCG (with extension hcg)
colorblender({ h: 0, c: 0, g: 100 });
colorblender({ h: 0, c: 0, g: 100, a: 1 });
// CMYK (with extension cmyk)
colorblender({ c: 0, m: 0, y: 0, k: 0 });
colorblender({ c: 0, m: 0, y: 0, k: 0, a: 1 });
// XYZ (with extension xyz)
colorblender({ x: 95, y: 100, z: 108.9 });
colorblender({ x: 95, y: 100, z: 108.9, a: 1 });
// LAB (with extension lab)
colorblender({ l: 100, a: 0, b: 0 });
colorblender({ l: 100, a: 0, b: 0, alpha: 1 }); // for lab, you need to use alpha instead of a
// LCH (with extension lch)
colorblender({ l: 100, c: 0, h: 0 });
colorblender({ l: 100, c: 0, h: 0, a: 1 });
// Ansi16 (with extension ansi)
colorblender({ ansi16: 97 });
// Ansi256 (with extension ansi)
colorblender({ ansi256: 231 });
// RAL (with extension ral)
colorblender('9010');
// HKS (with extension hks)
colorblender('81-K');
// Copic (with extension copic)
colorblender('Colorless Blender 0');
// PrismaColor (with extension prismacolor)
colorblender('White PC 938');
// Name (with extension name)
colorblender('White');
// Keyword (with extension keyword)
colorblender('white');

Methods

Conversion

.hex()

colorblender({ r: 255, g: 255, b: 255 }).hex(); // #FFFFFF
colorblender({ r: 255, g: 255, b: 255, a: 0.5 }).hex(); // #FFFFFF80

.rgb(raw = false)

colorblender('#FFF').rgb(); // { r: 255, g: 255, b: 255, a: 1 }
colorblender('#FFFFFF80').rgb(); // { r: 255, g: 255, b: 255, a: 0.5 }

.rgbNumber()

colorblender('#FFF').rgbNumber(); // 16777215

.rgbString(format: 'css' | 'default')

colorblender('#FFF').rgbString(); // 255, 255, 255
colorblender('#FFFFFF80').rgbString(); // 255, 255, 255, 0.5
colorblender('#FFF').rgbString('css'); // rgb(255, 255, 255)
colorblender('#FFFFFF80').rgbString('css'); // rgba(255, 255, 255, 0.5)

.hsl(raw = false)

colorblender('#FFF').hsl(); // { h: 0, s: 0, l: 100, a: 1 }
colorblender('#FFFFFF80').hsl(); // { h: 0, s: 0, l: 100, a: 0.5 }
colorblender({ r: 167, g: 40, b: 13 }).hsv(true); // { h: 10.51948051948052, s: 85.55555555555554, l: 35.294117647058826, a: 1 }

.hslString(format: 'css' | 'default')

colorblender('#FFF').hslString(); // 0°, 0%, 100%
colorblender('#FFFFFF80').hslString(); // 0°, 0%, 100%, 0.5
colorblender('#FFF').hslString('css'); // hsl(0, 0%, 100%)
colorblender('#FFFFFF80').hslString('css'); // hsla(0, 0%, 100%, 0.5)

.hsv(raw = false)

colorblender('#FFF').hsv(); // { h: 0, s: 0, v: 100, a: 1 }
colorblender('#FFFFFF80').hsv(); // { h: 0, s: 0, v: 100, a: 0.5 }
colorblender({ r: 167, g: 40, b: 13 }).hsv(true); // { h: 10.519480519480492, s: 92.21556886227545, v: 65.49019607843137, a: 1 }

.hsvString()

colorblender('#FFF').hslString(); // 0°, 0%, 100%
colorblender('#FFFFFF80').hslString(); // 0°, 0%, 100%, 0.5

.gray(raw = false)

colorblender({ r: 167, g: 40, b: 13 }).gray(); // { gray: 29 }

.hwb(raw = false) extension hwb

colorblender({ r: 167, g: 40, b: 13 }).hwb(); // { h: 11, w: 5, b: 35, a: 1 }
colorblender({ r: 167, g: 40, b: 13, a: 0.5 }).hwb(); // { h: 11, w: 5, b: 35, a: 0.5 }
colorblender({ r: 167, g: 40, b: 13 }).hwb(true); // { h: 10.51948051948052, w: 5.098039215686274, b: 34.509803921568626, , a: 1 }

.hwbString(format: 'css' | 'default') extension hwb

colorblender('#FFF').hwbString(); // 0°, 100%, 0%
colorblender('#FFFFFF80').hwbString(); // 0°, 100%, 0%, 0.5
colorblender('#FFF').hwbString('css'); // hwb(0 100% 0%)
colorblender('#FFFFFF80').hwbString('css'); // hwb(0 100% 0% / 0.5)

.hcg(raw = false) extension hcg

colorblender({ r: 167, g: 40, b: 13 }).hcg(); // { h: 11, c: 60, g: 13, a: 1 }
colorblender({ r: 167, g: 40, b: 13, a: 0.5 }).hcg(); // { h: 11, c: 60, g: 13, a: 0.5 }
colorblender({ r: 167, g: 40, b: 13 }).hcg(true); // { h: 10.519480519480519, c: 60.3921568627451, g: 12.871287128712869, , a: 1 }

.hcgString() extension hcg

colorblender('#FFF').hcgString(); // 0°, 0%, 0%
colorblender('#FFFFFF80').hcgString(); // 0°, 0%, 0%, 0.5

.cmyk(raw = false) extension cmyk

colorblender({ r: 167, g: 40, b: 13 }).cmyk(); // { c: 0, m: 76, y: 92, k: 35, a: 1 }
colorblender({ r: 167, g: 40, b: 13, a: 0.5 }).cmyk(); // { c: 0, m: 76, y: 92, k: 35, a: 0.5 }
colorblender({ r: 167, g: 40, b: 13 }).cmyk(true); // { c: 0, m: 76.04790419161677, y: 92.21556886227545, k: 34.509803921568626, , a: 1 }

.cmykString(format: 'css' | 'default') extension cmyk

colorblender('#FFF').cmykString(); // 0%, 0%, 0%, 0%
colorblender('#FFFFFF80').cmykString(); // 0%, 0%, 0%, 0%, 0.5
colorblender('#FFF').cmykString('css'); // device-cmyk(0% 0% 0% 0%)
colorblender('#FFFFFF80').cmykString('css'); // device-cmyk(0% 0% 0% 0% / 0.5)

.xyz(raw = false) extension xyz

colorblender({ r: 167, g: 40, b: 13 }).xyz(); // { x: 17, y: 10, z: 1, a: 1 }
colorblender({ r: 167, g: 40, b: 13, a: 0.5 }).xyz(); // { x: 17, y: 10, z: 1, a: 0.5 }
colorblender({ r: 167, g: 40, b: 13 }).xyz(true); // { x: 16.769891396698043, y: 9.764837423188144, z: 1.382502939864886, a: 1 }

.xyzString() extension xyz

colorblender('#FFF').xyzString(); // 95, 100, 108.9
colorblender('#FFFFFF80').xyzString(); // 95, 100, 108.9, 0.5

.lab(raw = false) extension lab

colorblender({ r: 167, g: 40, b: 13 }).lab(); // { l: 37, a: 50, b: 45, alpha: 1 }
colorblender({ r: 167, g: 40, b: 13, a: 0.5 }).lab(); // { l: 37, a: 50, b: 45, alpha: 0.5 }
colorblender({ r: 167, g: 40, b: 13 }).lab(true); // { l: 37.41702066350787, a: 50.19034131619138, b: 45.43968063599927, alpha: 1 }

.labString(format: 'css' | 'default') extension lab

colorblender('#FFF').labString(); // 100%, 0, 0
colorblender('#FFFFFF80').labString(); // 100%, 0, 0, 0.5
colorblender('#FFF').labString('css'); // lab(100% 0 0)
colorblender('#FFFFFF80').labString('css'); // lab(100% 0 0 / 0.5)

.lch(raw = false) extension lch

colorblender({ r: 167, g: 40, b: 13 }).lch(); // { l: 37, c: 68, h: 42, a: 1 }
colorblender({ r: 167, g: 40, b: 13, a: 0.5 }).lch(); // { l: 37, c: 68, h: 42, a: 0.5 }
colorblender({ r: 167, g: 40, b: 13 }).lch(true); // { l: 37.41702066350787, c: 67.70402453131862, h: 42.156026720919115, a: 1 }

.lchString(format: 'css' | 'default') extension lch

colorblender('#FFF').lchString(); // 100%, 0, 0
colorblender('#FFFFFF80').lchString(); // 100%, 0, 0, 0.5
colorblender('#FFF').lchString('css'); // lch(100% 0 0)
colorblender('#FFFFFF80').lchString('css'); // lch(100% 0 0 / 0.5)

.ansi16() extension ansi

colorblender({ r: 167, g: 40, b: 13 }).ansi16(); // { ansi16: 31 }

.ansi256() extension ansi

colorblender({ r: 167, g: 40, b: 13 }).ansi256(); // { ansi256: 130 }

.apple(raw = false) extension apple

colorblender({ r: 167, g: 40, b: 13 }).apple(); // { r: 42919, g: 10280, b: 3341, a: 1 }

.ral() extension ral

colorblender({ r: 167, g: 40, b: 13 }).ral(); // "3013"

.hks() extension hks

colorblender({ r: 167, g: 40, b: 13 }).hks(); // "82-K"

.copic() extension copic

colorblender({ r: 167, g: 40, b: 13 }).copic(); // "Burnt Umber E29"

.prismacolor() extension prismacolor

colorblender({ r: 167, g: 40, b: 13 }).prismacolor(); // "Terra Cotta PC 944"

.name() extension name

colorblender({ r: 167, g: 40, b: 13 }).name(); // Tabasco

.keyword() extension keyword

colorblender({ r: 167, g: 40, b: 13 }).keyword(); // firebrick

Manipulation

.alpha(value: number)

colorblender({ r: 167, g: 40, b: 13 }).alpha(0.5).rgb(); // { r: 167, g: 40, b: 13, a: 0.5 }

.hue(value: number)

colorblender({ r: 167, g: 40, b: 13 }).hue(20).rgb(); // { r: 166, g: 64, b: 13, a: 1 }

.negate()

colorblender({ r: 167, g: 40, b: 13 }).negate().rgb(); // { r: 88, b: 242, g: 215, a: 1 }

.brighten(ratio: number)

colorblender({ r: 167, g: 40, b: 13 }).brighten(0.2).rgb(); // { r: 185, b: 61, g: 83, a: 1 }

.lighten(ratio: number)

colorblender({ r: 167, g: 40, b: 13 }).lighten(0.2).rgb(); // { r: 200, b: 16, g: 48, a: 1 }

.darken(ratio: number)

colorblender({ r: 167, g: 40, b: 13 }).darken(0.2).rgb(); // { r: 134, b: 10, g: 32, a: 1 }

.saturate(ratio: number)

colorblender({ r: 167, g: 40, b: 13 }).saturate(0.2).rgb(); // { r: 180, b: 0, g: 32, a: 1 }

.desaturate(ratio: number)

colorblender({ r: 167, g: 40, b: 13 }).desaturate(0.2).rgb(); // { r: 152, b: 50, g: 28, a: 1 }

.fade(ratio: number)

colorblender({ r: 167, g: 40, b: 13, a: 1 }).fade(0.2).alpha(); // 0.8

.opaquer(ratio: number)

colorblender({ r: 167, g: 40, b: 13, a: 0.5 }).opaquer(0.2).alpha(); // 0.6

.temperature()

colorblender({ r: 167, g: 40, b: 13 }).temperature(-30).rgb(); // { r: 121, b: 59, g: 32, a: 1 }

.complement()

colorblender({ r: 167, g: 40, b: 13 }).complement().hex(); // #0D8CA7

.grayscale()

colorblender({ r: 167, g: 40, b: 13 }).grayscale().rgb(); // { r: 75, b: 75, g: 75, a: 1 }

.rotate(amount = 15)

colorblender({ r: 167, g: 40, b: 13 }).rotate(20).hue(); // 31

.whiten(ratio: number) extension hwb

colorblender({ r: 167, g: 40, b: 13 }).whiten(0.2).rgb(); // { r: 167, b: 16, g: 42 }

.blacken(ratio: number) extension hwb

colorblender({ r: 167, g: 40, b: 13 }).blacken(0.2).rgb(); // { r: 149, b: 13, g: 37 }

.tinten(ratio: number) extension hcg

colorblender({ r: 167, g: 40, b: 13 }).tinten(0.5).hex(); // #AD2F13

.shaden(ratio: number) extension hcg

colorblender({ r: 167, g: 40, b: 13 }).shaden(0.5).hex(); // #A12206

.negateTones() extension hcg

colorblender({ r: 167, g: 40, b: 13 }).negateTones().hex(); // #F27358

.mix(color: AnyColor | Colorblender, weight = 0.5) extension mix

colorblender({ r: 167, g: 40, b: 13 })
  .mix({ r: 28, g: 252, b: 185 }, 0.2)
  .hex(); // #629263

.mixPalette(color: AnyColor | Colorblender, amount: number) extension mix

colorblender({ r: 167, g: 40, b: 13 })
  .mixPalette({ r: 28, g: 252, b: 185 }, 5)
  .map((c) => c.hex());
// [
//   '#904B2A',
//   '#796F46',
//   '#629263',
//   '#4AB580',
//   '#33D99C',
// ]

.tints(amount: number) extension mix

colorblender({ r: 167, g: 40, b: 13 })
  .tints(5)
  .map((c) => c.hex());
// [
//   '#B64C35',
//   '#C4705E',
//   '#D39486',
//   '#E2B7AE',
//   '#F0DBD7',
// ]

.shades(amount: number) extension mix

colorblender({ r: 167, g: 40, b: 13 })
  .shades(5)
  .map((c) => c.hex());
// [
//   '#8B210B',
//   '#6F1B09',
//   '#541407',
//   '#380D04',
//   '#1C0702',
// ]

.tones(amount: number) extension mix

colorblender({ r: 167, g: 40, b: 13 })
  .tones(5)
  .map((c) => c.hex());
// [
//   '#A13720',
//   '#9A4533',
//   '#945447',
//   '#8D635A',
//   '#87716D',
// ]

.harmonies(type: HarmonyType) extension harmony

colorblender({ r: 167, g: 40, b: 13 })
  .harmonies('analogous')
  .map((c) => c.hex()); // ['#A70D3F', '#A7280D', '#A7750D']

colorblender({ r: 167, g: 40, b: 13 })
  .harmonies('complementary')
  .map((c) => c.hex()); // ['#A7280D', '#0D8CA7']

colorblender({ r: 167, g: 40, b: 13 })
  .harmonies('split-complementary')
  .map((c) => c.hex()); // ['#A7280D', '#0DA775', '#0D3FA7']

colorblender({ r: 167, g: 40, b: 13 })
  .harmonies('double-split-complementary')
  .map((c) => c.hex()); // ['#A70D3F', '#A7280D', '#A7750D', '#0DA775', '#0D3FA7']

colorblender({ r: 167, g: 40, b: 13 })
  .harmonies('tetradic')
  .map((c) => c.hex()); // ['#A7280D', '#3FA70D', '#0D8CA7', '#750DA7']

colorblender({ r: 167, g: 40, b: 13 })
  .harmonies('triadic')
  .map((c) => c.hex()); // ['#A7280D', '#0DA728', '#280DA7']

colorblender({ r: 167, g: 40, b: 13 })
  .harmonies('rectangle')
  .map((c) => c.hex()); // ['#A7280D', '#8CA70D', '#0D8CA7', '#280DA7']

Analysis

.isValid()

colorblender({ r: 167, g: 40, b: 13 }).isValid(); // true
colorblender({ r: 167, g: 40, a: 13 }).isValid(); // false

.isDark()

colorblender({ r: 0, g: 0, b: 0 }).isDark(); // true
colorblender({ r: 255, g: 255, b: 255 }).isDark(); // false

.isLight()

colorblender({ r: 0, g: 0, b: 0 }).isLight(); // false
colorblender({ r: 255, g: 255, b: 255 }).isLight(); // true

.isEqual(color: AnyColor | Colorblender)

colorblender({ r: 0, g: 0, b: 0 }).isEqual({ r: 255, g: 255, b: 255 }); // false
colorblender({ r: 255, g: 255, b: 255 }).isEqual('#FFF'); // true
colorblender({ r: 255, g: 255, b: 255 }).isEqual(colorblender('#FFF')); // true

.brightness(raw = false)

colorblender({ r: 167, g: 40, b: 13 }).brightness(); // 0.29
colorblender({ r: 167, g: 40, b: 13 }).brightness(true); // 0.29370588235294115

.alpha()

colorblender({ r: 167, g: 40, b: 13, a: 0.59 }).alpha(); // 0.59

.hue()

colorblender({ r: 167, g: 40, b: 13 }).hue(); // 11

.luminosity() extension a11y

colorblender({ r: 167, g: 40, b: 13 }).luminosity(); // 0.0976213184127798

.contrast(color: AnyColor | Colorblender) extension a11y

colorblender({ r: 167, g: 40, b: 13 }).contrast({ r: 28, g: 252, b: 185 }); // 5.308885390786212

.isReadable(color: AnyColor | Colorblender, options: ReadabilityOptions) extension a11y

interface ReadabilityOptions {
  level?: 'AA' | 'AAA';
  size?: 'normal' | 'large';
}

colorblender({ r: 167, g: 40, b: 13 }).isReadable(
  { r: 28, g: 252, b: 185 },
  {
    level: 'AAA',
    size: 'large',
  },
); // true

Extensions

extend(extensions: Extension[])

import { hwbExtension } from 'colorblender/extensions/hwb';
import { mixExtension } from 'colorblender/extensions/mix';

extend([hwbExtension, mixExtension]);

• hwb - HWB color model 0.86kb
• hcg - HCG color model 1.5kb
• cmyk - CMYK color model 0.5kb
• xyz - XYZ color model 0.72kb
• keyword - Color to keyword (148 keywords) 3.97kb
• lab - LAB color model 1.1kb
• lch - LCH color model 1.1kb
• name - Color to name (1566 names) 32.3kb
• mix - Mix colors and create palettes 0.52kb
• a11y - Accessibility analysis 0.48kb
• harmony - Color harmonies 0.34kb
• ansi - ANSI color models 1.48kb
• apple - APPLE color models 0.4kb
• ral - RAL color models 4.13kb
• hks - HKS color models 6.12kb
• copic - Copic color models 10.7kb
• prismacolor - PrismaColor color models 5.67kb

Issues

Please file an issue for bugs, missing documentation, or unexpected behavior.

File an issue

License

MIT

Credits

The API was inspired by color and colord libraries.