molefrog/colord

Colord is a tiny yet powerful tool for high-performance color manipulations and conversions.

Features

📦 Small: Just 1.4 KB gzipped (3x+ lighter than color and tinycolor2)
🚀 Fast: 2x+ faster than color and tinycolor2
😍 Simple: Chainable API and familiar patterns
💪 Immutable: No need to worry about data mutations
🛡 Bulletproof: Written in strict TypeScript and 100% covered by tests
🗂 Typed: All types are available out of the box
🏗 Extendable: Built-in plugin system to add new functionality
👫 Works everywhere: Supports all browsers and Node.js
💨 Dependency-free

Benchmarks

Library	Operations/sec	Size (minified)	Size (gzipped)	Dependencies	Type declarations
colord 👑	2,274,420
color	717,048
tinycolor2	956,285
ac-colors	637,469
chroma-js	900,826

The performance results were generated on a MBP 2019, 2,6 GHz Intel Core i7 via running npm run benchmark in the library folder. See tests/benchmark.ts.

Getting Started

npm i colord

import { colord } from "colord";

colord("#ff0000").grayscale().alpha(0.25).toRgbaString(); // "rgba(128, 128, 128, 0.25)"
colord("rgb(192, 192, 192)").isLight(); // true
colord("hsl(0, 50%, 50%)").darken(0.25).toHex(); // "#602020"

API

Color parsing

Accepted input formats

Hexadecimal strings (including 3, 4 and 8 digit notations)
RGB(A) strings and objects
HSL(A) strings and objects
HSV(A) objects
Color names (via plugin)
XYZ objects (via plugin)
LCH (coming soon)

// String input examples
colord("FFF");
colord("#ffffff");
colord("#ffffffff");
colord("rgb(255, 255, 255)");
colord("rgba(255, 255, 255, 1)");
colord("hsl(0, 100%, 100%)");
colord("hsla(0, 100%, 100%, 1)");
colord("tomato"); // requires "names" plugin

// Object input examples
colord({ r: 255, g: 255, b: 255 });
colord({ r: 255, g: 255, b: 255, a: 1 });
colord({ h: 360, s: 100, l: 100 });
colord({ h: 360, s: 100, l: 100, a: 1 });
colord({ h: 360, s: 100, v: 100 });
colord({ h: 360, s: 100, v: 100, a: 1 });

Permissive parser

The library's parser cares about you and tries to prevent as many mistakes and typos as possible. It trims unnecessary whitespaces, clamps numbers, disregards character case, punctuation, brackets, etc. These are some examples:

colord(" aBc ").toHex(); // "#aabbcc"
colord("__rGbA 10 20,  999...").toRgbaString(); // "rgb(10, 20, 255)"
colord(" hsL(  10, 200% 30 .5!!!").toHslaString(); // "hsla(10, 100%, 30%, 0.5)"

Color conversion

toHex()

Returns the hexadecimal representation of a color. When the alpha channel value of the color is less than 1, it outputs #rrggbbaa format instead of #rrggbb.

colord("rgb(0, 255, 0)").toHex(); // "#00ff00"
colord({ h: 300, s: 100, l: 50 }).toHex(); // "#ff00ff"
colord({ r: 255, g: 255, b: 255, a: 0 }).toHex(); // "#ffffff00"

toRgba()

colord("#ff0000").toRgba(); // { r: 255, g: 0, b: 0, a: 1 }
colord({ h: 180, s: 100, l: 50, a: 0.5 }).toRgba(); // { r: 0, g: 255, b: 255, a: 0.5 }

toRgbaString()

colord("#ff0000").toRgbaString(); // "rgb(255, 0, 0)"
colord({ h: 180, s: 100, l: 50, a: 0.5 }).toRgbaString(); // "rgba(0, 255, 255, 0.5)"

toHsla()

Converts a color to HSL color space and returns an object.

colord("#ffff00").toHsla(); // { h: 60, s: 100, l: 50, a: 1 }
colord("rgba(0, 0, 255, 0.5) ").toHsla(); // { h: 240, s: 100, l: 50, a: 0.5 }

toHslaString()

Converts a color to HSL color space and expresses it through the functional notation.

colord("#ffff00").toHsla(); // "hsl(60, 100%, 50%)"
colord("rgba(0, 0, 255, 0.5)").toHsla(); // "hsla(240, 100%, 50%, 0.5)"

toHsva()

Converts a color to HSV color space and returns an object.

colord("#ffff00").toHsva(); // { h: 60, s: 100, v: 100, a: 1 }
colord("rgba(0, 255, 255, 0.5) ").toHsva(); // { h: 180, s: 100, v: 100, a: 1 }

toName() (names plugin)

Converts a color to a CSS keyword. Returns undefined if the color is not specified in the specs.

import { colord, extend } from "colord";
import namesPlugin from "colord/plugins/names";

extend([namesPlugin]);

colord("ff6347").toName(); // "tomato"
colord("#00ffff").toName(); // "cyan"
colord("#aabbcc").toName(); // undefined (the color is not specified in CSS specs)

toXyz() (xyz plugin)

Converts a color to CIE XYZ color space. The conversion logic is ported from CSS Color Module Level 4 Specification.

import { colord, extend } from "colord";
import xyzPlugin from "colord/plugins/xyz";

extend([xyzPlugin]);

colord("#ffffff").toXyz(); // { x: 95.047, y: 100, z: 108.883, a: 1 }

Color manipulation

alpha(value)

Changes the alpha channel value and returns a new Colord instance.

colord("rgb(0, 0, 0)").alpha(0.5).toRgbaString(); // rgba(0, 0, 0, 0.5)

invert()

Creates a new Colord instance containing an inverted (opposite) version of the color.

colord("#ffffff").invert().toHex(); // "#000000"
colord("#aabbcc").invert().toHex(); // "#554433"

saturate(amount = 0.1)

Increases the HSL saturation of a color by the given amount.

colord("#bf4040").saturate(0.25).toHex(); // "#df2020"
colord("hsl(0, 50%, 50%)").saturate(0.5).toHslaString(); // "hsl(0, 100%, 50%)"

desaturate(amount = 0.1)

Decreases the HSL saturation of a color by the given amount.

colord("#df2020").saturate(0.25).toHex(); // "#bf4040"
colord("hsl(0, 100%, 50%)").saturate(0.5).toHslaString(); // "hsl(0, 50%, 50%)"

grayscale()

Makes a gray color with the same lightness as a source color. Same as calling desaturate(1).

colord("#bf4040").grayscale().toHex(); // "#808080"
colord("hsl(0, 100%, 50%)").grayscale().toHslaString(); // "hsl(0, 0%, 50%)"

lighten(amount = 0.1)

Increases the HSL lightness of a color by the given amount.

colord("#000000").lighten(0.5).toHex(); // "#808080"
colord("#223344").lighten(0.3).toHex(); // "#5580aa"
colord("hsl(0, 50%, 50%)").lighten(0.5).toHslaString(); // "hsl(0, 50%, 100%)"

darken(amount = 0.1)

Decreases the HSL lightness of a color by the given amount.

colord("#ffffff").darken(0.5).toHex(); // "#808080"
colord("#5580aa").darken(0.3).toHex(); // "#223344"
colord("hsl(0, 50%, 100%)").lighten(0.5).toHslaString(); // "hsl(0, 50%, 50%)"

Color analysis

alpha()

colord("#ffffff").alpha(); // 1
colord("rgba(50, 100, 150, 0.5)").alpha(); // 0.5

brightness()

Returns the brightness of a color (from 0 to 1). The calculation logic is modified from Web Content Accessibility Guidelines.

colord("#000000").brightness(); // 0
colord("#808080").brightness(); // 0.5
colord("#ffffff").brightness(); // 1

isLight()

Same as calling brightness() >= 0.5.

colord("#111111").isLight(); // false
colord("#aabbcc").isLight(); // true
colord("#ffffff").isLight(); // true

isDark()

Same as calling brightness() < 0.5.

colord("#111111").isDark(); // true
colord("#aabbcc").isDark(); // false
colord("#ffffff").isDark(); // false

luminance() (a11y plugin)

Returns the relative luminance of a color, normalized to 0 for darkest black and 1 for lightest white as defined by WCAG 2.0.

colord("#000000").luminance(); // 0
colord("#808080").luminance(); // 0.22
colord("#ccddee").luminance(); // 0.71
colord("#ffffff").luminance(); // 1

contrast(color2 = "#FFF") (a11y plugin)

Calculates a contrast ratio for a color pair. This luminance difference is expressed as a ratio ranging from 1 (e.g. white on white) to 21 (e.g., black on a white). WCAG Accessibility Level AA requires a ratio of at least 4.5 for normal text and 3 for large text.

colord("#000000").contrast(); // 21 (black on white)
colord("#ffffff").contrast("#000000"); // 21 (white on black)
colord("#777777").contrast(); // 4.47 (gray on white)
colord("#ff0000").contrast(); // 3.99 (red on white)
colord("#0000ff").contrast("#ff000"); // 2.14 (blue on red)

isReadable(color2 = "#FFF", options?) (a11y plugin)

Checks that a background and text color pair is readable according to WCAG 2.0 Contrast and Color Requirements.

colord("#000000").isReadable(); // true (normal black text on white bg conforms to WCAG AA)
colord("#777777").isReadable(); // false (normal gray text on white bg conforms to WCAG AA)
colord("#ffffff").isReadable("#000000"); // true (normal white text on black bg conforms to WCAG AA)
colord("#e60000").isReadable("#ffff47"); // true (normal red text on yellow bg conforms to WCAG AA)
colord("#e60000").isReadable("#ffff47", { level: "AAA" }); // false (normal red text on yellow bg does not conform to WCAG AAA)
colord("#e60000").isReadable("#ffff47", { level: "AAA", size: "large" }); // true (large red text on yellow bg conforms to WCAG AAA)

Plugins

Colord has a built-in plugin system that allows new features and functionality to be easily added.

a11y (Accessibility)

Adds accessibility and color contrast utilities working according to Web Content Accessibility Guidelines 2.0.

import { colord, extend } from "colord";
import a11yPlugin from "colord/plugins/a11y";

extend([a11yPlugin]);

colord("#000000").luminance(); // 0
colord("#ccddee").luminance(); // 0.71
colord("#ffffff").luminance(); // 1

colord("#000000").contrast(); // 21 (black on white)
colord("#ffffff").contrast("#000000"); // 21 (white on black)
colord("#0000ff").contrast("#ff000"); // 2.14 (blue on red)

colord("#000000").isReadable(); // true (black on white)
colord("#ffffff").isReadable("#000000"); // true (white on black)
colord("#777777").isReadable(); // false (gray on white)
colord("#e60000").isReadable("#ffff47"); // true (normal red text on yellow bg conforms to WCAG AA)
colord("#e60000").isReadable("#ffff47", { level: "AAA" }); // false (normal red text on yellow bg does not conform to WCAG AAA)
colord("#e60000").isReadable("#ffff47", { level: "AAA", size: "large" }); // true (large red text on yellow bg conforms to WCAG AAA)

names (CSS color keywords)

Provides options to convert a color into a CSS color keyword and vice versa.

import { colord, extend } from "colord";
import namesPlugin from "colord/plugins/names";

extend([namesPlugin]);

colord("tomato").toHex(); // "#ff6347"
colord("#00ffff").toName(); // "cyan"
colord("#aabbcc").toName(); // undefined (the color is not specified in CSS specs)

xyz (CIE XYZ color space)

Adds support of CIE XYZ color model. The conversion logic is ported from CSS Color Module Level 4 Specification.

import { colord, extend } from "colord";
import xyzPlugin from "colord/plugins/xyz";

extend([xyzPlugin]);

colord("#ffffff").toXyz(); // { x: 95.047, y: 100, z: 108.883, a: 1 }
colord({ x: 0, y: 0, z: 0 }).toHex(); // "#000000"

Types

Colord is written in strict TypeScript and ships with types in the library itself — no need for any other install. We provide everything you need in one tiny package.

While not only typing its own functions and variables, Colord can also help you type yours. Depending on the color space you are using, you can also import and use the type that is associated with it.

import { RgbColor, RgbaColor, HslColor, HslaColor, HsvColor, HsvaColor } from "colord";

const foo: HslColor = { h: 0, s: 0, l: 0 };
const bar: RgbColor = { r: 0, g: 0, v: 0 }; // ERROR

molefrog / colord