color-utils

Color conversion, manipulation, and accessibility utilities for hex, RGB, and HSL colors.

Install

npm install @theguyswithaball/color-utils

Usage

const color = require('@theguyswithaball/color-utils');

color.hexToRgb('#3498db');        // { r: 52, g: 152, b: 219 }
color.lighten('#3498db', 15);     // '#66b2e8'
color.getContrastRatio('#000', '#fff'); // 21
color.isAccessible('#000', '#fff');     // true
color.getReadableColor('#3498db');      // '#000000' or '#ffffff'

API

Validation

isValidHex(hex) → boolean

Returns true if hex is a valid #rgb or #rrggbb color string.

isValidRgb(r, g, b) → boolean

Returns true if all three values are integers in [0, 255].

isValidHsl(h, s, l) → boolean

Returns true if h is in [0, 360) and s, l are in [0, 100].

Conversions

hexToRgb(hex) → {r, g, b}

rgbToHex(r, g, b) → string

rgbToHsl(r, g, b) → {h, s, l}

hslToRgb(h, s, l) → {r, g, b}

hexToHsl(hex) → {h, s, l}

hslToHex(h, s, l) → string

Manipulation

All manipulation functions accept and return hex color strings.

lighten(hex, amount) → string

Increases lightness by amount (0–100).

darken(hex, amount) → string

Decreases lightness by amount (0–100).

saturate(hex, amount) → string

Increases saturation by amount (0–100).

desaturate(hex, amount) → string

Decreases saturation by amount (0–100).

mix(hex1, hex2, weight = 50) → string

Mixes two colors. weight (0–100) controls how much of hex1 is used.

invert(hex) → string

Returns the negative/inverted color.

grayscale(hex) → string

Converts to grayscale using luminance weights.

rotate(hex, degrees) → string

Rotates the hue by the given number of degrees.

complement(hex) → string

Returns the complementary color (hue rotated 180°).

triadic(hex) → [string, string, string]

Returns the base color and two triadic colors (120° apart).

tetradic(hex) → [string, string, string, string]

Returns four tetradic colors (90° apart).

analogous(hex, angle = 30) → [string, string, string]

Returns the base color and its two analogous neighbors at ±angle degrees.

Accessibility (WCAG 2.1)

getLuminance(hex) → number

Returns the relative luminance, from 0 (black) to 1 (white).

getContrastRatio(hex1, hex2) → number

Returns the contrast ratio between two colors (1–21).

isAccessible(foreground, background, level = 'AA', size = 'normal') → boolean

Checks if the color pair meets the WCAG contrast threshold.

| Level | Size | Min ratio | |-------|--------|-----------| | AA | normal | 4.5 | | AA | large | 3.0 | | AAA | normal | 7.0 | | AAA | large | 4.5 |

getReadableColor(background) → '#000000' | '#ffffff'

Returns black or white, whichever is more readable on the given background.

String output

toRgbString(r, g, b) → string

Returns 'rgb(r, g, b)'.

toHslString(h, s, l) → string

Returns 'hsl(h, s%, l%)'.

alpha(hex, opacity) → string

Returns 'rgba(r, g, b, opacity)'. Opacity must be between 0 and 1.

Misc

randomColor() → string

Returns a random hex color string.

parseColor(color) → {format, hex, rgb, hsl}

Parses a hex, rgb(...), or hsl(...) string and returns a normalized object with all three representations.

color.parseColor('rgb(255, 0, 0)');
// {
//   format: 'rgb',
//   hex: '#ff0000',
//   rgb: { r: 255, g: 0, b: 0 },
//   hsl: { h: 0, s: 100, l: 50 }
// }

License

MIT