Home

Awesome

<div align="center"> <a name="top"></a> <img alt="logo" src="./assets/color-core-light.png"/> </div> <div align="center"> <img alt="NPM Downloads" src="https://img.shields.io/npm/d18m/color-core?style=for-the-badge&logo=npm&color=purple"/> <img alt="NPM Version" src="https://img.shields.io/npm/v/color-core?style=for-the-badge&logo=npm"/> <img alt="NPM License" src="https://img.shields.io/npm/l/color-core?style=for-the-badge&color=red"/> <img src="https://img.shields.io/github/last-commit/iamlite/color-core?display_timestamp=author&style=for-the-badge&logo=github" alt="last-commit" /> <img alt="Libraries.io dependency status for latest release" src="https://img.shields.io/librariesio/release/npm/color-core?style=for-the-badge&logo=dependabot"/> <img alt="Codecov" src="https://img.shields.io/codecov/c/github/iamlite/color-core?style=for-the-badge&logo=codecov"/> <img alt="npm bundle size" src="https://img.shields.io/bundlephobia/min/color-core?style=for-the-badge"/> <a href="https://iamlite.github.io/color-core/"> <img alt="Static Badge" src="https://img.shields.io/badge/Docs-blue?style=for-the-badge&logo=github&logoColor=white&labelColor=gray"/> </a> </div>
<div align="center"> <a href="https://color-core.com"> <img alt="Static Badge" src="https://img.shields.io/badge/Demo_Website-blue?style=for-the-badge&logo=vercel&logoColor=white&labelColor=gray"/> </a> <a href="https://www.npmjs.com/package/color-core"> <img alt="Static Badge" src="https://img.shields.io/badge/NPM-URL%20-%20link?style=for-the-badge&logo=npm"/> </a> <a href="https://discord.gg/uYBuFXUmcU"> <img src="https://img.shields.io/discord/640575167772491786?style=for-the-badge&logo=discord&label=Discord&color=gold" alt="Discord" /> </a> </div>
<div align="center"> `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. </div>

Features

<div align="center">

Installation

npm i color-core
<br>

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

<br>

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 ‡️

<br> <div align="left">
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
</div> <br>

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.

<br> <div align="left">
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 }
</div> <br>

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.

<br>

Color Class

The Color class is the main entry point for color manipulations.

<br>

Constructor

<div align="left">
new Color(color: string | RGB | HSL | HSV | CMYK | LAB | LCH | XYZ | YUV | Oklab | Oklch | HSLuv | HPLuv | CIExyY | HSI | HWB | AdobeRGB)
</div> Creates a new Color instance from various color formats. <br>

Conversion Methods

<br>
MethodReturn TypeDescription
toRgb()RGBConverts the color to RGB format
toSrgb()SRGBConverts the color to sRGB format
toHex()stringConverts the color to HEX format
toHsl()HSLConverts the color to HSL format
toHsv()HSVConverts the color to HSV format
toHsi()HSIConverts the color to HSI format
toHwb()HWBConverts the color to HWB format
toLch()LCHConverts the color to LCH format
toYuv()YUVConverts the color to YUV format
toCmyk()CMYKConverts the color to CMYK format
toOklab()OklabConverts the color to Oklab format
toOklch()OklchConverts the color to Oklch format
toHSLuv()HSLuvConverts the color to HSLuv format
toHPLuv()HPLuvConverts the color to HPLuv format
toCIELuv()LUVConverts the color to CIELuv format
toCIExyY()CIExyYConverts the color to CIExyY format
toAdobeRGB()AdobeRGBConverts the color to Adobe RGB format
toXyz()XYZConverts the color to XYZ (D65) format
toXyzD50()XYZConverts the color to XYZ (D50) format
toLab()LABConverts the color to LAB (D65) format
toLabD50()LABConverts the color to LAB (D50) format
<br>

Harmony Methods

<br>
MethodParametersReturn TypeDescription
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?: numberColor[]Generates a monochromatic harmony
shades()count?: numberColor[]Generates shades of the color
tints()count?: numberColor[]Generates tints of the color
tones()count?: numberColor[]Generates tones of the color
<br>

Manipulation Methods

<br>
MethodParametersReturn TypeDescription
adjustLightness()amount: numberColorAdjusts the lightness of the color
adjustSaturation()amount: numberColorAdjusts the saturation of the color
adjustHue()amount: numberColorAdjusts the hue of the color
adjustAlpha()amount: numberColorAdjusts the alpha of the color
invert()NoneColorInverts the color
grayscale()NoneColorConverts the color to grayscale
mix()color: Color, amount: numberColorMixes the color with another color
<br>

Utility Methods

<br>
MethodParametersReturn TypeDescription
toString()includeAlpha?: booleanstringReturns the color as a hex string
equals(other: Color)other: ColorbooleanChecks if two colors are equal
getBrightness()NonenumberCalculates the perceived brightness (0-255)
isLight()threshold?: numberbooleanDetermines if the color is light or dark
getName()NonePromise<string>Returns the name of the closest matching color
getInfo()NonePromise<ColorInfo>Returns detailed information about the color
<br>

Standalone Functions

<br>

Conversion Functions

<br>
FunctionParametersReturn TypeDescription
hexToRgbhex: stringRGBConverts HEX to RGB
rgbToHexrgb: RGBstringConverts RGB to HEX
rgbToHslrgb: RGBHSLConverts RGB to HSL
hslToRgbhsl: HSLRGBConverts HSL to RGB
rgbToHsvrgb: RGBHSVConverts RGB to HSV
hsvToRgbhsv: HSVRGBConverts HSV to RGB
rgbToHsirgb: RGBHSIConverts RGB to HSI
hsiToRgbhsi: HSIRGBConverts HSI to RGB
rgbToHwbrgb: RGBHWBConverts RGB to HWB
hwbToRgbhwb: HWBRGBConverts HWB to RGB
rgbToCmykrgb: RGBCMYKConverts RGB to CMYK
cmykToRgbcmyk: CMYKRGBConverts CMYK to RGB
rgbToXyzrgb: RGBXYZConverts RGB to XYZ (D65)
xyzToRgbxyz: XYZRGBConverts XYZ to RGB (D65)
rgbToXyzD50rgb: RGBXYZConverts RGB to XYZ (D50)
xyzD50ToRgbxyz: XYZRGBConverts XYZ (D50) to RGB
xyzD65ToD50xyz: XYZXYZConverts XYZ from D65 to D50
xyzD50ToD65xyz: XYZXYZConverts XYZ from D50 to D65
rgbToLabrgb: RGBLABConverts RGB to LAB (D65)
labToRgblab: LABRGBConverts LAB to RGB (D65)
rgbToLabD50rgb: RGBLABConverts RGB to LAB (D50)
labD50ToRgblab: LABRGBConverts LAB (D50) to RGB
rgbToLchrgb: RGBLCHConverts RGB to LCH
lchToRgblch: LCHRGBConverts LCH to RGB
rgbToOklabrgb: RGBOklabConverts RGB to Oklab
oklabToRgboklab: OklabRGBConverts Oklab to RGB
rgbToOklchrgb: RGBOklchConverts RGB to Oklch
oklchToRgboklch: OklchRGBConverts Oklch to RGB
rgbToHPLuvrgb: RGBHPLuvConverts RGB to HPLuv
hpluvToRgbhpluv: HPLuvRGBConverts HPLuv to RGB
rgbToHSLuvrgb: RGBHSLuvConverts RGB to HSLuv
hsluvToRgbhsluv: HSLuvRGBConverts HSLuv to RGB
rgbToCIExyYrgb: RGBCIExyYConverts RGB to CIE xyY
ciexyYToRgbciexyY: CIExyYRGBConverts CIE xyY to RGB
rgbToCIELuvrgb: RGBCIELuvConverts RGB to CIE Luv
cieLuvToRgbcieLuv: CIELuvRGBConverts CIE Luv to RGB
rgbToYuvrgb: RGBYUVConverts RGB to YUV
yuvToRgbyuv: YUVRGBConverts YUV to RGB
rgbToSrgbrgb: RGBRGBConverts RGB to sRGB
srgbToRgbrgb: RGBRGBConverts sRGB to RGB
rgbToAdobeRGBrgb: RGBRGBConverts RGB to Adobe RGB
adobeRGBToRGBrgb: RGBRGBConverts Adobe RGB to RGB
<br>

Harmony Functions

<br>
FunctionParametersReturn TypeDescription
complementarycolor: Color[Color, Color]Generates a complementary harmony
analogouscolor: Color, angle?[Color, Color, Color]Generates an analogous harmony
triadiccolor: Color[Color, Color, Color]Generates a triadic harmony
tetradiccolor: Color, angle?[Color, Color, Color, Color]Generates a tetradic harmony
splitComplementarycolor: Color, angle?[Color, Color, Color]Generates a split-complementary harmony
doubleSplitComplementarycolor: Color, angle?[Color, Color, Color, Color, Color]Generates a double split-complementary harmony
squarecolor: Color[Color, Color, Color, Color]Generates a square harmony
monochromaticcolor: Color, count?Color[]Generates a monochromatic harmony
shadescolor: Color, count?Color[]Generates shades of the color
tintscolor: Color, count?Color[]Generates tints of the color
tonescolor: Color, count?Color[]Generates tones of the color
<br>

Manipulation Functions

<br>
FunctionParametersReturn TypeDescription
adjustLightnesscolor: Color, amount: numberColorAdjusts the lightness of the color
adjustSaturationcolor: Color, amount: numberColorAdjusts the saturation of the color
adjustHuecolor: Color, amount: numberColorAdjusts the hue of the color
adjustAlphacolor: Color, amount: numberColorAdjusts the alpha of the color
invertcolor: ColorColorInverts the color
grayscalecolor: ColorColorConverts the color to grayscale
mixcolor1: Color, color2: Color, amount: numberColorMixes two colors
<br>

Types

<br> <div align="left">
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 };
</div> <br>

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

Color Manipulation

<br> <div align="left">
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
</div> ---

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

Working with Different Color Spaces

<br> <div align="left">
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 }
</div> <br>

Color Harmonies

<br> <div align="left">
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'
</div> <br>

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

<br>

This project follows Semantic Versioning. For the versions available, see the tags on this repository.

<br>

Contributing

<br>

Contributions are welcome and greatly appreciated!

<br>

License

<br>

This project is licensed under the MIT License - see the LICENSE file for details.

<br>

Support

<br>

If you're having any problem, please raise an issue on GitHub and I will be happy to help.

<br>

Acknowledgements

<br>

HSLuv & HPLuv Conversions by Alexei Boronine

Oklab & Oklch Math Used by BjΓΆrn Ottosson

Color Name API by meodai

<br>
<h1>Code Coverage</h1> <br>

<img alt="codecov" src="https://codecov.io/gh/iamlite/color-core/graphs/sunburst.svg?token=MBMKJU55OY"></img>

<br>

Built with ❀️ by <a href="https://github.com/iamlite">iamlite</a>

<br>

Back to top :arrow_up:

</div>