Colord

<div align="center"> <a href="https://colord.omgovich.ru/"> <img src="assets/logo.png" width="280" height="210" alt="colord" /> </a> </div> <div align="center"> <a href="https://npmjs.org/package/colord"> <img alt="npm" src="https://img.shields.io/npm/v/colord.svg?labelColor=dd3a5e&color=6ead0a" /> </a> <a href="https://github.com/omgovich/colord/actions"> <img alt="build" src="https://img.shields.io/github/workflow/status/omgovich/colord/Node.js%20CI/master.svg?labelColor=dd3a5e&color=6ead0a" /> </a> <a href="https://codecov.io/gh/omgovich/colord"> <img alt="coverage" src="https://img.shields.io/codecov/c/github/omgovich/colord.svg?labelColor=dd3a5e&color=6ead0a" /> </a> <a href="https://npmjs.org/package/colord"> <img alt="no dependencies" src="https://badgen.net/bundlephobia/dependency-count/colord?labelColor=dd3a5e&color=6ead0a" /> </a> <a href="https://npmjs.org/package/colord"> <img alt="types included" src="https://badgen.net/npm/types/colord?labelColor=dd3a5e&color=6ead0a" /> </a> </div> <div align="center"> <strong>Colord</strong> is a tiny yet powerful tool for high-performance color manipulations and conversions. </div>

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

<div><img src="assets/divider.png" width="838" alt="---" /></div>

Benchmarks

| Library | <nobr>Operations/sec</nobr> | Size<br /> (minified) | Size<br /> (gzipped) | Dependencies | Type declarations | | ----------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | | <nobr><b>colord 👑</b></nobr> | <nobr><b>3,524,989</b></nobr> | | | | | | 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.

<div><img src="assets/divider.png" width="838" alt="---" /></div>

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"

<div><img src="assets/divider.png" width="838" alt="---" /></div>

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)

<div><img src="assets/divider.png" width="838" alt="---" /></div>

API

Color parsing

<details> <summary><b><code>colord(input)</code></b></summary>

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.

</details> <details> <summary><b><code>getFormat(input)</code></b></summary>

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

</details>

Color conversion

<details> <summary><b><code>.toHex()</code></b></summary>

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"

</details> <details> <summary><b><code>.toRgb()</code></b></summary>

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 }

</details> <details> <summary><b><code>.toRgbString()</code></b></summary>

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

</details> <details> <summary><b><code>.toHsl()</code></b></summary>

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 }

</details> <details> <summary><b><code>.toHslString()</code></b></summary>

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

colord("