JSPM

Tools for all your color needs

Color utilities is a collection of tools used to work with colors.

Features

• Color conversions (ansi16, ansi256, cmy, cmyk, tsl, hsl, hsv, lab, luv, lch xyz ...)
• Color blending
• Color harmony pallet creation
• Color mixers ( such as getting shades, tints and tones)
• Performing Chromatic adaptation
• Color validation and sanitization
• Color manipulation (lighten, darken, saturate, mix)
• WCAG accessibility checking
• CSS color string parsing and formatting
• Color interpolation and scales
• Gamut checking and mapping

Table of Contents

• Color Utilities
• Features
• Table of Contents
• About Color Utilities
  • Limits
  • Performance Considerations
• Documentation
  • Dependencies
  • Importing
  • TypeScript Support
• Color
• Common Use Cases
• Conversions
• Color Converter
  • RGB Converter
  • XYZ Converter
• Color Blending
  • Blender
  • blend
• Color Harmonies
  • Analogous
  • Clash
  • Complementary
  • Split Complementary
  • Four Tone
  • Five Tone
  • Six Tone
  • Neutral
  • Square
  • Tetradic
  • Triadic
• Color Validation & Sanitization
• Color Manipulation
• Accessibility Utilities
• CSS Color Utilities
• Color Interpolation & Scales
• Gamut Utilities
• Color Mixes
  • Tones
  • Tints
  • Shades
• Chromatic adaptation
  • Supported Illuminants
  • adapt
  • Adapter
• Delta E / Color Difference
  • CIE 76
  • CIE 94
  • CIE 00
• Troubleshooting
• Contributing
• License

About Color Utilities

Color Utilities aims to be a one-stop shop for any work related to colors, mostly built with pure functions One can use as little or as much of it as needed or wanted, avoiding unneeded project bloating. In the future, this library will most probably grow further.

Limits

Due to the nature of color spaces, certain conversions are more computationally taxing than others. Further, certain conversions lead to data loss like RGB to Ansi16 and then back to RGB will most probably result in a significant difference in color.

Performance Considerations

• Color Class: Use with caution in performance-critical applications as it computes multiple color spaces
• Standalone Functions: More efficient for single conversions
• Individual CSS Parsers: Use specific parsers (parseHex, parseRgb) instead of fromCssString for better performance
• "all" Option: Avoid in real-time applications due to computational cost
• Tree-shaking: Individual functions can be imported separately to reduce bundle size

Documentation

npm install --save @dynamize/color-utilities

Dependencies

This library has no dependencies and is completely self-contained.

Importing

Importing is done using the ES static import declaration. Example:

import { Color } from "@dynamize/color-utilities";

In order to use the import declaration in a source file, the file must be interpreted by the runtime as a module.

TypeScript Support

This library includes full TypeScript definitions. No additional @types package needed.

import { Color, RGB } from "@dynamize/color-utilities";

const color: Color = new Color("rgb", { red: 255, green: 0, blue: 0 });
const rgb: RGB = color.data.rgb;

Color

A Color class is a representation of a color in Color Utilities. Use case for this is when you know you will need values for more then one color space.

Usage examples:

import { Color } from "@dynamize/color-utilities";

const color = new Color("rgb", { red: 238, green: 200, blue: 27 });

console.log(color.data);

Common Use Cases

Color Picker Implementation

// Efficient for color pickers - only compute needed spaces
const pickerColor = new Color("hsv", { hue: 49, saturation: 86, value: 93 }, [
  "rgb",
  "hex",
]);

Theme Generation

// Generate complete color themes
const baseColor = new Color("hex", "#3498db");
const shades = getShades(baseColor.data.rgb, { size: 10, prefixed: true });
const harmony = analogousHarmony(baseColor.data.hsl, true);

Color Analysis

// Compare colors for accessibility
const contrast = deltaECIE00Rgb(textColor.rgb, backgroundColor.rgb);

• The first argument we pass is a string value and it represents the space in which color values will be passed.
• The second argument is the actual color values and it's passed in form of an object.
• The third argument is optional and has a form of string array or a string "all", if not passed, automatically values for hex, hvs, lab, and cmyk, will be computed, alternatively color spaces listed in the array will be computed.

The result of the above example is:

 Color {
  rgb: { red: 238, green: 200, blue: 27, inGamut: true },
  xyz: { x: 56.11537464609447, y: 59.56827248834963, z: 9.578873171265526 },
  hex: 'EEC81B',
  hsv: { hue: 49, saturation: 89, value: 93 },
  lab: {
    luminance: 81.60296053275202,
    a: -1.2482727232548951,
    b: 79.33052440955292
 },
 cmyk: {
   cyan: 0,
   magenta: 15.96638655462185,
   yellow: 88.65546218487395,
   key: 6.666666666666665
  }
 }

Lets see an alternative use:

import { Color } from "@dynamize/color-utilities";

const color = new Color("rgb", { red: 238, green: 200, blue: 27 }, [
  "hsl",
  "luv",
  "ryb",
  "tsl",
]);

console.log(color.data);

Result from the above example would be:

Color {
  rgb: { red: 238, green: 200, blue: 27, inGamut: true },
  xyz: { x: 56.11537464609447, y: 59.56827248834963, z: 9.578873171265526 },
  hsl: { hue: 49, saturation: 86, lightness: 52 },
  luv: { L: 81.60296053275202, u: 33.50413039331645, v: 84.4716716630059 },
  ryb: { red: 63.346820809248555, yellow: 228, blue: 17 },
  tsl: {
    tint: 0.4209301051592921,
    saturation: 0.27240784750042124,
    lightness: 0.7515294117647058
  }
}

Note: If you noticed RGB and XYZ values are returned regardless, they are needed for two main family of spaces and there for are computed by default.

If "all" is passed as a third argument, all 45 spaces will be computed (the return example is to big to show here), this option is computationally tasking and it's not a good option for color pickers or other use cases where there is a high frequency of re computation. Accidentally the default (no third argument) will return values utilized in a Photoshop color picker (rgb, hsv, lab, cmyk and hex).

Conversions

Here is a list of all color conversion methods, they are standalone, and can be utilized on their own. Some of them might have multiple conversions and that will be stated in the table.

Color Converter

In situations where you might need to covert from one space into multiple spaces, you can use a color converter. Color Converter is faster and less task-intensive than using Color. There are two prebuilt Color Converters, RGB Converter and the XYZ Converter.

RGB Converter

RGB Converter is a prebuilt Color Converter that takes a single attribute of a type: { red: number, green: number, blue: number } or { r: number, g: number, b: number }.

It has a single method, "get" and it takes an attribute of type string which represents a color space you would like back. Supported conversion are: adobe_98_rgb, apple_rgb, ansi16, ansi256, best_rgb, beta_rgb, bruce_rgb, cie_rgb, color_match_rgb, cmy, cmyk, don_rgb_4, etka_space_ps5, eci_rgb_v2, hcy, hex, hsi, hsl, hsv, hwb, lab, lch_ab, lch_uv, luv, ntsc_rgb, pal_secam_rgb, pro_photo_rgb, ryb, smpte_c_rgb, tsl, uvw, wide_gamut_rgb, ycbcr_BT601, ycbcr_BT709, ycbcr_BT2020, ydbdr, ypbpr, yccbccrc, ycocg, yiq, xvycc, xyz.

Usage example:

import { RgbConverter } from "@dynamize/color-utilities";

const rgbCon = new RgbConverter({ red: 238, green: 200, blue: 27 });

console.log(rgbCon.get("hsv"));

This will return HSV values for the above-given color.

XYZ Converter

XYZ Converter is a prebuilt Color Converter that takes a single attribute of a type: { x: number, y: number, z: number }.

It has a single method, "get" and it takes an attribute of type string which represents a color space you would like back. Supported conversion are: lab, lch_ab, lch_uv, luv, uvw, rgb, adobe_98_rgb, apple_rgb, best_rgb, beta_rgb, bruce_rgb, cie_rgb, color_match_rgb, don_rgb_4, etka_space_ps5, eci_rgb_v2, ntsc_rgb, pal_secam_rgb, pro_photo_rgb, smpte_c_rgb, wide_gamut_rgb, xyy, lms, hunters_lab.

Usage example:

import { XyzConverter } from "@dynamize/color-utilities";

const xyzCon = new XyzConverter({ red: 238, green: 200, blue: 27 });

console.log(xyzCon.get("luv"));

This will return LUV values for the above-given color.

Color Blending

In Color Utilities, there are two ways you can blend colors: either by using the standalone method "blend" or by using a Color Blender.

Blender

Color Blender is quite powerful, it allows you to blend two colors in rgb ,cmyk, hex, hsl ,hsv, hwb, hex, ryb and xyz formats. The two colors do not have to be in the same format to blend them, and the returned color can have any of the following formats: rgb ,cmyk, hex, hsl ,hsv, hwb, hex, ryb, xyz.

Usage example:

import { Blender } from "@dynamize/color-utilities";

const color = new Blender(
  { c: 0, m: 7, y: 100, k: 0 },
  { h: 0, s: 100, v: 100 },
  { weight: 0.67, returnType: "hex" }
);

console.log(color.color);

Color Blender can return two things: color or blend data. Color will just be a color value in the format that was requested, blend data will give you more information. Below, you can see the blend data for the above example:

{
    color1: {
      data: { cyan: 0, magenta: 7, yellow: 100, key: 0 },
      rgb: { red: 255, green: 237.14999999999998, blue: 0, inGamut: true },
      amount: 0.67,
    },
    color2: {
      data: { hue: 0, saturation: 100, value: 100 },
      rgb: { red: 255, green: 0, blue: 0, inGamut: true },
      amount: 0.32999999999999996,
    },
    resultColor: "FF9F00",
  }

blend

Using the blend method is pretty straight-forward. It takes three parameters, the first two being the RGB values of colors to blend, and the last one is a percentage of the first color, the remaining percentage will be allocated to the second one.

Usage example:

import { blend } from "@dynamize/color-utilities";

const blended = blend(
  { red: 255, green: 237, blue: 0 },
  { red: 255, green: 0, blue: 0 },
  0.67
);

console.log(blended);

Color Harmonies

With Color utilities, you can also generate a number of Harmony pallets. For more information about Harmonies, visit: https://simplified.com/blog/colors/color-harmony All Harmonies are a standalone functions and they all the a color in a HSL format ({ hue: number, saturation: number, lightness: number }) and return an array of hex values. In addition, in addition the second optional parameter is a boolean, which represents if returned hex values should start with a #.

Analogous

Usage example:

import { analogousHarmony } from "@dynamize/color-utilities";

const pallet = analogousHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Clash

Usage example:

import { clashHarmony } from "@dynamize/color-utilities";

const pallet = clashHarmony({ hue: 49, saturation: 86, lightness: 52 }, true);

console.log(pallet);

Complementary

Usage example:

import { complementaryHarmony } from "@dynamize/color-utilities";

const pallet = complementaryHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Split Complementary

Usage example:

import { splitComplementaryHarmony } from "@dynamize/color-utilities";

const pallet = splitComplementaryHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Usage example:

import { splitComplementaryCWHarmony } from "@dynamize/color-utilities";

const pallet = splitComplementaryCWHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Usage example:

import { splitComplementaryCCWHarmony } from "@dynamize/color-utilities";

const pallet = splitComplementaryCCWHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Four Tone

Usage example:

import { fourToneCWHarmony } from "@dynamize/color-utilities";

const pallet = fourToneCWHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Usage example:

import { fourToneCCWHarmony } from "@dynamize/color-utilities";

const pallet = fourToneCCWHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Five Tone

Usage example:

import { fiveToneAHarmony } from "@dynamize/color-utilities";

const pallet = fiveToneAHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Usage example:

import { fiveToneBHarmony } from "@dynamize/color-utilities";

const pallet = fiveToneBHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Usage example:

import { fiveToneCHarmony } from "@dynamize/color-utilities";

const pallet = fiveToneCHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Usage example:

import { fiveToneDHarmony } from "@dynamize/color-utilities";

const pallet = fiveToneDHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Usage example:

import { fiveToneEHarmony } from "@dynamize/color-utilities";

const pallet = fiveToneEHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Six Tone

Usage example:

import { sixToneCWHarmony } from "@dynamize/color-utilities";

const pallet = sixToneCWHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Usage example:

import { sixToneCCWHarmony } from "@dynamize/color-utilities";

const pallet = sixToneCCWHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Neutral

Usage example:

import { neutralHarmony } from "@dynamize/color-utilities";

const pallet = neutralHarmony({ hue: 49, saturation: 86, lightness: 52 }, true);

console.log(pallet);

Square

import { squareHarmony } from "@dynamize/color-utilities";

const pallet = squareHarmony({ hue: 49, saturation: 86, lightness: 52 }, true);

console.log(pallet);

Tetradic

import { tetradicHarmony } from "@dynamize/color-utilities";

const pallet = tetradicHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Triadic

import { triadicHarmony } from "@dynamize/color-utilities";

const pallet = triadicHarmony({ hue: 49, saturation: 86, lightness: 52 }, true);

console.log(pallet);

Color Validation & Sanitization

isValidColor

import { isValidColor } from "@dynamize/color-utilities";

// Check if color is valid for a space
isValidColor("rgb", { red: 255, green: 0, blue: 0 }); // true
isValidColor("hsl", { hue: 400, saturation: 150, lightness: 50 }); // false

sanitizeColor

import { sanitizeColor } from "@dynamize/color-utilities";

// Clamp values to valid ranges
sanitizeColor("rgb", { red: 300, green: -5, blue: 128 });
// Returns: { red: 255, green: 0, blue: 128 }

Color Manipulation

import { lighten, darken, saturate, mix } from "@dynamize/color-utilities";

const baseColor = { red: 238, green: 200, blue: 27 };

// Basic adjustments
const lighter = lighten(baseColor, 20);
const darker = darken(baseColor, 15);
const saturated = saturate(baseColor, 30);

// Color mixing
const mixed = mix(baseColor, { red: 255, green: 0, blue: 0 }, 0.5);

Accessibility Utilities

import { contrastRatio, isAccessible } from "@dynamize/color-utilities";

// Check contrast ratio
const ratio = contrastRatio(white, black); // ~21:1

// Verify WCAG compliance
const accessible = isAccessible(
  { red: 255, green: 255, blue: 255 }, // text
  { red: 0, green: 100, blue: 200 },   // background
  'AA' // WCAG level
);

CSS Color Utilities

import { toCssString, fromCssString, parseHex, parseRgb } from "@dynamize/color-utilities";

// Convert to CSS strings
toCssString(color, 'hex');   // "#EEC81B"
toCssString(color, 'rgb');   // "rgb(238 200 27)"
toCssString(color, 'hsl');   // "hsl(49 86% 52%)"
toCssString(color, 'oklch'); // "oklch(0.823 0.156 89.6)"

// Parse CSS strings
fromCssString('#EEC81B');
fromCssString('rgb(238 200 27)');
fromCssString('hsl(49 86% 52%)');

// Or use individual parsers
parseHex('#EEC81B');
parseRgb('rgb(238, 200, 27)');

Color Interpolation & Scales

import { interpolate, createScale } from "@dynamize/color-utilities";

// Interpolate between colors
const purple = interpolate(red, blue, 0.5, 'lab');

// Create color scales
const gradient = createScale([red, green, blue], 10, 'hsl');

Gamut Utilities

import { isInGamut, mapToGamut } from "@dynamize/color-utilities";

// Check if color is in sRGB gamut
isInGamut({ red: 300, green: -5, blue: 128 }); // false

// Map to nearest in-gamut color
mapToGamut({ red: 300, green: -5, blue: 128 });
// Returns: { red: 255, green: 0, blue: 128, inGamut: true }

Color Mixes

Color Utilities also provides three types of color mixes you can get: Shades, Tints and Tones. All of these are generated by a standalone function that receives two arguments, the first being a base color in RGB format, and the second one is an optional options object that can have two values: size (number of colors generated in the pallet) and prefixed (boolean stating if the colors should start with a #). The return value is an array of strings representing hex values.

Tones

import { getTones } from "@dynamize/color-utilities";

const tones = getTones(
  { red: 238, green: 200, blue: 27 },
  { size: 10, prefixed: true }
);

console.log(tones);

Tints

import { getTints } from "@dynamize/color-utilities";

const tints = getTints(
  { red: 238, green: 200, blue: 27 },
  { size: 10, prefixed: true }
);

console.log(tints);

Shades

import { getShades } from "@dynamize/color-utilities";

const shades = getShades(
  { red: 238, green: 200, blue: 27 },
  { size: 10, prefixed: true }
);

console.log(shades);

Chromatic adaptation

Chromatic adaptation can be preformed in two ways, either by using a standalone "adapt" function or by using an Adapter class.

Supported Illuminants

The following illuminant adaptations are supported:

adapt

"adapt" function which takes two arguments, first being XYZ values 0f the color to be adapted, and a string value representing reference illuminant and a destination illuminant.

import { adapt } from "@dynamize/color-utilities";

const adapted = adapt(
  { x: 56.11537464609447, y: 59.56827248834963, z: 9.578873171265526 },
  "A_B"
);

console.log(adapted);

The above example will adapt from a from reference illuminant A to destination illuminant B.

Adapter

The Adapter class is a little bit more powerful but slower, it takes two optional arguments, first being color values, second is the color space of those values, if not passed default values will be for color white in XYZ format.

Here is a table of all available formats and values:

| Param place | Description | Formats | | ----------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | | # 1 | Color data | { r: number, g: number, b: number }, { red: number, green: number, blue: number }, { l: number, a: number, b: number }, { luminance: number, a: number, b: number }, { L: number, u: number, v: number }, { l: number, c: number, h: number }, { lightness: number, chroma: number hue: number }, { long: number, medium: number, short: number }, { u: number, v: number, w: number }, { x: number, y: number, Y: number }, { x: number, y: number, z: number } | | # 2 | Color Space of the given color | adobe_98_rgb, apple_rgb, best_rgb, beta_rgb, bruce_rgb, cie_rgb, color_match_rgb, don_rgb_4, eci_rgb_v2, etka_space_ps5, ntsc_rgb, pal_secam_rgb, pro_photo_rgb, rgb, smpte_c_rgb, wide_gamut_rgb | |

Example 1:

import { Adapter } from "@dynamize/color-utilities";

const adapted = new Adapter({
  x: 56.11537464609447,
  y: 59.56827248834963,
  z: 9.578873171265526,
}).adapt("A_B");

console.log(adapted);

Example 2:

import { Adapter } from "@dynamize/color-utilities";

const adapter = new Adapter();
const adapted = adapter
  .set({ x: 56.11537464609447, y: 59.56827248834963, z: 9.578873171265526 })
  .adapt("A_B");

console.log(adapted);

The above example is using the "adapt" method with in the Adapter. The difference being that it takes an optional second argument, which is the desired color space of returned color values.

Example 3:

import { Adapter } from "@dynamize/color-utilities";

const adapter = new Adapter();
const adapted = adapter
  .set({ x: 56.11537464609447, y: 59.56827248834963, z: 9.578873171265526 })
  .adapt("A_B", "adobe_98_rgb");

console.log(adapted);

Delta E / Color Difference

There are multiple ways to calculate the color difference or color distance. More information about color difference: https://en.wikipedia.org/wiki/Color_difference

Usage examples:

import { comparativeDistance } from "@dynamize/color-utilities";

const diff = comparativeDistance(
  { red: 238, green: 200, blue: 27 },
  { red: 217, green: 122, blue: 37 }
);

console.log(diff);

CIE 76

import { deltaECIE76Lab } from "@dynamize/color-utilities";

const diff = deltaECIE76Lab(
  {
    luminance: 81.60296053275202,
    a: -1.2482727232548951,
    b: 79.33052440955292,
  },
  { luminance: 60.61218950864361, a: 31.243719367882505, b: 58.52164206596838 }
);

console.log(diff);

import { deltaECIE76Rgb } from "@dynamize/color-utilities";

const diff = deltaECIE76Rgb(
  { red: 238, green: 200, blue: 27 },
  { red: 217, green: 122, blue: 37 }
);

console.log(diff);

CIE 94

import { deltaECIE94Lab } from "@dynamize/color-utilities";

const diff = deltaECIE94Lab(
  {
    luminance: 81.60296053275202,
    a: -1.2482727232548951,
    b: 79.33052440955292,
  },
  { luminance: 60.61218950864361, a: 31.243719367882505, b: 58.52164206596838 }
);

console.log(diff);

CIE 00

import { deltaECIE00Lab } from "@dynamize/color-utilities";

const diff = deltaECIE00Lab(
  {
    luminance: 81.60296053275202,
    a: -1.2482727232548951,
    b: 79.33052440955292,
  },
  { luminance: 60.61218950864361, a: 31.243719367882505, b: 58.52164206596838 }
);

console.log(diff);

import { deltaECIE00Rgb } from "@dynamize/color-utilities";

const diff = deltaECIE00Rgb(
  { red: 238, green: 200, blue: 27 },
  { red: 217, green: 122, blue: 37 }
);

console.log(diff);

Troubleshooting

Common Issues

Module not found: Ensure you're using a module-aware environment or bundler.

Color values incorrect: Verify input ranges (RGB: 0-255, HSL: 0-100, etc.)

Performance issues: Use standalone functions instead of Color class for single conversions.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

This project is licensed under the ISC License - see the LICENSE.md file for details.