🛼 use-color

A TypeScript-first, OKLCH-based, framework-agnostic color library
that validates color strings at compile time.
Never ship an invalid color string again.

Compile-time Type Checking

The only color library that catches invalid colors at compile time.

+ color('#00ffaa')
- color('#00ffzz')
// Argument of type '"#00ffzz"' is not assignable to parameter of type...

+ color('rgb(255, 128, 0)')
- color('rgb(255, 128,)')
// Argument of type '"rgb(255, 128,)"' is not assignable to parameter of type...

+ color('oklch(0.7 0.15 180)')
- color('oklch(invalid)')
// Argument of type '"oklch(invalid)"' is not assignable to parameter of type...

+ color('hsl(180, 50%, 50%)')
- color('hsl(180, 50%)')
// Argument of type '"hsl(180, 50%)"' is not assignable to parameter of type...

This is the moat. No other library—not colord, chroma-js, or tinycolor2—can do this.

Installation

pnpm add use-color

npm install use-color

yarn add use-color

Usage

Parse Colors

import { color } from "use-color";

// All formats supported
const red = color("#ff0000");
const green = color("rgb(0, 255, 0)");
const blue = color("hsl(240, 100%, 50%)");
const purple = color("oklch(0.5 0.2 300)");
const coral = color("coral"); // Named CSS colors

// Object input
const custom = color({ r: 255, g: 128, b: 0 });

Transform Colors

const c = color("#3b82f6");

// Lightness
c.lighten(0.2); // Perceptually uniform lightening
c.darken(0.1);

// Saturation
c.saturate(0.3);
c.desaturate(0.2);
c.grayscale();

// Hue
c.rotate(45); // Rotate hue by degrees
c.complement(); // Rotate 180°

// Alpha
c.alpha(0.5); // Set alpha
c.opacify(0.1); // Increase alpha
c.transparentize(0.2); // Decrease alpha

// Others
c.invert();
c.mix(otherColor, 0.5);

Chain Transformations

const result = color("#e11d48")
  .lighten(0.1)
  .saturate(0.2)
  .rotate(15)
  .alpha(0.9)
  .toHex();

// "#ff2d5c"

Output Formats

const c = color("#3b82f6");

// Hex
c.toHex(); // "#3b82f6"
c.toHex8(); // "#3b82f6ff"
c.toHexShort(); // null (not compressible) or "#38f"

// RGB
c.toRgb(); // { r: 59, g: 130, b: 246, a: 1 }
c.toRgbString(); // "rgb(59, 130, 246)"
c.toRgbaString(); // "rgba(59, 130, 246, 1)"
c.toRgbModern(); // "rgb(59 130 246)"  (CSS Level 4)

// HSL
c.toHsl(); // { h: 217, s: 0.91, l: 0.60, a: 1 }
c.toHslString(); // "hsl(217, 91%, 60%)"
c.toHslaString(); // "hsla(217, 91%, 60%, 1)"
c.toHslModern(); // "hsl(217 91% 60%)"

// OKLCH (perceptually uniform)
c.toOklch(); // { l: 0.62, c: 0.19, h: 255, a: 1 }
c.toOklchString(); // "oklch(0.62 0.19 255)"

// Display P3 (wide gamut)
c.toP3String(); // "color(display-p3 0.35 0.52 0.93)"

// CSS (smart default)
c.toCss(); // "#3b82f6"
c.toCss({ format: "oklch" }); // "oklch(0.62 0.19 255)"

Safe Parsing

import { tryColor } from "use-color";

const result = tryColor(userInput);

if (result.ok) {
  // result.value is a Color instance
  console.log(result.value.toHex());
} else {
  // result.error is a ColorParseError
  console.error(result.error.message);
  console.error(result.error.code); // 'INVALID_HEX' | 'INVALID_RGB' | ...
}

Color Properties

const c = color("#3b82f6");

c.getAlpha(); // 1
c.getLightness(); // 0.62 (OKLCH lightness)
c.getChroma(); // 0.19 (OKLCH chroma)
c.getHue(); // 255 (OKLCH hue)

c.isDark(); // false
c.isLight(); // true

Accessibility

Built-in WCAG 2.1 contrast checking and auto-adjustment.

import { contrast, isReadable, ensureContrast, luminance } from "use-color";

const text = "#374151";
const background = "#ffffff";

// Relative luminance (WCAG formula)
luminance(text); // 0.18
luminance(background); // 1.0

// Contrast ratio (1-21)
contrast(text, background); // 7.49

// Readability checks
isReadable(text, background); // true (default: AA 4.5:1)
isReadable(text, background, { level: "AAA" }); // true (7:1)
isReadable(text, background, { level: "AA", size: "large" }); // true (3:1)

// Auto-adjust for accessibility
const adjusted = ensureContrast("#888888", background, 4.5);
adjusted.toHex(); // "#767676" (meets 4.5:1 ratio)

APCA (Experimental)

APCA is the next-generation contrast algorithm for WCAG 3.0.

import { apcaContrast } from "use-color";

// Returns Lc value (-108 to +106)
apcaContrast("#000000", "#ffffff"); // 106 (maximum contrast)
apcaContrast("#767676", "#ffffff"); // 63 (good for body text)

Note: APCA is still in development and not yet a W3C standard. Use for experimental projects.

Why OKLCH?

use-color uses OKLCH internally for all color manipulations. This ensures perceptually uniform results:

Operation	HSL (traditional)	OKLCH (use-color)
Lighten yellow vs blue	Yellow appears brighter	Both appear equally lighter
Desaturate	Colors shift unexpectedly	Consistent desaturation
Mix colors	Muddy intermediates	Vibrant, natural gradients

OKLCH is the color space used by Tailwind CSS v4, shadcn/ui, and modern design systems.

Display P3 Wide Gamut

93% of browsers support Display P3. All Apple devices since 2016 have P3 displays.

import { color, isInP3Gamut, clampToP3Gamut } from "use-color";

const vibrant = color("oklch(0.7 0.35 150)");

// Check gamut
isInP3Gamut(vibrant); // true (P3 is ~25% larger than sRGB)

// Output for modern displays
vibrant.toP3String(); // "color(display-p3 0.12 0.87 0.45)"

// Fallback for older displays
vibrant.toHex(); // "#00d96f" (clamped to sRGB)

Tree-Shakeable

Import only what you need. Every function is individually exportable.

// Only bundles these specific functions
import { parseHex, toHex, lighten } from "use-color";

const rgba = parseHex("#ff0000");
const lighter = lighten(rgba, 0.2);
const hex = toHex(lighter);

Modular Imports

For smaller bundles, import only what you need:

// Core only (~8KB gzip) - parsing, formatting, manipulation
import { color, lighten, darken, toHex } from "use-color/core";

// Accessibility functions (~3KB gzip)
import { contrast, isReadable, apcaContrast } from "use-color/a11y";

// Named colors (~2KB gzip) - adds 'coral', 'rebeccapurple', etc.
import { parseNamed, NAMED_COLORS } from "use-color/names";

// Display P3 wide gamut (~3KB gzip)
import { toP3String, isInP3Gamut } from "use-color/p3";

Import	Size (gzip)	Description
`use-color`	~10KB	Full bundle with everything
`use-color/core`	~8KB	Core color operations
`use-color/a11y`	~3KB	WCAG contrast, APCA
`use-color/names`	~2KB	CSS named colors
`use-color/p3`	~3KB	Display P3 gamut

Type Guards & Assertions

import { isHex, isRgb, isColor, assertHex } from "use-color";

// Type guards (return boolean)
isHex("#ff0000"); // true
isHex("#gggggg"); // false
isRgb("rgb(1,2,3)"); // true
isColor(something); // type narrowing

// Assertions (throw on invalid)
assertHex(userInput); // throws ColorParseError if invalid
// After this line, TypeScript knows userInput is valid

Comparison

Feature	use-color	colord	chroma-js	tinycolor2
Compile-time validation	✅	❌	❌	❌
OKLCH native	✅	Plugin	❌	❌
P3 wide gamut	✅	❌	❌	❌
Accessibility	Built-in	Plugin	❌	Basic
Tree-shakeable	✅	✅	❌	❌
Modular imports	✅	❌	❌	❌
Bundle size (gzip)	8-10KB	2.1KB	16.7KB	5.3KB
TypeScript	Excellent	Good	Poor	Poor
Maintained	✅	❌ 3yr	⚠️	⚠️

Migration

From colord

- import { colord } from 'colord';
+ import { color } from 'use-color';

- const c = colord('#ff0000');
+ const c = color('#ff0000');

// Methods are mostly identical
c.lighten(0.1).toHex();

Key differences:

use-color uses OKLCH for transformations (better visual results)
Compile-time validation catches errors earlier

From chroma-js

- import chroma from 'chroma-js';
+ import { color, mix } from 'use-color';

- const c = chroma('#ff0000');
+ const c = color('#ff0000');

- chroma.mix('#ff0000', '#0000ff', 0.5);
+ mix(color('#ff0000'), color('#0000ff'), 0.5);

From tinycolor2

- import tinycolor from 'tinycolor2';
+ import { color } from 'use-color';

- const c = tinycolor('#ff0000');
+ const c = color('#ff0000');

- c.lighten(10).toString();
+ c.lighten(0.1).toHex();  // Note: use-color uses 0-1 range

API Reference

Factory Functions

Function	Description
`color(input)`	Create Color instance (throws on invalid)
`tryColor(input)`	Safe parsing, returns `Result<Color, ColorParseError>`

Color Methods

Manipulation (returns new Color)

Method	Description
`.lighten(amount)`	Increase lightness (0-1)
`.darken(amount)`	Decrease lightness (0-1)
`.saturate(amount)`	Increase chroma (0-1)
`.desaturate(amount)`	Decrease chroma (0-1)
`.grayscale()`	Remove all chroma
`.rotate(degrees)`	Rotate hue
`.complement()`	Rotate hue 180°
`.alpha(value)`	Set alpha (0-1)
`.opacify(amount)`	Increase alpha
`.transparentize(amount)`	Decrease alpha
`.invert()`	RGB inversion
`.invertLightness()`	OKLCH lightness inversion
`.mix(color, ratio)`	Mix with another color

Output (returns string/object)

Method	Description
`.toHex()`	`"#rrggbb"`
`.toHex8()`	`"#rrggbbaa"`
`.toRgb()`	`{ r, g, b, a }`
`.toRgbString()`	`"rgb(r, g, b)"`
`.toHsl()`	`{ h, s, l, a }`
`.toHslString()`	`"hsl(h, s%, l%)"`
`.toOklch()`	`{ l, c, h, a }`
`.toOklchString()`	`"oklch(l c h)"`
`.toP3String()`	`"color(display-p3 r g b)"`
`.toCss(options?)`	Smart CSS output

Properties

Method	Description
`.getAlpha()`	Get alpha value
`.getLightness()`	Get OKLCH lightness
`.getChroma()`	Get OKLCH chroma
`.getHue()`	Get OKLCH hue
`.isDark()`	Lightness < 0.5
`.isLight()`	Lightness >= 0.5

Standalone Functions

All Color methods are also available as standalone, tree-shakeable functions:

import { lighten, darken, mix, contrast, toHex } from "use-color";

Name		Name	Last commit message	Last commit date
Latest commit History 177 Commits
.github		.github
.vscode		.vscode
packages		packages
.editorconfig		.editorconfig
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
biome.json		biome.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

🛼 use-color

Compile-time Type Checking

Installation

Usage

Parse Colors

Transform Colors

Chain Transformations

Output Formats

Safe Parsing

Color Properties

Accessibility

APCA (Experimental)

Why OKLCH?

Display P3 Wide Gamut

Tree-Shakeable

Modular Imports

Type Guards & Assertions

Comparison

Migration

API Reference

Factory Functions

Color Methods

Manipulation (returns new Color)

Output (returns string/object)

Properties

Standalone Functions

License

About

Uh oh!

Releases 8

Packages

Uh oh!

Contributors 6

Uh oh!

Languages

License

junhoyeo/use-color

Folders and files

Latest commit

History

Repository files navigation

🛼 use-color

Compile-time Type Checking

Installation

Usage

Parse Colors

Transform Colors

Chain Transformations

Output Formats

Safe Parsing

Color Properties

Accessibility

APCA (Experimental)

Why OKLCH?

Display P3 Wide Gamut

Tree-Shakeable

Modular Imports

Type Guards & Assertions

Comparison

Migration

API Reference

Factory Functions

Color Methods

Manipulation (returns new Color)

Output (returns string/object)

Properties

Standalone Functions

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 8

Packages 0

Uh oh!

Contributors 6

Uh oh!

Languages

Packages