MooColor

Common errors

• TypeError: color.lighten is not a function

  cause 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

  cause 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')

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

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

Warnings

• breaking All 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.
• breaking The `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);`.
• breaking Node.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.
• breaking The `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.
• gotcha When 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.

Install

• npm install moo-color npm
• yarn add moo-color yarn
• pnpm add moo-color pnpm

Imports

• MooColor
  wrong:

  const MooColor = require('moo-color')

  correct:

  import { MooColor } from '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
  wrong:

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

  correct:

  import { MooColor } from 'moo-color';
  const randomColor = MooColor.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
  wrong:

  import { ColorData } from 'moo-color';

  correct:

  import type { 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.

Quickstart

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());