colore-js

A High-Performance JavaScript Library for Color Management.

Features

🔄 Color Manipulations

       Easily manipulate colors with functions to lighten, darken, saturate, desaturate, invert, and blend colors.

🌈 Color Harmony

       Generate harmonious colors using monochromatic, complementary, triadic, tetradic, and more color schemes.

🔍 Color Validation

       Validate color formats to ensure correct color values before applying transformations.

🎨 Color Conversions

       Convert colors between all popular color formats such as RGB, HEX, HSL, LAB, LCH, and more.

📊 Accessibility

       Calculate contrast ratios, luminance, and other color metrics for accessibility.

🛠 Color Parsing

       Parse individual components of colors, decompose and recompose colors.

🚀 High Performance

       Optimized for performance with a small footprint.

✅ No Dependencies

       Designed to be lean and efficient without any external dependencies.

📦 Small Size

       ~10 KB gzipped.

Installation

To install the Colore library, use the follow command:

npm install colore-js

Alternatively, if you use Yarn:

yarn add colore-js

Getting Started

import { hexToRgb, lightenColor, saturateColor, setCssVariableValue } from 'colore-js';

// Lightening a color
const lightenedRgb = lightenColor('rgb(255, 0, 0)', 20);
console.log(lightenedRgb); // Output: 'rgb(255, 51, 51)'

// Saturating a color
const saturatedRgb = saturateColor('rgb(255, 0, 0)', 50);
console.log(saturatedRgb); // Output: 'rgb(255, 51, 51)'

// Converting HEX to RGB color format
const rgbString = hexToRgb('#ff5733');
console.log(rgbString); // Output: 'rgb(255, 87, 51)'

// Setting a new CSS Variable Value
const element = document.querySelector('.my-element');
setCssVariableValue(element, '--my-variable', 'blue');

API Reference

Analysis

getContrastRatio

import { getContrastRatio } from 'colore-js';

const result = getContrastRatio('#ffffff', '#000000');
console.log(result); // Output: { ratio: 21, ratioString: "21.00:1", isAccessible: true, level: 'AAA' }

getLuminance

import { getLuminance } from 'colore-js';

const luminance = getLuminance('#ffffff');
console.log(luminance); // Output: 1

Conversions

cmykToRgb

import { cmykToRgb } from 'colore-js';

const rgbString = cmykToRgb(0, 100, 100, 0);
console.log(rgbString); // Output: "rgb(255, 0, 0)"

hexAlphaToHsla

import { hexAlphaToHsla } from 'colore-js';

const hslaColor = hexAlphaToHsla('#ff5733cc');
console.log(hslaColor); // Output: "hsla(14, 100%, 60%, 0.8)"

hexAlphaToHsva

import { hexAlphaToHsva } from 'colore-js';

const hsvaString = hexAlphaToHsva('#ff5733cc');
console.log(hsvaString); // Output: "hsva(11, 0.8, 1, 0.8)"

hexAlphaToRgba

import { hexAlphaToRgba } from 'colore-js';

const rgbaString = hexAlphaToRgba('#FF5733CC');
console.log(rgbaString); // Output: "rgba(255, 87, 51, 0.8)"

hexToHexAlpha

import { hexToHexAlpha } from 'colore-js';

const hexWithAlpha = hexToHexAlpha('#ff0000', 0.5);
console.log(hexWithAlpha); // Output: '#ff000080'

See all Conversions.

CSS Variables

getCssVariableValue

import { getCssVariableValue } from 'colore-js';

const element = document.querySelector('.my-element');
const variableValue = getCssVariableValue(element, '--my-variable');
console.log(variableValue); // Output: 'your-css-variable-value'

setCssVariableValue

import { setCssVariableValue } from 'colore-js';

const element = document.querySelector('.my-element');
setCssVariableValue(element, '--my-variable', 'blue');

Generators

generateInterpolatedColors

import { generateInterpolatedColors } from 'colore-js';

const color1 = '#ff0000';
const color2 = '#00ff00';
const steps = 5;

const interpolatedColorsStrings = generateInterpolatedColors(color1, color2, steps);
console.log(interpolatedColorsStrings);

generateRandomColor

import { generateRandomColor, ColorFormats } from 'colore-js';

const randomHexColor = generateRandomColor(ColorFormats.HEX);
console.log(randomHexColor); // Output: "#a1b2c3" (example)

Harmony

analogousColors

import { analogousColors } from 'colore-js';

const analogous = analogousColors('#ff0000');
console.log(analogous); // Output: ['#ff8000', '#ff0080']

complementaryColor

import { complementaryColor } from 'colore-js';

const complementary = complementaryColor('#ff0000');
console.log(complementary); // Output: '#00ffff'

monochromaticColors

import { monochromaticColors } from 'colore-js';

const monochromatic = monochromaticColors('#ff0000');
console.log(monochromatic); // Output: ['#4c0000', '#b20000', '#ff0000', '#ff4c4c', '#ff9999']

tetradicColors

import { tetradicColors } from 'colore-js';

const tetradic = tetradicColors('#ff0000');
console.log(tetradic); // Output: ['#00ff00', '#0000ff', '#ff00ff']

triadicColors

import { triadicColors } from 'colore-js';

const triadic = triadicColors('#ff0000');
console.log(triadic); // Output: ['#00ff00', '#0000ff']

Manipulations

blendColors

import { blendColors, BlendingModes } from 'colore-js';

const blended = blendColors('#ff0000', '#0000ff', BlendingModes.MULTIPLY);
console.log(blended); // Output: '#000000'

darkenColor

import { darkenColor } from 'colore-js';

const darkened = darkenColor('#ff0000', 20);
console.log(darkened); // Output: '#cc0000'

desaturateColor

import { desaturateColor } from 'colore-js';

const desaturated = desaturateColor('#ff0000', 50);
console.log(desaturated); // Output: '#804040'

invertColor

import { invertColor } from 'colore-js';

const invertedColor = invertColor("#ff5733");
console.log(invertedColor); // Output: "#00a8cc"

lightenColor

import { lightenColor } from 'colore-js';

const lightened = lightenColor('#ff0000', 20);
console.log(lightened); // Output: '#ff6666'

See all Manipulations.

Parser

decomposeColor

import { decomposeColor } from 'colore-js';

const decomposedHex = decomposeColor('#ff0000');
console.log(decomposedHex); // Output: { r: 255, g: 0, b: 0 }

detectColorFormat

import { detectColorFormat } from 'colore-js';

const formatHex = detectColorFormat('#ff0000');
console.log(formatHex); // Output: 'HEX'

parseColorToRgba

import { parseColorToRgba } from 'colore-js';

const rgbaHex = parseColorToRgba('#ff0000');
console.log(rgbaHex); // Output: { r: 255, g: 0, b: 0 }

parseHex

import { parseHex } from 'colore-js';

const rgb = parseHex('#ff0000');
console.log(rgb); // Output: { r: 255, g: 0, b: 0 }

parseHexAlpha

import { parseHexAlpha } from 'colore-js';

const rgba = parseHexAlpha('#ff000080');
console.log(rgba); // Output: { r: 255, g: 0, b: 0, a: 0.502 }

See all Parsers.

Validations

isValidHex

import { isValidHex } from 'colore-js';

console.log(isValidHex('#ff0000')); // Output: true

isValidHexAlpha

import { isValidHexAlpha } from 'colore-js';

console.log(isValidHexAlpha('#ff0000ff')); // Output: true

isValidHsl

import { isValidHsl } from 'colore-js';

console.log(isValidHsl('hsl(120, 100%, 50%)')); // Output: true

isValidHsla

import { isValidHsla } from 'colore-js';

console.log(isValidHsla('hsla(120, 100%, 50%, 0.5)')); // Output: true

isValidLab

import { isValidLab } from 'colore-js';

console.log(isValidLab('lab(50% 0% 0%)')); // Output: true

See all Validations.

See Documentation for complete API reference.

Supported Color Formats

• Hex strings
• Hex Alpha strings
• HSL strings and objects
• HSV strings and objects
• LAB strings and objects
• LCH strings and objects
• Named Colors strings and objects
• RGB strings and objects
• RGBA strings and objects
• XYZ strings and objects

Contributing

We welcome contributions from the community to make Colore better. If you find any issues or have suggestions for improvements, feel free to contribute or open an issue on our GitHub Repository.

License

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

Something Missing?

If you find any issues or have suggestions for improvements, feel free to contribute or open an issue on our GitHub Repository. We welcome contributions from the community to make Colore better.

Changelog

1.4.2 (2024-08-02)

Features

• add enhanceColor function for color manipulation (aedf1cb)

Chores

• add .DS_Store to .npmignore (8caef0a)

Documentation

• expand README with new API methods and examples (8cf7df8)
• update README for better clarity and organization (fc330eb)
• update README section headings to improve structure (81b9e3a)
• update README with detailed feature sections (4f02b46)