@carrot/colors

ts

Zero-dependency TypeScript color library with five color spaces (RGB, HSL, HSV, Oklab, Oklch), perceptual transforms, CSS parsing/rendering, and blend modes.

Usage

import { parseColor, renderHex, lighten, lerpPerceptual, colorFromString } from '@carrot/colors';

const color = parseColor('#ff6b35');
const lighter = lighten(color!, 0.1);
const hex = renderHex(lighter);

const gradient = Array.from({ length: 5 }, (_, i) =>
  renderHex(lerpPerceptual(colorA, colorB, i / 4))
);

const { backgroundHex, text } = colorFromString('user@example.com');

See the guide for comprehensive examples.

Contents

• 5 color types - ColorRgb / ColorHsl / ColorHsv / ColorOklab / ColorOklch (immutable + mutable variants)
• 20 conversion functions - full cross-space conversion grid, all routing through RGB
• Parsing - parseColor() handles hex, rgb(), hsl(), hsv(), oklab(), oklch(), comma-separated bytes
• Rendering - 10 format renderers + renderColor() dispatch via ColorRenderFormat
• Blending - 10 blend modes (Normal, Multiply, Screen, Overlay, etc.)
• Transforms - lighten, darken, saturate, desaturate, rotateHue, invert, grayscale (perceptual via Oklch)
• Interpolation - lerpRgb, lerpOklch, lerpPerceptual (shortest hue path)
• Accessibility - luminance(), contrastRatio(), contrastTextFor()
• Utilities - colorFromString() for deterministic string-to-color mapping

See below for the full API reference.

Build

pnpm build    # runs tsc

Zero runtime dependencies. TypeScript ^5.9.3. Node >=20 <23. ESM output with declarations.

See the guide for architecture details.

---

@carrot/colors - Contents

Import: import { ... } from '@carrot/colors';

Color Types

Each color space has an immutable class, a mutable class, and a structural interface.

Space	Immutable	Mutable	Interface	Channels
RGB	ColorRgb	MutableColorRgb	ColorRgbLike	r g b a (0-1)
HSL	ColorHsl	MutableColorHsl	ColorHslLike	h (0-360) s l a (0-1)
HSV	ColorHsv	MutableColorHsv	ColorHsvLike	h (0-360) s v a (0-1)
Oklab	ColorOklab	MutableColorOklab	ColorOklabLike	L (0-1) a b (~-0.4..0.4) alpha
Oklch	ColorOklch	MutableColorOklch	ColorOklchLike	L (0-1) C (0-~0.4) h (0-360) alpha

Immutable Class Members

All immutable classes share: constructor · static from(like) · with*(value) (per-channel copy) · clamped() · equals(other, epsilon?) · toMutable() · toArray() (RGB only)

ColorRgb presets: ColorRgb.white · ColorRgb.black · ColorRgb.transparent · ColorRgb.red · ColorRgb.green · ColorRgb.blue

Mutable Class Members

All mutable classes share: constructor · static from(like) · set(...) · copyFrom(other) · toImmutable()

MutableColorRgb also has: clamp() · equals(other, epsilon?)

Conversions

rgbToHsl · rgbToHsv · rgbToOklab · rgbToOklch · hslToRgb · hslToHsv · hslToOklab · hslToOklch · hsvToRgb · hsvToHsl · hsvToOklab · hsvToOklch · oklabToRgb · oklabToHsl · oklabToHsv · oklabToOklch · oklchToRgb · oklchToHsl · oklchToHsv · oklchToOklab

All accept a *Like interface, return an immutable instance. All conversions route through RGB.

Low-Level Conversion Helpers

clamp01(v) · wrap360(h) · srgbToLinear(c) · linearToSrgb(c) · floatToByte(f) · byteToFloat(b)

Parsing

Function	Returns	Description
parseColor(input)	ColorRgb | undefined	Parse any supported format
parseColorStrict(input)	ColorRgb	Parse or throw
parseHex(s)	ColorRgb | undefined	Parse #rgb #rgba #rrggbb #rrggbbaa

Supported parseColor formats: #hex · rgb() · rgba() · hsl() · hsla() · hsv() · hsva() · oklab() · oklch() · r,g,b[,a] (byte values)

Rendering

Function	Output
renderHex(color)	#rrggbb
renderHexRgba(color)	#rrggbbaa
renderRgb(color)	rgb(r, g, b)
renderRgba(color)	rgba(r, g, b, a)
renderHsl(color)	hsl(h, s%, l%)
renderHsla(color)	hsla(h, s%, l%, a)
renderHsv(color)	hsv(h, s%, v%)
renderHsva(color)	hsva(h, s%, v%, a)
renderOklab(color)	oklab(L% a b)
renderOklch(color)	oklch(L% C H)
renderColor(color, format)	Dispatches to any of the above

All render functions accept ColorRgbLike and convert internally as needed.

ColorRenderFormat (const enum)

Hex · HexRgba · Rgb · Rgba · Hsl · Hsla · Hsv · Hsva · Oklab · Oklch

Blending

blend(base, layer, mode) - returns ColorRgb

ColorBlendMode (const enum)

Normal · Multiply · Screen · Overlay · Darken · Lighten · ColorDodge · ColorBurn · HardLight · SoftLight

Transformations

Function	Signature	Description
lerpRgb	(a, b, t) => ColorRgb	Linear interpolation in RGB
lerpOklch	(a, b, t) => ColorOklch	Perceptual interpolation in Oklch (shortest hue path)
lerpPerceptual	(a, b, t) => ColorRgb	RGB in, Oklch lerp, RGB out
lighten	(color, amount) => ColorRgb	Increase Oklch lightness
darken	(color, amount) => ColorRgb	Decrease Oklch lightness
saturate	(color, amount) => ColorRgb	Increase Oklch chroma
desaturate	(color, amount) => ColorRgb	Decrease Oklch chroma
rotateHue	(color, degrees) => ColorRgb	Rotate hue in Oklch
invert	(color) => ColorRgb	Invert RGB channels
grayscale	(color) => ColorRgb	Perceptual luminance grayscale
luminance	(color) => number	WCAG 2.0 relative luminance
contrastRatio	(a, b) => number	WCAG contrast ratio (1-21)

Utilities

Function	Signature	Description
colorFromString	(input, opts?) => { background, backgroundHex, text }	Deterministic color from any string (FNV-1a hash)
contrastTextFor	(color) => '#000' | '#fff'	Best contrast text color for a background