color-fns

library0.1.1jsnpmunverified

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.

serialization

npm install color-fns

github ↗package ↗

INSTALL

IMPORT

SIG · COLOR-FNS

color-fns

serializationjavascriptv0.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

toRgb

✓ import { toRgb } from 'color-fns';

✗ const { toRgb } = require('color-fns'); // Incorrect in modern ESM projects

This library is primarily designed for ES Modules and ships TypeScript types. Prefer named imports.

mix

✓ import { mix } from 'color-fns';

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

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

formatHex

✓ import { formatHex } from 'color-fns';

✗ console.log(ColorFns.formatHex('#abc')); // Only for UMD global in browsers

The `ColorFns` global is only available when using the UMD build via a script tag in a browser environment.

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

Debug

Known issues

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

affects: <0.1.0

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

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: (0 , color_fns__WEBPACK_IMPORTED_MODULE_0__.toRgb) is not a function

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

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

Upgrade

Version history

0.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/baianat/color-fns ↗

packagehttps://www.npmjs.com/package/color-fns ↗