{"id":11360,"library":"moo-color","title":"MooColor","description":"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.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/archco/moo-color","tags":["javascript","color","color-conversion","color-manipulation","hex","rgb","hsl","hwb","hsv","typescript"],"install":[{"cmd":"npm install moo-color","lang":"bash","label":"npm"},{"cmd":"yarn add moo-color","lang":"bash","label":"yarn"},{"cmd":"pnpm add moo-color","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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`.","wrong":"const MooColor = require('moo-color')","symbol":"MooColor","correct":"import { MooColor } from 'moo-color'"},{"note":"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.","wrong":"const color = new MooColor('red');\nconst randomColor = color.random();","symbol":"MooColor.random","correct":"import { MooColor } from 'moo-color';\nconst randomColor = MooColor.random();"},{"note":"Use `import type` for importing type definitions like `ColorData` to ensure they are stripped during compilation and do not result in runtime module imports.","wrong":"import { ColorData } from 'moo-color';","symbol":"ColorData","correct":"import type { ColorData } from 'moo-color';"}],"quickstart":{"code":"import { MooColor } from 'moo-color';\n\n// Parse various color formats, including named colors and RGBA\nconst red = new MooColor('red');\nconst semiTransparentBlue = new MooColor('rgba(0, 0, 255, 0.7)');\nconst orangeHsl = new MooColor('hsl(30, 100%, 50%)');\n\nconsole.log('Original Red (hex):', red.toHex()); // #ff0000\n\n// Manipulation methods return new instances (immutable API since v2.0.0)\nconst lightenedRed = red.lighten(20);\nconst desaturatedBlue = semiTransparentBlue.desaturate(30);\n\nconsole.log('Lightened Red (hex):', lightenedRed.toHex()); // Example: #ff6666\nconsole.log('Original Red is unchanged:', red.toHex()); // #ff0000\n\n// Chaining operations\nconst adjustedOrange = orangeHsl\n  .rotate(60) // Rotate hue by 60 degrees\n  .saturate(15) // Increase saturation\n  .darken(10) // Darken the color\n  .setAlpha(0.9); // Set transparency\n\nconsole.log('Adjusted Orange (RGBA):', adjustedOrange.toRgba()); // Example: rgba(..., 0.9)\n\n// WCAG contrast ratio check\nconst white = new MooColor('#fff');\nconst black = new MooColor('#000');\nconsole.log('Contrast Ratio (Black vs White):', black.contrastRatioWith(white)); // 21\n\n// Generate a random color with specific constraints\nconst randomWarmColor = MooColor.random({ hue: [0, 60], saturation: [50, 100] });\nconsole.log('Random warm color:', randomWarmColor.toHsl());","lang":"typescript","description":"This quickstart demonstrates parsing various color formats, performing immutable manipulations, chaining methods, checking WCAG contrast ratios, and generating constrained random colors."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use the `MooColor` constructor directly to create a new instance with the desired color, e.g., `const newColor = new MooColor(newColorString);`.","message":"The `setColor()` instance method has been completely removed.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"Node.js version 18 or higher is now required. Running the package in older Node.js environments will result in errors.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Call `MooColor.random()` directly on the `MooColor` class rather than on an instance.","message":"The `random()` method was changed from an instance method (`new MooColor().random()`) to a static method (`MooColor.random()`) of the `MooColor` class.","severity":"breaking","affected_versions":">=0.2.0"},{"fix":"To get a specific hex format, use `color.toHex('short')` for `#f00` or `color.toHex('name')` for named colors like 'red' where applicable.","message":"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.","severity":"gotcha","affected_versions":">=0.1.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you are using the return value of manipulation methods, as they now return new instances. For example, `const newColor = originalColor.lighten(10);`.","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.","error":"TypeError: color.lighten is not a function"},{"fix":"Instead of `color.setColor('blue')`, create a new instance with the desired color: `const blueColor = new MooColor('blue');`.","cause":"Calling the `setColor()` method, which was removed in `moo-color` v2.0.0.","error":"TypeError: color.setColor is not a function"},{"fix":"Call `MooColor.random()` as a static method directly on the class.","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.","error":"TypeError: Cannot read properties of undefined (reading 'random')"},{"fix":"Upgrade your Node.js runtime to version 18 or higher to meet the package's engine requirements.","cause":"Running `moo-color` v2.0.0+ in a Node.js environment older than version 18.","error":"Error: Cannot find module 'moo-color' (when running on older Node.js versions)"}],"ecosystem":"npm"}