{"id":10626,"library":"chromatism","title":"Chromatism Color Utilities","description":"Chromatism is a lightweight JavaScript utility library designed for comprehensive color manipulation, offering a rich set of functions for color transformations, conversions, and metering. It supports various color types including RGB, HSL, Hex, CMYK, and can intelligently process mixed input types. The current stable version is 3.0.0, which marked a significant breaking change focused on optimizing for ES Modules (ESM) to achieve the smallest possible bundle sizes. Key differentiators include its strong emphasis on ESM for tree-shaking, the implementation of uniform hue-shifting transforms using HSLuv for more accurate color adjustments, and an efficient internal conversion chain. The library also ships with first-class TypeScript definitions, enhancing developer experience and type safety. While previous major versions supported function chaining, v3.0.0 removed this pattern in favor of a more functional, direct API.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/toish/chromatism","tags":["javascript","color","colour","utility","hue","chroma","CMYK","RGB","HSL","typescript"],"install":[{"cmd":"npm install chromatism","lang":"bash","label":"npm"},{"cmd":"yarn add chromatism","lang":"bash","label":"yarn"},{"cmd":"pnpm add chromatism","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Prefer named imports for tree-shaking and smaller bundles. Since v3.0.0, the library is optimized for ES Modules.","wrong":"const { brightness } = require('chromatism');","symbol":"brightness","correct":"import { brightness } from 'chromatism';"},{"note":"This pattern provides access to all utility functions via the `chromatism` namespace object. While CommonJS `require` might still work in some legacy environments, v3.0.0 is primarily designed for ESM.","wrong":"const chromatism = require('chromatism');","symbol":"* as chromatism","correct":"import * as chromatism from 'chromatism';"},{"note":"Type definitions are included with the package, enabling strong typing for color objects and function parameters in TypeScript projects.","symbol":"RGB, HEX","correct":"import type { RGB, HEX } from 'chromatism';"}],"quickstart":{"code":"import { convert, shade, invert, complementary, rgb } from 'chromatism';\n\n// Start with a hex color\nconst baseHex = '#FF6347'; // Tomato\n\n// Convert to RGB and then apply a shade adjustment\nconst shadedColor = shade(15, convert(baseHex).rgb);\nconsole.log('Shaded Color (RGB):', shadedColor.rgb); // Access specific format\nconsole.log('Shaded Color (HEX):', shadedColor.hex);\n\n// Get the complementary color in HSL\nconst complementaryColor = complementary(baseHex).hsl;\nconsole.log('Complementary Color (HSL):', complementaryColor);\n\n// Invert the original color\nconst invertedColor = invert(baseHex).rgb;\nconsole.log('Inverted Color (RGB):', invertedColor);\n\n// Example with direct RGB input and brightness adjustment\nconst newColor = rgb(255, 0, 0); // Red\nconst brighterRed = shade(-20, newColor); // shade can also brighten\nconsole.log('Brighter Red (HEX):', brighterRed.hex);","lang":"typescript","description":"Demonstrates core color manipulation functions like conversion, shading, inversion, and generating complementary colors, showcasing various input/output formats."},"warnings":[{"fix":"Refactor chained calls into separate function invocations, passing the output of one function as the input to the next. Access the desired output format via getters like `.hex` or `.rgb` on the returned color object.","message":"Function chaining, a core feature in pre-v2.x versions, was entirely removed in v3.0.0. Functions now return color objects with getters for various types (e.g., `.hex`, `.rgb`), requiring a functional approach rather than chained method calls.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"If these constants are critical for your application, you may need to implement them manually or consider using an older major version of the library (e.g., v2.x) that still included them. Explore alternative libraries if specific CIE-related constants are needed.","message":"Illuminant and Transformation Matrix constants were removed in v3.0.0 to streamline the library and reduce its bundle size. If your application relied on these specific constants, they are no longer available directly from the library.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure your project is configured to properly resolve ES Modules (e.g., `\"type\": \"module\"` in `package.json` or configuring your bundler like Rollup/Webpack for ESM) and consistently use `import` syntax.","message":"Version 3.0.0 is heavily optimized for ES Modules (ESM) and is shipped with a `pkg.module` entry. While CommonJS `require()` might still function in some environments, for optimal bundle size and adherence to modern JavaScript standards, always use `import` statements.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Upgrade to `chromatism` v2.5.8 or a newer version to benefit from the included TypeScript definitions. If upgrading is not feasible, consider installing `@types/chromatism` (if available for your version) or create custom declaration files.","message":"Prior to v2.5.8, TypeScript definitions for `chromatism` were either missing or incomplete. While the library now ships with built-in types, older versions might lead to type errors or require external `@types/chromatism` packages.","severity":"gotcha","affected_versions":"<2.5.8"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For ES Modules, use `import { someFunction } from 'chromatism';` for individual functions or `import * as chromatism from 'chromatism';` and then `chromatism.someFunction(...)`. If targeting a CommonJS environment that still supports the library, ensure `const chromatism = require('chromatism');` is used before accessing `chromatism.someFunction(...)`.","cause":"Attempting to use named exports with CommonJS `require()` or incorrect ES Module import syntax.","error":"chromatism.someFunction is not a function"},{"fix":"Refactor your code to use individual function calls. For example, instead of `chromatism.chain(color).shade(10).hex`, you would write `const intermediateColor = chromatism.convert(color); const finalColor = chromatism.shade(10, intermediateColor.rgb); const hexValue = finalColor.hex;`","cause":"Attempting to use the deprecated function chaining API that was removed in v3.0.0.","error":"TypeError: chromatism.chain is not a function"},{"fix":"Ensure you are using the full color object returned by chromatism functions to access format getters. For example, `const myColor = chromatism.shade(10, baseColor); myColor.hex;` is correct. If you have a raw `{ r, g, b }` object, convert it first: `chromatism.convert({ r: 255, g: 0, b: 0 }).hex;`","cause":"While many functions return a full color object with getters (like `.hex`, `.rgb`), you might be accessing a raw color component object (e.g., `{ r, g, b }`) directly from a destructured result or an intermediate step that hasn't been converted to the full chromatism color object.","error":"Property 'hex' does not exist on type '{ r: number; g: number; b: number; }' (or similar color object without getters)."}],"ecosystem":"npm"}