{"id":10650,"library":"color-fns","title":"color-fns: Modern Color Utility Library","description":"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.","status":"active","version":"0.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/baianat/color-fns","tags":["javascript","color","utility","functions","typescript"],"install":[{"cmd":"npm install color-fns","lang":"bash","label":"npm"},{"cmd":"yarn add color-fns","lang":"bash","label":"yarn"},{"cmd":"pnpm add color-fns","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This library is primarily designed for ES Modules and ships TypeScript types. Prefer named imports.","wrong":"const { toRgb } = require('color-fns'); // Incorrect in modern ESM projects","symbol":"toRgb","correct":"import { toRgb } from 'color-fns';"},{"note":"Functions are individual named exports for optimal tree-shaking. There are no default exports for the library as a whole.","wrong":"import mix from 'color-fns/mix'; // Not a default export, and direct path imports are generally not recommended for tree-shaking.","symbol":"mix","correct":"import { mix } from 'color-fns';"},{"note":"The `ColorFns` global is only available when using the UMD build via a script tag in a browser environment.","wrong":"console.log(ColorFns.formatHex('#abc')); // Only for UMD global in browsers","symbol":"formatHex","correct":"import { formatHex } from 'color-fns';"}],"quickstart":{"code":"import { parseHex, toRgb, rgbToHsl, mix, formatHex, isValidHex } from 'color-fns';\n\n// 1. Parse a hex color string into an RGB object\nconst hexRed = '#FF0000';\nconst redRgb = parseHex(hexRed); // { r: 255, g: 0, b: 0 }\nconsole.log(`Parsed '${hexRed}' to RGB:`, redRgb);\n\n// 2. Convert RGB to HSL\nconst blueRgb = { r: 0, g: 0, b: 255 };\nconst blueHsl = rgbToHsl(blueRgb); // { h: 240, s: 1, l: 0.5 }\nconsole.log(`Converted RGB ${JSON.stringify(blueRgb)} to HSL:`, blueHsl);\n\n// 3. Mix two RGB colors\nconst mixedRgb = mix(redRgb, blueRgb, 0.5); // Mixes red and blue 50/50 to produce purple\nconsole.log('Mixed Red and Blue (50/50) to RGB:', mixedRgb);\n\n// 4. Format an RGB color object back to a hex string\nconst formattedMixedHex = formatHex(mixedRgb);\nconsole.log('Formatted mixed RGB to Hex string:', formattedMixedHex); // e.g., '#800080'\n\n// 5. Validate a color string\nconst validHex = '#ABC';\nconst invalidHex = '#XYZ';\nconsole.log(`Is '${validHex}' a valid hex string?`, isValidHex(validHex)); // true\nconsole.log(`Is '${invalidHex}' a valid hex string?`, isValidHex(invalidHex)); // false","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"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 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');`.","cause":"Attempting to use CommonJS `require` syntax or incorrect named imports in an ES Modules (ESM) or bundler environment that expects ESM.","error":"TypeError: (0 , color_fns__WEBPACK_IMPORTED_MODULE_0__.toRgb) is not a function"},{"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');`.","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.","error":"ReferenceError: ColorFns is not defined"}],"ecosystem":"npm"}