🎨 @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 doruk.karaboncuk@interaktifis.com

📄 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: doruk.karaboncuk@interaktifis.com
GitHub Issues: Create an issue

Made with ❤️ by @chaisser

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
src		src
test		test
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

🎨 @chaisser/color-utils

✨ Features

📦 Installation

🚀 Quick Start

📖 What It Does

🎯 How It Works

🎨 What It's Useful For

💡 Usage Examples

Hex to RGB

RGB to Hex

RGB to HSL

HSL to RGB

HSL to Hex / Hex to HSL

Lighten and Darken

Brightness Detection

Hex Validation

RGB String Output

📚 API Reference

Conversions

Manipulation

Detection

Formatting

Interfaces

🔗 Related Packages

🔒 License

👨 Developed by

📄 Repository

🤝 Contributing

📞 Support

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages