color-fns: Modern Color Utility Library

0.1.1 · active · verified Sun Apr 19

color-fns is a modern, modular, and tree-shakable JavaScript utility library designed for comprehensive color manipulation and conversion. Inspired by the API design of `date-fns`, it emphasizes lightweight, individual function imports for optimal bundle sizes. The current stable version is 0.1.1, following a significant rewrite in version 0.1.0 that introduced a new, TypeScript-first API with reduced overloads and clearer handling of color values. The library supports multiple color models (RGB, HSL, HSV, CMYK, Hex) and offers functions for parsing, conversion, operations (like mixing), formatting to CSS-compatible output, validation, and querying (e.g., contrast, darkness). While still in pre-1.0 status, its development appears active, with a focus on type safety and modern JavaScript practices. Key differentiators include its modularity, explicit TypeScript types, and a clear, functional API.

Common errors

```
TypeError: (0 , color_fns__WEBPACK_IMPORTED_MODULE_0__.toRgb) is not a function
```
cause Attempting to use CommonJS `require` syntax or incorrect named imports in an ES Modules (ESM) or bundler environment that expects ESM.

fix Ensure you are using ES module imports (e.g., `import { toRgb } from 'color-fns';`) and that your build tools are configured to handle ESM correctly. For CommonJS-only environments, use `const { toRgb } = require('color-fns');`.
```
ReferenceError: ColorFns is not defined
```
cause This error occurs when trying to use the global `ColorFns` object without having included the UMD build via a `<script>` tag in a browser, or by trying to use it in a Node.js/bundler environment without proper module imports.

fix For browser usage with a script tag, ensure `<script src="https://unpkg.com/color-fns"></script>` is loaded *before* your script attempts to use `ColorFns`. For module environments (Node.js, bundlers), use `import { functionName } from 'color-fns';` or `const { functionName } = require('color-fns');`.

Warnings

breaking Version 0.1.0 introduced a complete rewrite of the library in TypeScript, leading to a new API for all methods. This significantly changed how color values are accepted and processed, reducing overloads and confusion. Code written for versions prior to 0.1.0 will not be compatible.
Fix: Consult the documentation for `color-fns` version 0.1.x for the updated API. Specifically review how color inputs are provided to functions, as previous 'acceptable color values' may no longer be supported or handled differently.
gotcha As the library is currently in pre-1.0 status (v0.1.1), future minor or patch releases *could* introduce further breaking changes before a stable 1.0 release is made. API stability is not guaranteed until version 1.0 or higher.
Fix: Pin your `color-fns` dependency to exact versions (e.g., '0.1.1') to ensure consistent behavior, and review release notes carefully when upgrading to newer pre-1.0 versions.

Install

npm install color-fns npm
yarn add color-fns yarn
pnpm add color-fns pnpm

Imports

toRgb
wrong:
```
const { toRgb } = require('color-fns'); // Incorrect in modern ESM projects
```
correct:
```
import { toRgb } from 'color-fns';
```
This library is primarily designed for ES Modules and ships TypeScript types. Prefer named imports.

mix

wrong:

import mix from 'color-fns/mix'; // Not a default export, and direct path imports are generally not recommended for tree-shaking.

correct:

import { mix } from 'color-fns';

Functions are individual named exports for optimal tree-shaking. There are no default exports for the library as a whole.

formatHex
wrong:
```
console.log(ColorFns.formatHex('#abc')); // Only for UMD global in browsers
```
correct:
```
import { formatHex } from 'color-fns';
```
The `ColorFns` global is only available when using the UMD build via a script tag in a browser environment.

Quickstart

Demonstrates parsing hex colors, converting between models (RGB to HSL), mixing colors, formatting output back to hex, and validating color strings using the `color-fns` library.

import { parseHex, toRgb, rgbToHsl, mix, formatHex, isValidHex } from 'color-fns';

// 1. Parse a hex color string into an RGB object
const hexRed = '#FF0000';
const redRgb = parseHex(hexRed); // { r: 255, g: 0, b: 0 }
console.log(`Parsed '${hexRed}' to RGB:`, redRgb);

// 2. Convert RGB to HSL
const blueRgb = { r: 0, g: 0, b: 255 };
const blueHsl = rgbToHsl(blueRgb); // { h: 240, s: 1, l: 0.5 }
console.log(`Converted RGB ${JSON.stringify(blueRgb)} to HSL:`, blueHsl);

// 3. Mix two RGB colors
const mixedRgb = mix(redRgb, blueRgb, 0.5); // Mixes red and blue 50/50 to produce purple
console.log('Mixed Red and Blue (50/50) to RGB:', mixedRgb);

// 4. Format an RGB color object back to a hex string
const formattedMixedHex = formatHex(mixedRgb);
console.log('Formatted mixed RGB to Hex string:', formattedMixedHex); // e.g., '#800080'

// 5. Validate a color string
const validHex = '#ABC';
const invalidHex = '#XYZ';
console.log(`Is '${validHex}' a valid hex string?`, isValidHex(validHex)); // true
console.log(`Is '${invalidHex}' a valid hex string?`, isValidHex(invalidHex)); // false

view raw JSON →