chromakit-react

ChromaKit

The Modern React Color Picker with Perceptually Uniform Colors

Build better design systems with OKLCH color space support

Live Demo • Documentation • Migration Guide

npm install chromakit-react

See it in action →

Table of Contents

• Why ChromaKit
• Quick Start
• Why OKLCH?
• Features
• Framework Setup
• API Reference
• Examples
• Color Utilities
• Theming
• Browser Support
• TypeScript
• Troubleshooting

Why Developers Choose ChromaKit

The only React color picker built for modern design systems. While other pickers struggle with consistent color scales and muddy gradients, ChromaKit uses perceptually uniform color spaces (OKLCH, OKLAB) to deliver what designers expect and users see.

// Get started in 30 seconds
import { ColorPicker } from 'chromakit-react';
import 'chromakit-react/chromakit.css';

<ColorPicker onChange={(color) => console.log(color.oklch)} />;

Perfect For

• Design System Engineers - Generate consistent tonal scales with predictable lightness
• Accessibility Teams - Built-in WCAG AA/AAA contrast checking
• App Developers - Zero dependencies, 10KB bundle, works everywhere
• UI Libraries - Composable primitives, full TypeScript support

What Makes ChromaKit Different

Perceptually Uniform Colors

The Problem: Traditional RGB/HSL create inconsistent color scales. A 10% lightness change in blue looks different than in yellow. Your carefully crafted design system falls apart.

ChromaKit's Solution: OKLCH color space ensures equal numerical changes produce equal visual differences. Generate accessible color palettes that actually look evenly spaced.

// Generate a perfectly uniform color scale
const scale = Array.from({ length: 9 }, (_, i) => {
  const lightness = 0.2 + i * 0.1; // 20% to 100%
  return `oklch(${lightness} 0.15 250)`; // Consistently spaced blues
});

Composable Architecture

Unlike monolithic pickers, ChromaKit gives you building blocks:

import {
  ColorArea,
  HueSlider,
  AlphaSlider,
  useColorState,
} from 'chromakit-react';

// Build your perfect picker layout
function CustomPicker() {
  const { hsva, colorValue, updateColor } = useColorState('#6366F1');
  return (
    <>
      <ColorArea hsva={hsva} onChange={updateColor} />
      <HueSlider hsva={hsva} onChange={updateColor} />
      <AlphaSlider hsva={hsva} onChange={updateColor} />
    </>
  );
}

Built for Performance

• 10KB gzipped - Competitive with alternatives, but includes OKLCH + composability
• Zero dependencies - No supply chain risk, no version conflicts
• Tree-shakeable - Import only what you use
• 60fps interactions - Smooth dragging on all devices

Accessibility Baked In

• WCAG AA compliant - Full keyboard navigation, proper ARIA labels
• Contrast checker included - getContrastRatio(), meetsContrastRatio()
• Screen reader tested - Works with NVDA, JAWS, VoiceOver
• Touch-friendly - 44px minimum touch targets

TypeScript Excellence

Every color format, every component prop, every utility function - fully typed:

import type { ColorValue, OKLCHColor, RGBColor } from 'chromakit-react';

const handleChange = (value: ColorValue) => {
  value.oklch; // { l: number, c: number, h: number }
  value.rgb; // { r: number, g: number, b: number }
  value.hex; // string
};

Comparison

Feature	ChromaKit	react-colorful	react-color
Bundle Size	~10KB	~3KB	~28KB
OKLCH/OKLAB	✅	❌	❌
Composable	✅	Limited	❌
TypeScript	✅ Native	✅	⚠️ @types
Dark Mode	✅ Built-in	Manual	Manual
Dependencies	0	0	Many

Choose ChromaKit for: Design systems, OKLCH support, accessibility features, composability
Choose react-colorful for: Minimal bundle size (<5KB), traditional RGB/HSL only

Migration Guide available for switching from react-colorful or react-color.

Quick Start

Controlled Component (recommended)

import { useState } from 'react';
import { ColorPicker } from 'chromakit-react';
import 'chromakit-react/chromakit.css';

function App() {
  const [color, setColor] = useState('#6366F1');

  return (
    <ColorPicker
      value={color}
      onChange={(colorValue) => setColor(colorValue.hex)}
    />
  );
}

That's it! You now have a fully-featured color picker with OKLCH support, eyedropper, color history, and more.

Why OKLCH?

OKLCH is a perceptually uniform color space - equal numerical changes produce equal visual differences.

Key Benefits:

• Predictable Lightness: oklch(0.5 ...) appears equally bright regardless of hue, unlike HSL
• Better Gradients: Smooth transitions without muddy middle tones
• Design Systems: Generate consistent tonal scales with uniform visual weight
• Wide Gamut: Access more vibrant colors on modern displays

Parameters:

• L (Lightness): 0 (black) to 1 (white)
• C (Chroma): 0 (grayscale) to ~0.4 (vibrant)
• H (Hue): 0-360° around the color wheel

// HSL: Same lightness value, different perceived brightness
hsl(240, 100%, 50%) // Blue - looks dark
hsl(60, 100%, 50%)  // Yellow - looks bright

// OKLCH: Same lightness = same perceived brightness
oklch(0.5 0.2 240)  // Blue at 50% brightness
oklch(0.5 0.2 60)   // Yellow at 50% brightness

Learn more about OKLCH →

Framework Setup

Next.js App Router

'use client';
import { ColorPicker } from 'chromakit-react';
import 'chromakit-react/chromakit.css';

export function MyColorPicker() {
  const [color, setColor] = useState('#6366F1');
  return <ColorPicker value={color} onChange={(c) => setColor(c.hex)} />;
}

Next.js Pages Router (SSR)

import dynamic from 'next/dynamic';

const ColorPicker = dynamic(
  () => import('chromakit-react').then((mod) => mod.ColorPicker),
  { ssr: false }
);

Vite / CRA

import { ColorPicker } from 'chromakit-react';
import 'chromakit-react/chromakit.css';
// Works out of the box

API Reference

ColorPicker

Full-featured color picker component.

interface ColorPickerProps {
  value?: string;
  defaultValue?: string;
  onChange?: (color: ColorValue) => void;
  onChangeComplete?: (color: ColorValue) => void;
  formats?: ColorFormat[];
  showAlpha?: boolean;
  showInputs?: boolean;
  showPreview?: boolean;
  showCopyButton?: boolean;
  showEyeDropper?: boolean;
  showPresets?: boolean;
  presets?: string[];
  presetGroups?: PresetGroup[] | Record<string, string[]>;
  enableHistory?: boolean;
  width?: number;
  height?: number;
  className?: string;
}

Props:

Prop	Type	Default	Description
value	string	-	Controlled color value (any supported format)
defaultValue	string	'#6366F1'	Initial color for uncontrolled mode
onChange	(color: ColorValue) => void	-	Fires during color changes (real-time)
onChangeComplete	(color: ColorValue) => void	-	Fires when user completes a change (mouse up, blur)
formats	ColorFormat[]	['hex', 'rgb', 'hsl', 'oklch']	Available color format options
showAlpha	boolean	true	Enable alpha channel controlha channel control
showInputs	boolean	true	Show color input fields
showPreview	boolean	true	Show color preview swatch
showCopyButton	boolean	true	Show copy button (enables Cmd/Ctrl+C)
showEyeDropper	boolean	true	Show eyedropper button (if browser supports)
showPresets	boolean	true	Show preset colors section
presets	string[]	Built-in defaults	Custom preset colors array
presetGroups	PresetGroup[] or Record<string, string[]>	Built-in groups	Preset color groups with dropdown
enableHistory	boolean	true	Store recent colors in localStorage
width	number	auto	Custom picker width in pixels
height	number	100	Color area height in pixels
className	string	-	Additional CSS classes

ColorValue Object:

The onChange and onChangeComplete callbacks receive a ColorValue object:

interface ColorValue {
  hex: string; // "#ff6b6b"
  hex8: string; // "#ff6b6bff"
  rgb: RGBColor; // { r: 255, g: 107, b: 107 }
  rgba: RGBAColor; // { r: 255, g: 107, b: 107, a: 1 }
  hsl: HSLColor; // { h: 0, s: 100, l: 71 }
  hsla: HSLAColor; // { h: 0, s: 100, l: 71, a: 1 }
  hsv: HSVColor; // { h: 0, s: 58, v: 100 }
  hsva: HSVAColor; // { h: 0, s: 58, v: 100, a: 1 }
  oklch: OKLCHColor; // { l: 0.71, c: 0.19, h: 25 }
  oklcha: OKLCHAColor; // { l: 0.71, c: 0.19, h: 25, a: 1 }
  oklab: OKLABColor; // { l: 0.71, a: 0.17, b: 0.08 }
  oklaba: OKLABAColor; // { l: 0.71, a: 0.17, b: 0.08, alpha: 1 }
}

Composable Components

Build custom pickers using primitive components for complete layout control:

import {
  ColorArea,
  HueSlider,
  AlphaSlider,
  ColorPreview,
  ColorInputs,
  useColorState,
} from 'chromakit-react';

function CustomPicker() {
  const { hsva, colorValue, updateColor } = useColorState('#ff0000');

  return (
    <div className="custom-picker">
      <ColorArea hsva={hsva} onChange={updateColor} width={200} height={150} />
      <HueSlider hsva={hsva} onChange={updateColor} />
      <AlphaSlider hsva={hsva} onChange={updateColor} />
      <ColorPreview colorValue={colorValue} size="lg" />
      <ColorInputs
        colorValue={colorValue}
        onChange={(hex) => updateColor(parseColor(hex))}
        format="hex"
      />
    </div>
  );
}

Component Props:

ColorArea - 2D saturation/lightness picker

interface ColorAreaProps {
  hsva: HSVAColor;
  onChange: (hsva: HSVAColor) => void;
  onStart?: () => void;
  onEnd?: () => void;
  width?: number; // Default: 256
  height?: number; // Default: 200
  className?: string;
}

HueSlider - Hue selection slider

interface HueSliderProps {
  hsva: HSVAColor;
  onChange: (hsva: HSVAColor) => void;
  onStart?: () => void;
  onEnd?: () => void;
  vertical?: boolean; // Default: false
  className?: string;
}

AlphaSlider - Alpha/transparency slider

interface AlphaSliderProps {
  hsva: HSVAColor;
  onChange: (hsva: HSVAColor) => void;
  onStart?: () => void;
  onEnd?: () => void;
  vertical?: boolean; // Default: false
  className?: string;
}

ColorPreview - Color swatch with comparison

interface ColorPreviewProps {
  colorValue: ColorValue;
  showComparison?: boolean; // Show before/after
  originalColor?: string; // Original color for comparison
  size?: 'sm' | 'md' | 'lg'; // Default: 'md'
  className?: string;
}

ColorInputs - Format-switchable input fields

interface ColorInputsProps {
  colorValue: ColorValue;
  onChange: (hexColor: string) => void;
  format: ColorFormat;
  onFormatChange?: (format: ColorFormat) => void;
  showAlpha?: boolean;
  availableFormats?: ColorFormat[];
  className?: string;
}

ColorSwatch - Individual color button

interface ColorSwatchProps {
  color: string;
  onClick?: () => void;
  active?: boolean;
  size?: 'sm' | 'md' | 'lg';
  className?: string;
}

RecentColors - Color history display

interface RecentColorsProps {
  onColorSelect?: (color: string) => void;
  maxColors?: number; // Default: 10
  className?: string;
}

Hooks

useColorState - Main color state management hook

function useColorState(initialColor?: string) {
  return {
    hsva: HSVAColor;           // Internal HSVA representation
    colorValue: ColorValue;     // All format conversions
    updateColor: (hsva: HSVAColor) => void;
    setColorFromString: (color: string) => void;
  };
}

useDrag - Drag interaction handler (for custom components)

function useDrag(
  ref: RefObject<HTMLElement>,
  onDrag: (x: number, y: number) => void,
  onStart?: () => void,
  onEnd?: () => void
): void;

Examples

Basic Usage

Simple controlled picker

const [color, setColor] = useState('#6366F1');

<ColorPicker
  value={color}
  onChange={(colorValue) => setColor(colorValue.hex)}
/>;

Preset Colors

Custom preset colors

<ColorPicker
  value={color}
  onChange={(colorValue) => setColor(colorValue.hex)}
  presets={['#FF6B6B', '#4ECDC4', '#45B7D1', '#FFA07A', '#98D8C8', '#F7DC6F']}
/>

Preset groups with dropdown (New in v0.1.10)

const presetGroups = [
  {
    name: 'Material',
    colors: ['#F44336', '#E91E63', '#9C27B0', '#673AB7', '#3F51B5'],
  },
  {
    name: 'Tailwind',
    colors: ['#EF4444', '#F97316', '#EAB308', '#22C55E', '#10B981'],
  },
];

<ColorPicker
  value={color}
  onChange={(colorValue) => setColor(colorValue.hex)}
  presetGroups={presetGroups}
/>;

Or use object format:

const presetGroups = {
  Material: ['#F44336', '#E91E63', '#9C27B0', '#673AB7', '#3F51B5'],
  Tailwind: ['#EF4444', '#F97316', '#EAB308', '#22C55E', '#10B981'],
};

<ColorPicker
  value={color}
  onChange={(colorValue) => setColor(colorValue.hex)}
  presetGroups={presetGroups}
/>;

Format Control

Limit available formats

<ColorPicker
  value={color}
  onChange={(colorValue) => setColor(colorValue.hex)}
  formats={['oklch', 'hex', 'rgb']}
/>

Advanced Features

Track color changes completion

<ColorPicker
  value={color}
  onChange={(colorValue) => {
    // Fires during dragging (real-time updates)
    setColor(colorValue.hex);
  }}
  onChangeComplete={(colorValue) => {
    // Fires when user finishes selecting (mouse up, blur)
    // Perfect for API calls or expensive operations
    saveColorToDatabase(colorValue.hex);
  }}
/>

Color history with localStorage

<ColorPicker
  value={color}
  onChange={(colorValue) => setColor(colorValue.hex)}
  enableHistory={true} // Automatically saves recent colors
/>

Access all color formats

<ColorPicker
  value={color}
  onChange={(colorValue) => {
    console.log(colorValue.hex); // "#ff6b6b"
    console.log(colorValue.rgb); // { r: 255, g: 107, b: 107 }
    console.log(colorValue.oklch); // { l: 0.71, c: 0.19, h: 25 }
    setColor(colorValue.hex);
  }}
/>

Eyedropper & Copy Features

Built-in eyedropper and copy buttons

<ColorPicker
  value={color}
  onChange={(colorValue) => setColor(colorValue.hex)}
  showEyeDropper={true} // Shows eyedropper button (if browser supports)
  showCopyButton={true} // Shows copy button + enables Cmd/Ctrl+C
/>

Note: The EyeDropper API requires a secure context (HTTPS) and is currently supported in Chrome/Edge 95+, not yet in Firefox or Safari.

Form Integration

React Hook Form

import { Controller, useForm } from 'react-hook-form';
import { ColorPicker } from 'chromakit-react';

function MyForm() {
  const { control, handleSubmit } = useForm({
    defaultValues: { brandColor: '#6366F1' }
  });

  return (
    <form onSubmit={handleSubmit(data => console.log(data))}>
      <Controller
        name="brandColor"
        control={control}
        render={({ field }) => (
          <ColorPicker
            value={field.value}
            onChange={(c) => field.onChange(c.hex)}
          />
        )}
      />
    </form>
  );
}

Formik

import { useFormik } from 'formik';
import { ColorPicker } from 'chromakit-react';

function MyForm() {
  const formik = useFormik({
    initialValues: { brandColor: '#6366F1' },
    onSubmit: values => console.log(values)
  });

  return (
    <form onSubmit={formik.handleSubmit}>
      <ColorPicker
        value={formik.values.brandColor}
        onChange={(c) => formik.setFieldValue('brandColor', c.hex)}
      />
    </form>
  );
}

Color Utilities

Conversion Functions

Convert between any color format:

import {
  hexToRgb,
  rgbToHex,
  rgbToHsl,
  hslToRgb,
  rgbToOklch,
  oklchToRgb,
  parseColor,
  colorValueToString,
} from 'chromakit-react';

// Parse any format
const parsed = parseColor('#ff6b6b');
// Returns: { r: 255, g: 107, b: 107, a: 1 }

// Convert between formats
const rgb = hexToRgb('#ff0000'); // { r: 255, g: 0, b: 0 }
const hex = rgbToHex(rgb); // '#ff0000'
const hsl = rgbToHsl(rgb); // { h: 0, s: 100, l: 50 }
const oklch = rgbToOklch(rgb); // { l: 0.63, c: 0.26, h: 29 }

// Format color value to string
const color = { r: 255, g: 107, b: 107, a: 1 };
const hexString = colorValueToString(color, 'hex'); // "#ff6b6b"
const rgbString = colorValueToString(color, 'rgb'); // "rgb(255, 107, 107)"
const oklchString = colorValueToString(color, 'oklch'); // "oklch(0.71 0.19 25)"

Available conversion functions:

• hexToRgba(hex) - Parse hex to RGBA
• parseColor(color) - Parse any format to RGBA
• rgbToHex(rgb) - RGB to 6-digit hex
• rgbaToHex8(rgba) - RGBA to 8-digit hex
• rgbToHsl(rgb) / hslToRgb(hsl)
• rgbaToHsla(rgba) / hslaToRgba(hsla)
• rgbToHsv(rgb) / hsvToRgb(hsv)
• rgbaToHsva(rgba) / hsvaToRgba(hsva)
• rgbToOklab(rgb) / oklabToRgb(oklab)
• rgbaToOklaba(rgba) / oklabaToRgba(oklaba)
• rgbToOklch(rgb) / oklchToRgb(oklch)
• rgbaToOklcha(rgba) / oklchaToRgba(oklcha)
• oklabToOklch(oklab) / oklchToOklab(oklch)
• rgbaToColorValue(rgba) - Convert to all formats
• colorValueToString(colorValue, format) - Format to string

Color Formats

ChromaKit supports the following color formats:

Format	Example	Description
HEX	#ff0000	Hexadecimal RGB
HEX8	#ff0000ff	Hex with alpha
RGB	rgb(255, 0, 0)	Red, Green, Blue
RGBA	rgba(255, 0, 0, 1)	RGB with alpha
HSL	hsl(0, 100%, 50%)	Hue, Saturation, Lightness
HSLA	hsla(0, 100%, 50%, 1)	HSL with alpha
HSV	hsv(0, 100%, 100%)	Hue, Saturation, Value
HSVA	hsva(0, 100%, 100%, 1)	HSV with alpha
OKLCH	oklch(0.63 0.26 29)	Perceptually uniform cylindrical
OKLCHA	oklch(0.63 0.26 29 / 1)	OKLCH with alpha
OKLAB	oklab(0.63 0.22 0.13)	Perceptually uniform Cartesian

Theming & Customization

Override CSS variables for custom themes:

.my-custom-picker {
  --ck-primary: #9333ea;
  --ck-bg: #0a0a0b;
  --ck-text: #ffffff;
  --ck-radius: 8px;
}

<ColorPicker className="my-custom-picker" />

See source CSS for all available variables.

Browser Support

ChromaKit works in all modern browsers:

• Chrome/Edge: 88+
• Firefox: 87+
• Safari: 15+
• Node.js: 20+ (for SSR/build tools)

Feature Support

Feature	Browser Support	Fallback
Color Picker	All modern browsers	-
OKLCH/OKLAB calculations	All modern browsers	-
CSS oklch() syntax	Chrome 111+, Firefox 113+, Safari 15.4+	Use hex/rgb output
EyeDropper API	Chrome/Edge 95+	Button hidden automatically
Clipboard API	All modern browsers (HTTPS required)	Manual copy

For CSS OKLCH color space support, see Can I Use: OKLCH.

TypeScript

ChromaKit is written in TypeScript and provides complete type definitions for all exports.

Type Exports

import type {
  // Color format types
  RGBColor,
  RGBAColor,
  HSLColor,
  HSLAColor,
  HSVColor,
  HSVAColor,
  OKLCHColor,
  OKLCHAColor,
  OKLABColor,
  OKLABAColor,

  // Utility types
  ColorFormat,
  ColorValue,
  AnyColor,

  // Component props
  ColorPickerProps,
  ColorAreaProps,
  HueSliderProps,
  AlphaSliderProps,

  // Preset types
  PresetGroup,
  PresetGroupsInput,
} from 'chromakit-react';

Type-Safe Color Conversions

import {
  rgbToHsl,
  hslToRgb,
  type RGBColor,
  type HSLColor,
} from 'chromakit-react';

const rgb: RGBColor = { r: 255, g: 107, b: 107 };
const hsl: HSLColor = rgbToHsl(rgb);
// Type: { h: number; s: number; l: number }

const backToRgb: RGBColor = hslToRgb(hsl);
// Fully typed with autocomplete

Troubleshooting

Common Issues

Issue: Styles not loading

Make sure to import the CSS file:

import 'chromakit-react/chromakit.css';

Or if using automatic imports, ensure your bundler processes CSS side effects.

Issue: Eyedropper not showing

The EyeDropper API requires:

• Secure context (HTTPS in production, localhost in development)
• Browser support (Chrome/Edge 95+)
• User permission

Check browser support:

if ('EyeDropper' in window) {
  // Eyedropper available
}

Issue: TypeScript errors with color formats

Ensure you're using the correct types:

import type { ColorValue } from 'chromakit-react';

const handleChange = (colorValue: ColorValue) => {
  // colorValue has all format properties
  console.log(colorValue.hex);
  console.log(colorValue.oklch);
};

Issue: Next.js "window is not defined" error

For server-side rendering, use dynamic imports:

import dynamic from 'next/dynamic';

const ColorPicker = dynamic(
  () => import('chromakit-react').then((mod) => mod.ColorPicker),
  { ssr: false }
);

Issue: Color history not persisting

History uses localStorage with key chromakit-color-history. Ensure:

• localStorage is available (not in incognito/private mode)
• enableHistory prop is true (default)
• Browser has storage permissions

Clear history manually:

import { clearColorHistory } from 'chromakit-react';
clearColorHistory();

**I## Resources

• Migration Guide - Switch from react-colorful/react-color
• Performance Benchmarks - Bundle size & speed comparisons
• Contributing Guide - Help improve ChromaKit
• Changelog - Release notes

Support

• Issues - Report bugs
• Discussions - Ask questions
• Sponsor - Support development

License

MIT © Garrett Siegel

Credits

Built with:

• React - UI framework
• TypeScript - Type safety
• Vite - Build tool

chromakit.site

Star on GitHub • Try Live Demo • Report Bug Color science based on:

• OKLCH specification - W3C standard
• Oklab color space - Björn Ottosson's research

Design inspired by:

• Radix UI - Component patterns
• Tailwind CSS - Color palettes

chromakit.site

```