moo-color

library2.0.0jsnpmunverified

MooColor is a modern TypeScript library designed for comprehensive color parsing, conversion, and manipulation. Currently stable at version 2.0.0, the package maintains an active release cadence with minor updates and patches, and announces significant breaking changes with major versions. Key differentiators include its strictly immutable API, where all manipulation methods return new instances rather than mutating the original, and robust WCAG 2.1 compliance for accurate luminance and contrast ratio calculations. It provides dual ESM, CJS, and IIFE bundles, making it versatile across Node.js environments (requiring Node.js >=18 since v2) and browsers. The library is fully typed, including Template Literal Types for advanced color string representation, and supports a wide array of color models like hex, RGB, HSL, HWB, HSV, and CMYK, alongside named colors.

serialization

npm install moo-color

github ↗package ↗

INSTALL

IMPORT

SIG · MOO-COLOR

moo-color

serializationjavascriptv2.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MooColor

✓ import { MooColor } from 'moo-color'

✗ const MooColor = require('moo-color')

Since v2.0.0, `MooColor` is the primary named export for ESM/TypeScript. For CommonJS, use `const { MooColor } = require('moo-color');`. The global IIFE bundle exposes `MooColor` directly on `window`.

MooColor.random

✓ import { MooColor } from 'moo-color'; const randomColor = MooColor.random();

✗ const color = new MooColor('red'); const randomColor = color.random();

The `random()` method was changed to a static method of the `MooColor` class in v0.2.0. Calling it as an instance method will result in a runtime error.

ColorData

✓ import type { ColorData } from 'moo-color';

✗ import { ColorData } from 'moo-color';

Use `import type` for importing type definitions like `ColorData` to ensure they are stripped during compilation and do not result in runtime module imports.

This quickstart demonstrates parsing various color formats, performing immutable manipulations, chaining methods, checking WCAG contrast ratios, and generating constrained random colors.

import { MooColor } from 'moo-color'; // Parse various color formats, including named colors and RGBA const red = new MooColor('red'); const semiTransparentBlue = new MooColor('rgba(0, 0, 255, 0.7)'); const orangeHsl = new MooColor('hsl(30, 100%, 50%)'); console.log('Original Red (hex):', red.toHex()); // #ff0000 // Manipulation methods return new instances (immutable API since v2.0.0) const lightenedRed = red.lighten(20); const desaturatedBlue = semiTransparentBlue.desaturate(30); console.log('Lightened Red (hex):', lightenedRed.toHex()); // Example: #ff6666 console.log('Original Red is unchanged:', red.toHex()); // #ff0000 // Chaining operations const adjustedOrange = orangeHsl .rotate(60) // Rotate hue by 60 degrees .saturate(15) // Increase saturation .darken(10) // Darken the color .setAlpha(0.9); // Set transparency console.log('Adjusted Orange (RGBA):', adjustedOrange.toRgba()); // Example: rgba(..., 0.9) // WCAG contrast ratio check const white = new MooColor('#fff'); const black = new MooColor('#000'); console.log('Contrast Ratio (Black vs White):', black.contrastRatioWith(white)); // 21 // Generate a random color with specific constraints const randomWarmColor = MooColor.random({ hue: [0, 60], saturation: [50, 100] }); console.log('Random warm color:', randomWarmColor.toHsl());

Debug

Known issues

breakingAll color manipulation methods (`lighten`, `darken`, `saturate`, `grayscale`, `whiten`, `blacken`, `rotate`, `complement`, `invert`), `setAlpha()`, and `changeModel()` now return a new `MooColor` instance instead of mutating the original object.

fix

Chain methods or assign the return value to a new variable. Do not assume the original instance is modified; always use the return value of these methods.

affects: >=2.0.0

breakingThe `setColor()` instance method has been completely removed.

fix

Use the `MooColor` constructor directly to create a new instance with the desired color, e.g., `const newColor = new MooColor(newColorString);`.

affects: >=2.0.0

breakingNode.js version 18 or higher is now required. Running the package in older Node.js environments will result in errors.

fix

Ensure your project's Node.js environment is updated to version 18 or newer. Check your `package.json` engines field or global Node.js version.

affects: >=2.0.0

breakingThe `random()` method was changed from an instance method (`new MooColor().random()`) to a static method (`MooColor.random()`) of the `MooColor` class.

fix

Call `MooColor.random()` directly on the `MooColor` class rather than on an instance.

affects: >=0.2.0

gotchaWhen formatting colors to hexadecimal, the `toHex()` method's `mode` argument (introduced in v0.1.1) allows control over the output format ('full', 'short', or 'name'). Without specifying, it defaults to full hex.

fix

To get a specific hex format, use `color.toHex('short')` for `#f00` or `color.toHex('name')` for named colors like 'red' where applicable.

affects: >=0.1.1

Errors

Common errors & fixes

TypeError: color.lighten is not a function

Attempting to call a manipulation method on a `MooColor` instance that was not correctly assigned after an immutable operation (post v2.0.0) or if `color` is not a `MooColor` instance.

fix

Ensure you are using the return value of manipulation methods, as they now return new instances. For example, `const newColor = originalColor.lighten(10);`.

TypeError: color.setColor is not a function

Calling the `setColor()` method, which was removed in `moo-color` v2.0.0.

fix

Instead of `color.setColor('blue')`, create a new instance with the desired color: `const blueColor = new MooColor('blue');`.

TypeError: Cannot read properties of undefined (reading 'random')

Attempting to call the `random()` method on an instance of `MooColor` (`new MooColor().random()`) after v0.2.0, when it became a static method.

fix

Call `MooColor.random()` as a static method directly on the class.

Error: Cannot find module 'moo-color' (when running on older Node.js versions)

Running `moo-color` v2.0.0+ in a Node.js environment older than version 18.

fix

Upgrade your Node.js runtime to version 18 or higher to meet the package's engine requirements.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/archco/moo-color ↗

packagehttps://www.npmjs.com/package/moo-color ↗