https://github.com/iamlite/color-core
`color-core` is a powerful, type-safe color manipulation library for TypeScript and JavaScript applications. It provides a comprehensive toolkit for working with colors across multiple color spaces, making it an indispensable tool for developers working on projects that require advanced color handling.
https://github.com/iamlite/color-core
Last synced: 11 months ago
JSON representation
`color-core` is a powerful, type-safe color manipulation library for TypeScript and JavaScript applications. It provides a comprehensive toolkit for working with colors across multiple color spaces, making it an indispensable tool for developers working on projects that require advanced color handling.
- Host: GitHub
- URL: https://github.com/iamlite/color-core
- Owner: iamlite
- License: mit
- Created: 2024-07-10T04:58:28.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-01-17T17:01:19.000Z (12 months ago)
- Last Synced: 2025-02-26T05:54:03.217Z (11 months ago)
- Language: TypeScript
- Homepage: https://color-core.com
- Size: 12.9 MB
- Stars: 10
- Watchers: 1
- Forks: 1
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-typescript - Color-Core - `color-core` is a powerful, type-safe color manipulation library for TypeScript and JavaScript applications. It provides a comprehensive toolkit for working with colors across multiple color spaces, making it an indispensable tool for developers working on projects that require advanced color handling. (Built with TypeScript / Libraries)
README
---
---
`color-core` is a comprehensive, type-safe color manipulation library for TypeScript and JavaScript applications. It provides a powerful toolkit for working with colors across multiple color spaces, making it an essential tool for developers working on projects that require advanced color handling.
## Features
- 🎨 Support for 22 color spaces: RGB, sRGB, Adobe RGB, HEX, HSL, HSV, HSI, HWB, CMYK, LCH, LAB(D50), LAB(D60), XYZ(D50), XYZ(D65), YUV, Oklab, Oklch, HSLuv, HPLuv, CIExyY, and CIELuv
- 🔄 Easy color conversions between all supported formats
- 🌈 Generate color harmonies (complementary, analogous, triadic, tetradic, split-complementary, and more)
- 🛠 Powerful color manipulation tools (adjust lightness, saturation, hue, alpha, and more)
- 💪 Full TypeScript support with type safety
- 🔌 Seamless IDE integration
- 🧠 Color naming and information retrieval
- 🔦 Brightness calculation and light/dark color detection
- 🚀 Optimized for modern web applications
## Installation
```bash
npm i color-core
```
---
## Usage
`color-core` is designed to simplify color manipulation for developers and designers. Whether you're working on web applications, data visualization, or graphic design, this library provides the tools you need to handle colors efficiently across various formats and color spaces. Let's explore how to use `color-core` in your projects. The following examples demonstrate key functionalities of the library, from basic color conversions to more advanced color manipulations
### The Color Class
The `Color` class is the heart of `color-core`. It provides a unified way to create, convert, and manipulate colors across different color spaces.
See it in action ⤵️
```typescript
import { Color } from 'color-core';
// Create a color from different formats
const red = new Color('#ff0000');
const green = new Color({ r: 0, g: 255, b: 0 });
const blue = new Color({ h: 240, s: 100, l: 50 });
// Convert to different formats
console.log(red.toRgb()); // { r: 255, g: 0, b: 0 }
console.log(green.toHsl()); // { h: 120, s: 100, l: 50 }
console.log(blue.toHex()); // '#0000ff'
// Advanced color spaces
console.log(red.toOklab()); // { L: 0.627955, a: 0.224863, b: 0.125846 }
console.log(green.toCIExyY());// { x: 0.3, y: 0.6, Y: 0.715158 }
console.log(blue.toHSLuv()); // { h: 265.87, s: 100, l: 32.3 }
// Color manipulation
const lightRed = red.adjustLightness(20);
console.log(lightRed.toHex()); // '#ff6666'
const desaturatedGreen = green.adjustSaturation(-50);
console.log(desaturatedGreen.toHex()); // '#40bf40'
// Generate harmonies
const [complement] = red.complementary();
console.log(complement.toHex()); // '#00ffff'
const [color1, color2] = blue.splitComplementary();
console.log(color1.toHex(), color2.toHex()); // '#ffaa00' '#ff5500'
// Mix colors
const purple = red.mix(blue, 0.5);
console.log(purple.toHex()); // '#800080'
// Get color information
red.getName().then(name => console.log(name)); // 'Red'
red.getInfo().then(info => console.log(info));
// Returns: { name, hex, rgb, hsl, luminance, requestedHex }
// Check brightness and lightness
console.log(red.getBrightness()); // 76.245
console.log(red.isLight()); // false
```
### Color Conversion Functions
For situations where you need quick, one-off color conversions, `color-core` offers standalone conversion functions. These can be useful when you don't need the full functionality of the `Color` class.
```typescript
import { hexToRgb, rgbToHsl, rgbToOklab } from 'color-core';
const rgb = hexToRgb('#00ff00');
console.log(rgb); // { r: 0, g: 255, b: 0 }
const hsl = rgbToHsl(rgb);
console.log(hsl); // { h: 120, s: 100, l: 50 }
const oklab = rgbToOklab(rgb);
console.log(oklab); // { L: 0.866440, a: -0.233888, b: 0.179498 }
```
---
## API Reference
The following section provides a comprehensive overview of color-core's API. Each method and function is documented to help you understand its purpose and usage within your color manipulation workflows.You can find more detailed information in the [official documentation](https://docs.color-core.com).
### Color Class
The `Color` class is the main entry point for color manipulations.
#### Constructor
```typescript
new Color(color: string | RGB | HSL | HSV | CMYK | LAB | LCH | XYZ | YUV | Oklab | Oklch | HSLuv | HPLuv | CIExyY | HSI | HWB | AdobeRGB)
```
Creates a new Color instance from various color formats.
#### Conversion Methods
| Method | Return Type | Description |
|---------------|:-----------:|:-------------------------------------:|
| `toRgb()` | RGB | Converts the color to RGB format |
| `toSrgb()` | SRGB | Converts the color to sRGB format |
| `toHex()` | string | Converts the color to HEX format |
| `toHsl()` | HSL | Converts the color to HSL format |
| `toHsv()` | HSV | Converts the color to HSV format |
| `toHsi()` | HSI | Converts the color to HSI format |
| `toHwb()` | HWB | Converts the color to HWB format |
| `toLch()` | LCH | Converts the color to LCH format |
| `toYuv()` | YUV | Converts the color to YUV format |
| `toCmyk()` | CMYK | Converts the color to CMYK format |
| `toOklab()` | Oklab | Converts the color to Oklab format |
| `toOklch()` | Oklch | Converts the color to Oklch format |
| `toHSLuv()` | HSLuv | Converts the color to HSLuv format |
| `toHPLuv()` | HPLuv | Converts the color to HPLuv format |
| `toCIELuv()` | LUV | Converts the color to CIELuv format |
| `toCIExyY()` | CIExyY | Converts the color to CIExyY format |
| `toAdobeRGB()`| AdobeRGB | Converts the color to Adobe RGB format |
| `toXyz()` | XYZ | Converts the color to XYZ (D65) format |
| `toXyzD50()` | XYZ | Converts the color to XYZ (D50) format |
| `toLab()` | LAB | Converts the color to LAB (D65) format |
| `toLabD50()` | LAB | Converts the color to LAB (D50) format |
#### Harmony Methods
| Method | Parameters | Return Type | Description |
|------------------------------|:--------------:|:----------------------------:|:----------------------------------------------:|
| `complementary()` | None | [Color, Color] | Generates a complementary harmony |
| `analogous()` | angle?: number | [Color, Color, Color] | Generates an analogous harmony |
| `triadic()` | None | [Color, Color, Color] | Generates a triadic harmony |
| `tetradic()` | angle?: number | [Color, Color, Color, Color] | Generates a tetradic harmony |
| `splitComplementary()` | angle?: number | [Color, Color, Color] | Generates a split-complementary harmony |
| `doubleSplitComplementary()` | angle?: number | [Color, Color, Color, Color, Color] | Generates a double split-complementary harmony |
| `square()` | None | [Color, Color, Color, Color] | Generates a square harmony |
| `monochromatic()` | count?: number | Color[] | Generates a monochromatic harmony |
| `shades()` | count?: number | Color[] | Generates shades of the color |
| `tints()` | count?: number | Color[] | Generates tints of the color |
| `tones()` | count?: number | Color[] | Generates tones of the color |
#### Manipulation Methods
| Method | Parameters | Return Type | Description |
|----------------------|:----------------------------:|:-----------:|:-----------------------------------:|
| `adjustLightness()` | amount: number | Color | Adjusts the lightness of the color |
| `adjustSaturation()` | amount: number | Color | Adjusts the saturation of the color |
| `adjustHue()` | amount: number | Color | Adjusts the hue of the color |
| `adjustAlpha()` | amount: number | Color | Adjusts the alpha of the color |
| `invert()` | None | Color | Inverts the color |
| `grayscale()` | None | Color | Converts the color to grayscale |
| `mix()` | color: Color, amount: number | Color | Mixes the color with another color |
#### Utility Methods
| Method | Parameters | Return Type | Description |
|------------------------|:----------------------:|:-----------:|:---------------------------------------------:|
| `toString()` | includeAlpha?: boolean | string | Returns the color as a hex string |
| `equals(other: Color)` | other: Color | boolean | Checks if two colors are equal |
| `getBrightness()` | None | number | Calculates the perceived brightness (0-255) |
| `isLight()` | threshold?: number | boolean | Determines if the color is light or dark |
| `getName()` | None | Promise | Returns the name of the closest matching color |
| `getInfo()` | None | Promise | Returns detailed information about the color |
### Standalone Functions
#### Conversion Functions
| Function | Parameters | Return Type | Description |
|-----------------|:--------------:|:-----------:|:-----------------------:|
| `hexToRgb` | hex: string | RGB | Converts HEX to RGB |
| `rgbToHex` | rgb: RGB | string | Converts RGB to HEX |
| `rgbToHsl` | rgb: RGB | HSL | Converts RGB to HSL |
| `hslToRgb` | hsl: HSL | RGB | Converts HSL to RGB |
| `rgbToHsv` | rgb: RGB | HSV | Converts RGB to HSV |
| `hsvToRgb` | hsv: HSV | RGB | Converts HSV to RGB |
| `rgbToHsi` | rgb: RGB | HSI | Converts RGB to HSI |
| `hsiToRgb` | hsi: HSI | RGB | Converts HSI to RGB |
| `rgbToHwb` | rgb: RGB | HWB | Converts RGB to HWB |
| `hwbToRgb` | hwb: HWB | RGB | Converts HWB to RGB |
| `rgbToCmyk` | rgb: RGB | CMYK | Converts RGB to CMYK |
| `cmykToRgb` | cmyk: CMYK | RGB | Converts CMYK to RGB |
| `rgbToXyz` | rgb: RGB | XYZ | Converts RGB to XYZ (D65) |
| `xyzToRgb` | xyz: XYZ | RGB | Converts XYZ to RGB (D65) |
| `rgbToXyzD50` | rgb: RGB | XYZ | Converts RGB to XYZ (D50) |
| `xyzD50ToRgb` | xyz: XYZ | RGB | Converts XYZ (D50) to RGB |
| `xyzD65ToD50` | xyz: XYZ | XYZ | Converts XYZ from D65 to D50 |
| `xyzD50ToD65` | xyz: XYZ | XYZ | Converts XYZ from D50 to D65 |
| `rgbToLab` | rgb: RGB | LAB | Converts RGB to LAB (D65) |
| `labToRgb` | lab: LAB | RGB | Converts LAB to RGB (D65) |
| `rgbToLabD50` | rgb: RGB | LAB | Converts RGB to LAB (D50) |
| `labD50ToRgb` | lab: LAB | RGB | Converts LAB (D50) to RGB |
| `rgbToLch` | rgb: RGB | LCH | Converts RGB to LCH |
| `lchToRgb` | lch: LCH | RGB | Converts LCH to RGB |
| `rgbToOklab` | rgb: RGB | Oklab | Converts RGB to Oklab |
| `oklabToRgb` | oklab: Oklab | RGB | Converts Oklab to RGB |
| `rgbToOklch` | rgb: RGB | Oklch | Converts RGB to Oklch |
| `oklchToRgb` | oklch: Oklch | RGB | Converts Oklch to RGB |
| `rgbToHPLuv` | rgb: RGB | HPLuv | Converts RGB to HPLuv |
| `hpluvToRgb` | hpluv: HPLuv | RGB | Converts HPLuv to RGB |
| `rgbToHSLuv` | rgb: RGB | HSLuv | Converts RGB to HSLuv |
| `hsluvToRgb` | hsluv: HSLuv | RGB | Converts HSLuv to RGB |
| `rgbToCIExyY` | rgb: RGB | CIExyY | Converts RGB to CIE xyY |
| `ciexyYToRgb` | ciexyY: CIExyY | RGB | Converts CIE xyY to RGB |
| `rgbToCIELuv` | rgb: RGB | CIELuv | Converts RGB to CIE Luv |
| `cieLuvToRgb` | cieLuv: CIELuv | RGB | Converts CIE Luv to RGB |
| `rgbToYuv` | rgb: RGB | YUV | Converts RGB to YUV |
| `yuvToRgb` | yuv: YUV | RGB | Converts YUV to RGB |
| `rgbToSrgb` | rgb: RGB | RGB | Converts RGB to sRGB |
| `srgbToRgb` | rgb: RGB | RGB | Converts sRGB to RGB |
| `rgbToAdobeRGB` | rgb: RGB | RGB | Converts RGB to Adobe RGB |
| `adobeRGBToRGB` | rgb: RGB | RGB | Converts Adobe RGB to RGB |
#### Harmony Functions
| Function | Parameters | Return Type | Description |
|----------------------------|:--------------------:|:----------------------------:|:----------------------------------------------:|
| `complementary` | color: Color | [Color, Color] | Generates a complementary harmony |
| `analogous` | color: Color, angle? | [Color, Color, Color] | Generates an analogous harmony |
| `triadic` | color: Color | [Color, Color, Color] | Generates a triadic harmony |
| `tetradic` | color: Color, angle? | [Color, Color, Color, Color] | Generates a tetradic harmony |
| `splitComplementary` | color: Color, angle? | [Color, Color, Color] | Generates a split-complementary harmony |
| `doubleSplitComplementary` | color: Color, angle? | [Color, Color, Color, Color, Color] | Generates a double split-complementary harmony |
| `square` | color: Color | [Color, Color, Color, Color] | Generates a square harmony |
| `monochromatic` | color: Color, count? | Color[] | Generates a monochromatic harmony |
| `shades` | color: Color, count? | Color[] | Generates shades of the color |
| `tints` | color: Color, count? | Color[] | Generates tints of the color |
| `tones` | color: Color, count? | Color[] | Generates tones of the color |
#### Manipulation Functions
| Function | Parameters | Return Type | Description |
|--------------------|:----------------------------:|:-----------:|:-----------------------------------:|
| `adjustLightness` | color: Color, amount: number | Color | Adjusts the lightness of the color |
| `adjustSaturation` | color: Color, amount: number | Color | Adjusts the saturation of the color |
| `adjustHue` | color: Color, amount: number | Color | Adjusts the hue of the color |
| `adjustAlpha` | color: Color, amount: number | Color | Adjusts the alpha of the color |
| `invert` | color: Color | Color | Inverts the color |
| `grayscale` | color: Color | Color | Converts the color to grayscale |
| `mix` | color1: Color, color2: Color, amount: number | Color | Mixes two colors |
### Types
```typescript
type RGB = { r: number; g: number; b: number; a?: number };
type SRGB = { r: number; g: number; b: number };
type HSL = { h: number; s: number; l: number; a?: number };
type HSV = { h: number; s: number; v: number; a?: number };
type CMYK = { c: number; m: number; y: number; k: number };
type LAB = { l: number; a: number; b: number };
type LCH = { l: number; c: number; h: number };
type XYZ = { x: number; y: number; z: number };
type YUV = { y: number; u: number; v: number };
type Oklab = { L: number; a: number; b: number };
type Oklch = { L: number; C: number; h: number };
type HPLuv = { h: number; p: number; l: number };
type HSLuv = { h: number; s: number; l: number };
type CIExyY = { x: number; y: number; Y: number };
type CIELuv = { L: number; u: number; v: number };
type HSI = { h: number; s: number; i: number };
type HWB = { h: number; w: number; b: number };
type AdobeRGB = { r: number; g: number; b: number };
```
---
## Examples
These practical examples demonstrate how to use various features of color-core to solve common color-related tasks. Feel free to adapt these examples to your specific needs.
### Color Manipulation
```typescript
import { Color } from 'color-core';
const color = new Color('#ff0000');
// Lighten the color
const lighterColor = color.adjustLightness(20);
console.log(lighterColor.toHex()); // '#ff6666'
// Desaturate the color
const desaturatedColor = color.adjustSaturation(-50);
console.log(desaturatedColor.toHex()); // '#bf4040'
// Change the hue
const hueShiftedColor = color.adjustHue(120);
console.log(hueShiftedColor.toHex()); // '#00ff00'
// Invert the color
const invertedColor = color.invert();
console.log(invertedColor.toHex()); // '#00ffff'
// Convert to grayscale
const grayscaleColor = color.grayscale();
console.log(grayscaleColor.toHex()); // '#4d4d4d'
// Mix with another color
const mixedColor = color.mix(new Color('#0000ff'), 0.5);
console.log(mixedColor.toHex()); // '#800080'
// Get color name
color.getName().then(name => console.log(name)); // 'Red'
// Get color information
color.getInfo().then(info => console.log(info));
// Returns: { name, hex, rgb, hsl, luminance, requestedHex }
// Check brightness and if the color is light
console.log(color.getBrightness()); // 76.245
console.log(color.isLight()); // false
```
---
## Advanced Usage
The advanced usage section covers more complex scenarios, including working with less common color spaces and generating sophisticated color harmonies. These examples showcase the depth of `color-core`'s capabilities.
### Working with Different Color Spaces
```typescript
import { Color } from 'color-core';
// Create a color in Oklab space
const oklabColor = new Color({ L: 0.627955, a: 0.224863, b: 0.125846 });
console.log(oklabColor.toHex()); // '#ff0000'
// Convert to CIE xyY
const xyYColor = oklabColor.toCIExyY();
console.log(xyYColor); // { x: 0.64, y: 0.33, Y: 0.2126 }
// Create a color in HSLuv space
const hsluvColor = new Color({ h: 12.177, s: 100, l: 53.237 });
console.log(hsluvColor.toRgb()); // { r: 255, g: 0, b: 0 }
// Convert to Adobe RGB
const adobeRGBColor = hsluvColor.toAdobeRGB();
console.log(adobeRGBColor); // { r: 255, g: 0, b: 0 }
```
### Color Harmonies
```typescript
import { Color } from 'color-core';
const baseColor = new Color('#ff0000');
// Generate complementary color
const [complement] = baseColor.complementary();
console.log(complement.toHex()); // '#00ffff'
// Generate analogous colors
const [analog1, analog2] = baseColor.analogous();
console.log(analog1.toHex(), analog2.toHex()); // '#ff8000' '#ff0080'
// Generate triadic colors
const [triad1, triad2] = baseColor.triadic();
console.log(triad1.toHex(), triad2.toHex()); // '#00ff00' '#0000ff'
// Generate tetradic colors
const [tetra1, tetra2, tetra3] = baseColor.tetradic();
console.log(tetra1.toHex(), tetra2.toHex(), tetra3.toHex()); // '#80ff00' '#00ffff' '#8000ff'
// Generate split-complementary colors
const [split1, split2] = baseColor.splitComplementary();
console.log(split1.toHex(), split2.toHex()); // '#00ff80' '#0080ff'
// Generate shades
const shades = baseColor.shades(5);
shades.forEach(shade => console.log(shade.toHex()));
// '#ff0000' '#cc0000' '#990000' '#660000' '#330000'
// Generate tints
const tints = baseColor.tints(5);
tints.forEach(tint => console.log(tint.toHex()));
// '#ff0000' '#ff3333' '#ff6666' '#ff9999' '#ffcccc'
```
As you become more familiar with color-core, you'll likely discover additional ways to leverage its functionality in your projects. The library's extensive color space support and manipulation tools provide a robust foundation for a wide range of color-related tasks.
---
## Versioning
This project follows [Semantic Versioning](https://semver.org/). For the versions available, see the [tags on this repository](https://github.com/iamlite/color-core/tags).
---
## Contributing
Contributions are welcome and greatly appreciated!
---
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
## Support
If you're having any problem, please [raise an issue](https://github.com/iamlite/color-core/issues/new) on GitHub and I will be happy to help.
---
## Acknowledgements
[HSLuv & HPLuv Conversions](https://www.hsluv.org/) by [Alexei Boronine](https://github.com/boronine)
[Oklab & Oklch Math Used](https://bottosson.github.io/posts/oklab/) by [Björn Ottosson](https://bottosson.github.io/posts/oklab/)
[Color Name API](https://github.com/meodai/color-name-api) by [meodai](https://github.com/meodai)
---
Code Coverage
Built with ❤️ by iamlite
[Back to top :arrow_up:](#top)
