colord

Colord uses a built-in plugin system to extend its core functionality. To use a plugin, you must import the extend function and the specific plugin from its package path, then pass the plugin(s) to extend(). Once extended, the new methods and color space support become available on all colord instances.

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

extend([a11yPlugin]);

// Now you can use methods provided by the plugin
colord("#000000").luminance();

Colord supports several color models natively or via its plugin system:

Native Support:

• Hexadecimal strings (including 3, 4, and 8 digit notations)
• RGB strings and objects
• HSL strings and objects
• HSV objects

Plugin-based Support:

• Color names
• HWB objects and strings
• CMYK objects and strings
• LCH objects and strings
• LAB objects
• XYZ objects

Colord provides a chainable API for color parsing, manipulation, and conversion. You can import the colord function and immediately start working with color strings or objects.

Key features include:

• Immutability: Operations return a new color instance rather than mutating the original.
• Chainable API: Methods can be linked together for complex transformations.
• CSS-compliant: Follows CSS Color Level specifications.

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"

To use Colord in your project, install it using npm:

npm i colord

The names plugin allows converting between colors and their CSS color keyword names.

Key methods:

• .toName(options?): Returns the CSS color name of the color, or undefined if no exact match exists.

Options:

• closest: If true, returns the closest matching CSS color name instead of undefined.

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

extend([namesPlugin]);

colord("#00ffff").toName(); // "cyan"
colord("#fe0000").toName({ closest: true }); // "red"

Colord provides several methods to convert a color instance into different representations:

• .toHex(): Returns the hexadecimal representation. If the alpha channel is < 1, it returns #rrggbbaa format.
• .toRgb(): Returns an object { r, g, b, a }.
• .toRgbString(): Returns an rgb() or rgba() functional string.
• .toHsl(): Returns an object { h, s, l, a }.
• .toHslString(): Returns an hsl() or hsla() functional string.
• .toHsv(): Returns an object { h, s, v, a }.

colord("#ff0000").toRgb(); // { r: 255, g: 0, b: 0, a: 1 }
colord("#ff0000").toRgbString(); // "rgb(255, 0, 0)"
colord("#ffff00").toHsl(); // { h: 60, s: 100, l: 50, a: 1 }
colord("#ffff00").toHslString(); // "hsl(60, 100%, 50%)"

The getFormat(input) function returns the name of the color model used by the input (e.g., "hex", "rgb", "hsl"). It uses the same parsing system as colord(). If the input cannot be parsed, it returns undefined.

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

The harmonies plugin allows you to generate colors based on color theory relationships.

Key method:

• .harmonies(type): Returns an array of colord instances representing the requested harmony.

Supported types:

• analogous
• complementary
• double-split-complementary
• rectangle
• split-complementary
• tetradic
• triadic

import { colord, extend } from "colord";
import harmonies from "colord/plugins/harmonies";

extend([harmonies]);

const color = colord("#ff0000");
color.harmonies("analogous").map((c) => c.toHex()); // ["#ff0080", "#ff0000", "#ff8000"]

The mix plugin allows mixing colors through the LAB color space for more natural results. It also provides utilities for generating tints, shades, and tones.

Key methods:

• .mix(otherColor, weight?): Mixes the current color with another color. weight is a number (0-1) representing the influence of the second color.
• .tints(count): Returns an array of colors transitioning from the original toward white.
• .shades(count): Returns an array of colors transitioning from the original toward black.
• .tones(count): Returns an array of colors transitioning from the original toward gray.

import { colord, extend } from "colord";
import mixPlugin from "colord/plugins/mix";

extend([mixPlugin]);

colord("#ffffff").mix("#000000").toHex(); // "#777777"
const color = colord("#ff0000");
color.tints(3).map((c) => c.toHex()); // ["#ff0000", "#ff9f80", "#ffffff"]

The lch plugin adds support for the CIE LCH color space.

Key methods:

• .toLch(): Returns an object { l, c, h, a }.
• .toLchString(): Returns a CSS-compatible LCH string.

import { colord, extend } from "colord";
import lchPlugin from "colord/plugins/lch";

extend([lchPlugin]);

colord("#646464").toLch(); // { l: 42.37, c: 0, h: 0, a: 1 }