Colord: Lightweight JavaScript Color Manipulation Library

Colord is a lightweight JavaScript color library for parsing, converting, and adjusting CSS colors.

It provides an immutable, dependency-free API to handle HEX, RGB, HSL, and HSV values, with optional plugins for OKLCH, palette generation, and contrast checks.

Features

• Parses hexadecimal, RGB, and HSL strings, plus RGB, HSL, and HSV objects.
• Converts colors to HEX, RGB, HSL, and HSV with built-in methods.
• Adjusts alpha, hue, lightness, and saturation through chainable operations.
• Adds OKLab, OKLCH, Lab, LCH, HWB, CMYK, and XYZ through optional plugins.
• Generates color harmonies, mixes, tints, shades, and tones.
• Checks text contrast and readability against WCAG 2 thresholds.

How To Use It

Installation

Install Colord with npm:

npm install colord

For browser use, load the versioned ES module in the document:

<script type="module">
  import { colord } from "https://cdn.jsdelivr.net/npm/[email protected]/index.mjs";
  console.log(colord("#ff6347").toHslString());
</script>

Basic Usage

import { colord } from "colord";
const color = colord("#ff6347");
console.log(color.toRgbString()); // "rgb(255, 99, 71)"
console.log(color.toHsl());
console.log(color.darken(0.2).toHex());
console.log(color.alpha(0.5).toRgbString());

Validate a Color Before Using It

An invalid input produces an instance whose fallback color is black. Check isValid() before saving a user-entered value or applying it to a theme:

import { colord } from "colord";
function normalizeColor(input) {
  const color = colord(input);
  return color.isValid() ? color.toHex() : null;
}
console.log(normalizeColor("rgb(255 99 71)")); // "#ff6347"
console.log(normalizeColor("not-a-color"));  // null

Set Theme Colors and Choose Contrasting Text

The a11y plugin calculates contrast ratios from RGB channels. Use the final composited colors if a text or background layer is translucent.

<button class="primary-action">Save changes</button>

import { colord, extend } from "colord";
import a11yPlugin from "colord/plugins/a11y";
extend([a11yPlugin]);
const brand = colord("#0f766e");
const foreground = colord("#fff").contrast(brand) >=
  colord("#000").contrast(brand) ? "#fff" : "#000";
document.documentElement.style.setProperty("--brand", brand.toHex());
document.documentElement.style.setProperty("--on-brand", foreground);

.primary-action {
  background: var(--brand);
  color: var(--on-brand);
}

Convert OKLCH Colors

Enable oklch to parse CSS oklch() strings and convert RGB colors to OKLCH. Object input needs ok: true to distinguish OKLCH from CIE LCH, which uses the same channel names.

import { colord, extend } from "colord";
import oklchPlugin from "colord/plugins/oklch";
extend([oklchPlugin]);
console.log(colord("oklch(0.5 0.2 240)").toHex()); // "#0069c7"
console.log(colord("#008080").toOklchString());
console.log(colord({ l: 0.5431, c: 0.09271, h: 194.77, ok: true }).toHex()); // "#008080"

Generate a Palette

The mix plugin interpolates colors in CIE Lab by default. Choose "rgb" as the color space when you need RGB-channel interpolation.

import { colord, extend } from "colord";
import mixPlugin from "colord/plugins/mix";
import harmoniesPlugin from "colord/plugins/harmonies";
extend([mixPlugin, harmoniesPlugin]);
const base = colord("#ff0000");
const tints = base.tints(5).map((color) => color.toHex());
const complementary = base.harmonies("complementary")
  .map((color) => color.toHex());
console.log(tints);
console.log(complementary); // ["#ff0000", "#00ffff"]

Color Inputs and Supported Models

Core parsing accepts hexadecimal strings (3, 4, 6, or 8 digits), RGB and HSL strings, and RGB, HSL, or HSV objects. Additional models require the corresponding plugins.

Public API Reference

Core Functions

Core Conversion Methods

Core Manipulation Methods

Core Color Analysis

Optional Plugins and Their Methods

Import a plugin from colord/plugins/<name> and register it with extend([plugin]).

Plugin Options and Accepted Values

Color Minification Options

Register the minify plugin to shorten CSS color strings. Keyword output also requires the names plugin.

import { colord, extend } from "colord";
import minifyPlugin from "colord/plugins/minify";
extend([minifyPlugin]);
console.log(colord("#112233").minify()); // "#123"
console.log(colord("#aabbcc66").minify({ alphaHex: true }));

TypeScript Types

Colord includes TypeScript declarations for its core API, plugins, and color objects.

import { colord, extend, type RgbColor, type OklchaColor } from "colord";
import oklchPlugin from "colord/plugins/oklch";
extend([oklchPlugin]);
const rgb: RgbColor = { r: 255, g: 99, b: 71 };
const perceptual: OklchaColor = colord(rgb).toOklch();

Alternatives and Related Resources

• Minimalist Color Manipulation Library – color2k
• hueful: CSS Color Parsing and Conversion in JavaScript
• Dynamically Change Font Color Based On Background – Contrast.js
• 10 Best Color Manipulation JavaScript Libraries

FAQs

Why does colord(“tomato”).isValid() return false?

Register the names plugin before parsing CSS color keywords: extend([namesPlugin]).

Does Colord parse CSS color(display-p3 ...) values?

No. Colord supports the input formats listed above, including OKLCH and Lab through plugins. Convert Display P3 colors to a supported format before passing them to Colord.

Should I use isLight() or contrast() for text color?

isLight() uses a brightness threshold. The a11y plugin’s contrast() calculates the contrast ratio for the actual text and background colors.