github.com/omgovich/colord @v2.9 sqlite

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

Features

• 📦 Small: Just 1.7 KB gzipped (3x+ lighter than color and tinycolor2)
• 🚀 Fast: 3x+ 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 has 100% test coverage
• 🗂 Typed: Ships with types included
• 🏗 Extendable: Built-in plugin system to add new functionality
• 📚 CSS-compliant: Strictly follows CSS Color Level specifications
• 👫 Works everywhere: Supports all browsers and Node.js
• 💨 Dependency-free

Benchmarks

| Library | Operations/sec | Size

(minified) | Size

(gzipped) | Dependencies | Type declarations | | ----------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | | colord 👑 | 3,524,989 | | | | | | color | 744,263 | | | | | | tinycolor2 | 971,312 | | | | | | ac-colors | 660,722 | | | | | | chroma-js | 962,967 | | | | |

The performance results were generated on a MBP 2019, 2,6 GHz Intel Core i7 by 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).toRgbString(); // "rgba(128, 128, 128, 0.25)"
colord("rgb(192, 192, 192)").isLight(); // true
colord("hsl(0, 50%, 50%)").darken(0.25).toHex(); // "#602020"

Supported Color Models

• Hexadecimal strings (including 3, 4 and 8 digit notations)
• RGB strings and objects
• HSL strings and objects
• HSV objects
• Color names (via plugin)
• HWB objects and strings (via plugin)
• CMYK objects and strings (via plugin)
• LCH objects and strings (via plugin)
• LAB objects (via plugin)
• XYZ objects (via plugin)

API

Color parsing

colord(input)

Parses the given input and creates a new Colord instance. String parsing strictly conforms to CSS Color Level Specifications.

import { colord } from "colord";

// String input examples
colord("#FFF");
colord("#ffffff");
colord("#ffffffff");
colord("rgb(255, 255, 255)");
colord("rgba(255, 255, 255, 0.5)");
colord("rgba(100% 100% 100% / 50%)");
colord("hsl(90, 100%, 100%)");
colord("hsla(90, 100%, 100%, 0.5)");
colord("hsla(90deg 100% 100% / 50%)");
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 });

Check out the "Plugins" section for more input format examples.

getFormat(input)

Returns a color model name for the input passed to the function. Uses the same parsing system as colord function.

import { getFormat } from "colord";

getFormat("#aabbcc"); // "hex"
getFormat({ r: 13, g: 237, b: 162, a: 0.5 }); // "rgb"
getFormat("hsl(180deg, 50%, 50%)"); // "hsl"
getFormat("WUT?"); // undefined

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"

.toRgb()

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

.toRgbString()

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

.toHsl()

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

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

.toHslString()

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

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

.toHsv()

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

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

.toName(options?) (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("rgba(0, 0, 0, 0)").toName(); // "transparent"

colord("#fe0000").toName(); // undefined (the color is not specified in CSS specs)
colord("#fe0000").toName({ closest: true }); // "red" (closest color available)

.toCmyk() (cmyk plugin)

Converts a color to CMYK color space.

import { colord, extend } from "colord";
import cmykPlugin from "colord/plugins/cmyk";

extend([cmykPlugin]);

colord("#ffffff").toCmyk(); // { c: 0, m: 0, y: 0, k: 0, a: 1 }
colord("#555aaa").toCmyk(); // { c: 50, m: 47, y: 0, k: 33, a: 1 }

.toCmykString() (cmyk plugin)

Converts a color to color space.

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

import { colord, extend } from "colord";
import cmykPlugin from "colord/plugins/cmyk";

extend([cmykPlugin]);

colord("#99ffff").toCmykString(); // "device-cmyk(40% 0% 0% 0%)"
colord("#00336680").toCmykString(); // "device-cmyk(100% 50% 0% 60% / 0.5)"

.toHwb() (hwb plugin)

Converts a color to HWB (Hue-Whiteness-Blackness) color space.

import { colord, extend } from "colord";
import hwbPlugin from "colord/plugins/hwb";

extend([hwbPlugin]);

colord("#ffffff").toHwb(); // { h: 0, w: 100, b: 0, a: 1 }
colord("#555aaa").toHwb(); // { h: 236, w: 33, b: 33, a: 1 }

.toHwbString() (hwb plugin)

Converts a color to HWB (Hue-Whiteness-Blackness) color space and expresses it through the functional notation.

import { colord, extend } from "colord";
import hwbPlugin from "colord/plugins/hwb";

extend([hwbPlugin]);

colord("#999966").toHwbString(); // "hwb(60 40% 40%)"
colord("#99ffff").toHwbString(); // "hwb(180 60% 0%)"
colord("#003366").alpha(0.5).toHwbString(); // "hwb(210 0% 60% / 0.5)"

.toLab() (lab plugin)

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

import { colord, extend } from "colord";
import labPlugin from "colord/plugins/lab";

extend([labPlugin]);

colord("#ffffff").toLab(); // { l: 100, a: 0, b: 0, alpha: 1 }
colord("#33221180").toLab(); // { l: 14.89, a: 5.77, b: 14.41, alpha: 0.5 }

.toLch() (lch plugin)

Converts a color to [CIE LCH](https://lea.verou.me/2020/04/lch-colors-in-css-what-why-and-h