Formatting, Cache & CLI

Formatting

Function	Description
toHslString(h, s, l, alpha?)	Formats as hsl(...) or hsla(...)
toHwbString(H, W, B, alpha?)	Formats as hwb(...) with optional alpha
toOklchString(color, alpha?)	Converts any color to oklch(L C H) CSS string
toColorP3String(color, alpha?)	Converts any color to color(display-p3 r g b) CSS string

import { toOklchString, toColorP3String, toHwbString } from 'color-value-tools'

toOklchString('#3498db') // 'oklch(0.6 0.1175 234.77)'
toColorP3String('#3498db') // 'color(display-p3 0.2493 0.5875 0.8479)'
toHwbString(204, 20, 14) // 'hwb(204 20% 14%)'
toHwbString(204, 20, 14, 0.8) // 'hwb(204 20% 14% / 0.8)'

Cache Management

Useful in rendering loops, color pickers, or any context with repeated normalizeColor calls on the same values.

Function	Description
normalizeColorCached(input)	Cached version of normalizeColor for repeated string calls
clearColorCache()	Clears the normalization cache and resets hit counter
getCacheStats()	Returns { size: number, hits: number }
enableCache()	Re-enables the cache (on by default)
disableCache()	Disables caching (useful in tests)

import { normalizeColorCached, getCacheStats, clearColorCache } from 'color-value-tools'

// First call — parsed and cached
normalizeColorCached('#3498db')

// Second call — instant cache hit
normalizeColorCached('#3498db')

getCacheStats() // { size: 1, hits: 1 }
clearColorCache() // { size: 0, hits: 0 } reset

Generator Functions

Useful for large palettes and frame-by-frame animations without allocating full arrays upfront.

Function	Description
generateGradientColors*(start, end, steps, opts?)	Yields steps colors from start to end. Same mode / format options as mixColors
generateTints*(color, steps, opts?)	Yields tints toward white in Oklab
generateShades*(color, steps, opts?)	Yields shades toward black in Oklab

import { generateGradientColors, generateTints } from 'color-value-tools'

// Process one color at a time — no intermediate array
for (const color of generateGradientColors('#ff0000', '#0000ff', 1000, { mode: 'oklch' })) {
  renderPixel(color)
}

// Collect lazily
const first5 = [...generateTints('#e74c3c', 100)].slice(0, 5)

CLI

The cvt CLI is included in the package. Install globally or use via npx:

npm install -g color-value-tools

# Full info (default command)
cvt "#3498db"

# All format conversions — hex, rgb, hsl, hsv, hwb, lab, lch, oklab, oklch, cmyk
cvt "#3498db" convert

# Contrast ratio and WCAG level
cvt "#3498db" contrast "#ffffff"

# Generate 7 shades
cvt "#3498db" shades 7

# All harmonies — complement, triadic, analogous, split-comp, tetradic
cvt "#3498db" harmonies

# Nearest CSS named color
cvt "cornflowerblue" nearest

Accepts any valid color format: hex, rgb(), hsl(), oklch(), named colors.

cvt "#3498db"
────────────────────────────────────────
  Type:              hex
  Hex:               #3498db
  RGB:               rgb(52, 152, 219)
  HSL:               hsl(204, 70%, 53%)
  HSV:               hsv(204, 76%, 86%)
  Nearest named:     cornflowerblue
  Best text on it:   #ffffff