Socket
Socket
Sign inDemoInstall

colord

Package Overview
Dependencies
0
Maintainers
1
Versions
49
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

    colord

👑 A tiny yet powerful tool for high-performance color manipulations and conversions


Version published
Maintainers
1
Install size
78.8 kB
Created

Package description

What is colord?

The colord npm package is a tiny yet powerful tool for color conversions and manipulations. It provides functions for parsing colors, converting them between different color models, and manipulating their properties such as hue, saturation, lightness, and alpha channel.

What are colord's main functionalities?

Parsing and converting colors

This feature allows you to parse color strings and convert them to different color models. The example shows how to parse a hex color and convert it to an RGB object.

const { colord, extend } = require('colord');
const c = colord('#ff5733');
console.log(c.toRgb()); // { r: 255, g: 87, b: 51, a: 1 }

Manipulating color properties

This feature enables you to manipulate color properties such as alpha channel. The example demonstrates setting the alpha of an RGBA color and converting it to a string.

const { colord } = require('colord');
const color = colord('rgba(255, 87, 51, 1)');
console.log(color.alpha(0.5).toRgbString()); // 'rgba(255, 87, 51, 0.5)'

Mixing colors

This feature allows you to mix two colors together. The example mixes a color with white at a 50% ratio and outputs the hex value of the result.

const { colord } = require('colord');
const mix = colord('#ff5733').mix('#ffffff', 0.5).toHex();
console.log(mix); // '#ffaba9'

Generating readable colors

This feature helps in checking if a color is readable on another color, which is useful for accessibility. The example checks if the color '#ff5733' is readable on a white background.

const { colord, extend } = require('colord');
extend([require('colord/plugins/a11y')]);
const color = colord('#ff5733');
console.log(color.isReadable('#ffffff')); // true or false

Other packages similar to colord

Changelog

Source

1.4.0

  • New plugin: Color mixing
  • Adjust XYZ, LAB and LCH conversions to the D50 white point (according to the latest CSS specs).

Readme

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

Features

  • 📦 Small: Just 1.5 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
  • 👫 Works everywhere: Supports all browsers and Node.js
  • 💨 Dependency-free
---

Benchmarks

LibraryOperations/secSize
(minified)
Size
(gzipped)
DependenciesType declarations
colord 👑3,620,695
color760,254
tinycolor21,111,927
ac-colors632,656
chroma-js969,079

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"
---

API

Color parsing

Accepted input formats
// 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 parser of the library is user-friendly: it trims unnecessary whitespaces, clamps numbers, disregards character case, punctuation, brackets, etc. Here are some examples:

colord(" aBc ").toHex(); // "#aabbcc"
colord("__rGbA 10 20,,  999...").toRgbString(); // "rgb(10, 20, 255)"
colord(" hsL(  10, 200% 30 .5!!!").toHslString(); // "hsla(10, 100%, 30%, 0.5)"
colord({ r: NaN, g: -Infinity, b: +Infinity, a: 100500 }).toRgb(); // { r: 0, g: 0, b: 255, a: 1 }

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() (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)
colord("rgba(0, 0, 0, 0)").toName(); // "transparent"
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 }
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 color space. The conversion logic is ported from CSS Color Module Level 4 Specification.

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

extend([lchPlugin]);

colord("#ffffff").toLch(); // { l: 100, c: 0, h: 0, a: 1 }
colord("#213b0b").toLch(); // { l: 21.85, c: 31.95, h: 127.77, a: 1 }
toLchString() (lch plugin)

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

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

extend([lchPlugin]);

colord("#ffffff").toLchString(); // "lch(100% 0 0)"
colord("#213b0b").alpha(0.5).toLchString(); // "lch(21.85% 31.95 127.77 / 0.5)"
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).toRgbString(); // 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).toHslString(); // "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).toHslString(); // "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().toHslString(); // "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).toHslString(); // "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).toHslString(); // "hsl(0, 50%, 50%)"
mix(color2, ratio = 0.5) (mix plugin)

Produces a mixture of two colors and returns the result of mixing them (new Colord instance).

In contrast to other libraries that perform RGB values mixing, Colord mixes colors through LCH color space — same way the new CSS color-mix function works. This approach produces better results and doesn't have the drawbacks the legacy way has.

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

extend([mixPlugin]);

colord("#ffffff").mix("#000000").toHex(); // "#777777"
colord("#800080").mix("#dda0dd").toHex(); // "#af5cae"
colord("#cd853f").mix("#eee8aa", 0.6).toHex(); // "#dfc279"
colord("#008080").mix("#808000", 0.35).toHex(); // "#14865f"

Color analysis

isValid()

Returns a boolean indicating whether or not an input has been parsed successfully. Note: If parsing is unsuccessful, Colord defaults to black (does not throws an error).

colord("#ffffff").isValid(); // true
colord("#wwuutt").isValid(); // false
colord("abracadabra").isValid(); // false
colord({ r: 0, g: 0, b: 0 }).isValid(); // true
colord({ r: 0, g: 0, v: 0 }).isValid(); // false
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) 0.38 KB

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)
hwb (HWB color model) 0.5 KB

Adds support of Hue-Whiteness-Blackness color model.

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 }

colord({ h: 0, w: 0, b: 100 }).toHex(); // "#000000"
colord({ h: 0, w: 100, b: 0, a: 1 }).toHex(); // "#ffffff"
lab (CIE LAB color space) 0.9 KB

Adds support of CIE LAB color model. 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({ l: 53.24, a: 80.09, b: 67.2 }).toHex(); // "#ff0000"
colord("#ffffff").toLab(); // { l: 100, a: 0, b: 0, alpha: 1 }
lch (CIE LCH color space) 1.2 KB

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

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

extend([lchPlugin]);

colord({ l: 100, c: 0, h: 0 }).toHex(); // "#ffffff"
colord("lch(48.25% 30.07 196.38)").toHex(); // "#008080"

colord("#646464").toLch(); // { l: 42.37, c: 0, h: 0, a: 1 }
colord("#646464").alpha(0.5).toLchString(); // "lch(42.37% 0 0 / 0.5)"
mix (Color mixing) 0.97 KB

A plugin adding a color mixing utility.

In contrast to other libraries that perform RGB values mixing, Colord mixes colors through LCH color space — same way the new CSS color-mix function works. This approach produces better results and doesn't have the drawbacks the legacy way has.

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

extend([mixPlugin]);

colord("#ffffff").mix("#000000").toHex(); // "#777777"
colord("#800080").mix("#dda0dd").toHex(); // "#af5cae"
colord("#cd853f").mix("#eee8aa", 0.6).toHex(); // "#dfc279"
colord("#008080").mix("#808000", 0.35).toHex(); // "#14865f"
names (CSS color keywords) 1.29 KB

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)
colord("rgba(0, 0, 0, 0)").toName(); // "transparent"
xyz (CIE XYZ color space) 0.7 KB

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
---

Roadmap

  • Parse and convert Hex, RGB(A), HSL(A), HSV(A)
  • Saturate, desaturate, grayscale
  • Trim an input value
  • Clamp input numbers to resolve edge cases (e.g. rgb(256, -1, 999, 2))
  • brightness, isDark, isLight
  • Set and get alpha
  • Plugin API
  • 4 and 8 digit Hex
  • lighten, darken
  • invert
  • CSS color names (via plugin)
  • A11y and contrast utils (via plugin)
  • XYZ color space (via plugin)
  • HWB color space (via plugin)
  • LAB color space (via plugin)
  • LCH color space (via plugin)
  • Mix colors (via plugin)
  • CMYK color space (via plugin)

Keywords

FAQs

Last updated on 28 Apr 2021

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc