Chromatism Color Utilities

Common errors

• chromatism.someFunction is not a function

  cause Attempting to use named exports with CommonJS `require()` or incorrect ES Module import syntax.
  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(...)`.

• TypeError: chromatism.chain is not a function

  cause Attempting to use the deprecated function chaining API that was removed in v3.0.0.
  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;`

• Property 'hex' does not exist on type '{ r: number; g: number; b: number; }' (or similar color object without getters).

  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.
  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;`

Warnings

• breaking 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install chromatism npm
• yarn add chromatism yarn
• pnpm add chromatism pnpm

Imports

• brightness
  wrong:

  const { brightness } = require('chromatism');

  correct:

  import { brightness } from 'chromatism';

  Prefer named imports for tree-shaking and smaller bundles. Since v3.0.0, the library is optimized for ES Modules.
• * as chromatism
  wrong:

  const chromatism = require('chromatism');

  correct:

  import * as chromatism from 'chromatism';

  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.
• RGB, HEX

  import type { RGB, HEX } from 'chromatism';

  Type definitions are included with the package, enabling strong typing for color objects and function parameters in TypeScript projects.

Quickstart

Demonstrates core color manipulation functions like conversion, shading, inversion, and generating complementary colors, showcasing various input/output formats.

import { convert, shade, invert, complementary, rgb } from 'chromatism';

// Start with a hex color
const baseHex = '#FF6347'; // Tomato

// Convert to RGB and then apply a shade adjustment
const shadedColor = shade(15, convert(baseHex).rgb);
console.log('Shaded Color (RGB):', shadedColor.rgb); // Access specific format
console.log('Shaded Color (HEX):', shadedColor.hex);

// Get the complementary color in HSL
const complementaryColor = complementary(baseHex).hsl;
console.log('Complementary Color (HSL):', complementaryColor);

// Invert the original color
const invertedColor = invert(baseHex).rgb;
console.log('Inverted Color (RGB):', invertedColor);

// Example with direct RGB input and brightness adjustment
const newColor = rgb(255, 0, 0); // Red
const brighterRed = shade(-20, newColor); // shade can also brighten
console.log('Brighter Red (HEX):', brighterRed.hex);