[go: up one dir, main page]

color-core
TypeScript icon, indicating that this package has built-in type declarations

1.4.0 • Public • Published
logo


`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)
  • 🎛 Customizable, unopinionated ColorPicker component
  • 💪 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

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


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.


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 }

ColorPicker Component

color-core includes a customizable ColorPicker component for typescript applications. This component provides a user-friendly interface for color selection while allowing extensive customization to fit your application's needs.


import { ColorPicker } from 'color-core';

function MyComponent() {
  return (
    <ColorPicker
      initialColor={{ r: 255, g: 0, b: 0 }}
      onChange={(color) => console.log('Selected color:', color)}
      width={300}
      height={200}
    />
  );
}


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.


Color Class

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


Constructor

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


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


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


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


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. For the versions available, see the tags on this repository.



Contributing


Contributions are welcome and greatly appreciated!



License


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



Support


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



Acknowledgements


HSLuv & HPLuv Conversions by Alexei Boronine

Oklab & Oklch Math Used by Björn Ottosson

Color Name API by meodai



Code Coverage


codecov


Built with ❤️ by iamlite


Back to top ⬆️

Package Sidebar

Install

npm i color-core

Weekly Downloads

47

Version

1.4.0

License

MIT

Unpacked Size

234 kB

Total Files

122

Last publish

Collaborators

  • iamlite