🎨 @chaisser/color-utils

Color conversion and manipulation: hex, RGB, HSL, lighten, darken, brightness detection

✨ Features

• 🎯 Type-safe - Full TypeScript support with RGB, HSL, RGBA, HSLA interfaces
• 🔄 Conversions - Hex ↔ RGB ↔ HSL with multiple calling conventions
• ☀️ Lighten & Darken - Adjust color brightness by amount
• 📏 Brightness - Calculate perceived brightness and detect light/dark colors
• ✅ Validation - Check if a string is a valid hex color
• 📝 String output - Convert any color to CSS rgb() string
• 🪶 Zero dependencies - Lightweight and tree-shakeable
• 🏎️ ESM + CJS - Dual module format support

📦 Installation

npm install @chaisser/color-utils
# or
yarn add @chaisser/color-utils
# or
pnpm add @chaisser/color-utils

🚀 Quick Start

import {
  hexToRgb,
  rgbToHex,
  rgbToHsl,
  hslToRgb,
  lighten,
  darken,
  isLight,
  isDark,
} from '@chaisser/color-utils';

// Convert between formats
hexToRgb('#ff6600');             // { r: 255, g: 102, b: 0 }
rgbToHex(255, 102, 0);           // '#ff6600'
rgbToHsl(255, 102, 0);           // { h: 24, s: 100, l: 50 }
hslToRgb(24, 100, 50);          // { r: 255, g: 102, b: 0 }

// Lighten and darken
lighten('#ff6600', 20);          // '#ff9933'
darken('#ff6600', 20);           // '#cc5200'

// Brightness detection
isLight('#ffffff');               // true
isDark('#000000');                // true

📖 What It Does

This package provides color conversion and manipulation utilities for JavaScript and TypeScript. It handles conversions between hex, RGB, and HSL color spaces, lets you lighten or darken colors, calculates perceived brightness, and detects whether a color is light or dark.

🎯 How It Works

The package provides conversion and manipulation functions:

• Conversions - hexToRgb, rgbToHex, rgbToHsl, hslToRgb, hslToHex, hexToHsl
• Manipulation - lighten, darken
• Detection - getBrightness, isLight, isDark
• Validation - isHexColor
• Formatting - toRgbString

All conversion functions accept either individual values or object arguments.

🎨 What It's Useful For

• Theme Systems - Generate color palettes from a base color
• UI Components - Auto-detect text color based on background brightness
• Data Visualization - Lighten/darken chart colors
• CSS-in-JS - Convert colors between formats for style calculations
• Accessibility - Check contrast ratios and color brightness
• Design Tools - Color picker utilities and format conversion

💡 Usage Examples

Hex to RGB

import { hexToRgb } from '@chaisser/color-utils';

hexToRgb('#ff6600');   // { r: 255, g: 102, b: 0 }
hexToRgb('ff6600');    // { r: 255, g: 102, b: 0 }  — # is optional
hexToRgb('#f60');      // { r: 255, g: 102, b: 0 }  — shorthand

RGB to Hex

import { rgbToHex } from '@chaisser/color-utils';

rgbToHex(255, 102, 0);         // '#ff6600'
rgbToHex({ r: 255, g: 102, b: 0 }); // '#ff6600' — object form

RGB to HSL

import { rgbToHsl } from '@chaisser/color-utils';

rgbToHsl(255, 102, 0);          // { h: 24, s: 100, l: 50 }
rgbToHsl({ r: 255, g: 102, b: 0 }); // { h: 24, s: 100, l: 50 }

HSL to RGB

import { hslToRgb } from '@chaisser/color-utils';

hslToRgb(24, 100, 50);          // { r: 255, g: 102, b: 0 }
hslToRgb({ h: 24, s: 100, l: 50 }); // { r: 255, g: 102, b: 0 }

HSL to Hex / Hex to HSL

import { hslToHex, hexToHsl } from '@chaisser/color-utils';

hslToHex(0, 100, 50);           // '#ff0000'
hslToHex({ h: 0, s: 100, l: 50 }); // '#ff0000'

hexToHsl('#ff0000');             // { h: 0, s: 100, l: 50 }

Lighten and Darken

import { lighten, darken } from '@chaisser/color-utils';

// Works with hex strings, RGB objects, or HSL objects
lighten('#336699', 20);          // '#5c8cb3'
darken('#336699', 20);           // '#1a334d'

lighten({ r: 51, g: 102, b: 153 }, 15); // hex string result
darken({ h: 210, s: 50, l: 40 }, 10);    // hex string result

Brightness Detection

import { getBrightness, isLight, isDark } from '@chaisser/color-utils';

getBrightness('#ffffff');         // 255
getBrightness('#000000');         // 0
getBrightness('#ff6600');         // 158

isLight('#ffffff');               // true
isLight('#ff6600');               // true

isDark('#000000');                // true
isDark('#333333');                // true

// Custom threshold (default: 128)
isLight('#888888', 100);         // true (brightness 136 > 100)

Hex Validation

import { isHexColor } from '@chaisser/color-utils';

isHexColor('#ff6600');           // true
isHexColor('#f60');              // true
isHexColor('ff6600');           // false — missing #
isHexColor('#gg6600');          // false — invalid chars

RGB String Output

import { toRgbString } from '@chaisser/color-utils';

toRgbString('#ff6600');          // 'rgb(255, 102, 0)'
toRgbString({ r: 255, g: 102, b: 0 }); // 'rgb(255, 102, 0)'

📚 API Reference

Conversions

| Function | Input | Output | |---|---|---| | hexToRgb(hex) | string | RGB | | rgbToHex(r, g, b) or rgbToHex(rgb) | numbers or RGB | string | | rgbToHsl(r, g, b) or rgbToHsl(rgb) | numbers or RGB | HSL | | hslToRgb(h, s, l) or hslToRgb(hsl) | numbers or HSL | RGB | | hslToHex(h, s, l) or hslToHex(hsl) | numbers or HSL | string | | hexToHsl(hex) | string | HSL |

Manipulation

| Function | Input | Output | Description | |---|---|---|---| | lighten(color, amount) | string \| RGB \| HSL, number | string | Increase lightness by amount (0-100) | | darken(color, amount) | string \| RGB \| HSL, number | string | Decrease lightness by amount (0-100) |

Detection

| Function | Input | Output | Description | |---|---|---|---| | getBrightness(color) | string \| RGB | number | Perceived brightness (0-255) | | isLight(color, threshold?) | string \| RGB, number | boolean | Brightness > threshold (default: 128) | | isDark(color, threshold?) | string \| RGB, number | boolean | Brightness <= threshold (default: 128) | | isHexColor(hex) | string | boolean | Valid hex color check |

Formatting

| Function | Input | Output | Description | |---|---|---|---| | toRgbString(color) | string \| RGB | string | CSS rgb(r, g, b) string |

Interfaces

interface RGB  { r: number; g: number; b: number }
interface HSL  { h: number; s: number; l: number }
interface RGBA extends RGB { a: number }
interface HSLA extends HSL { a: number }

🔗 Related Packages

Explore our other utility packages in the @chaisser namespace:

• @chaisser/color-utils (this package) - Color conversion and manipulation
• @chaisser/string-wizard - Advanced string manipulation
• @chaisser/type-guard - Runtime type guards and validators
• @chaisser/uuid-v7 - Time-ordered UUID v7 generator
• @chaisser/wait-for - Promise-based wait utilities
• @chaisser/regex-humanizer - Regex to human-readable descriptions
• @chaisser/password-strength - Password strength checker
• @chaisser/human-time - Human-readable time formatting
• @chaisser/obj-path - Safe dot-notation object access
• @chaisser/debounce-throttle - Rate limiting utilities
• @chaisser/deep-clone - Deep cloning functions
• @chaisser/array-group-by - Array grouping utilities
• @chaisser/merge-objects - Object merge utilities
• @chaisser/chunk-array - Array chunking functions
• @chaisser/event-emitter - Typed event emitter

🔒 License

MIT - Free to use in personal and commercial projects

👨 Developed by

Doruk Karaboncuk [email protected]

📄 Repository

• GitHub: @chaisser
• NPM: @chaisser/color-utils

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest new features
• Submit pull requests
• Improve documentation

📞 Support

For issues, questions, or suggestions, please reach out through:

• Email: [email protected]
• GitHub Issues: Create an issue

Made with ❤️ by @chaisser