@zenuilabs/color-picker

A developer-friendly color picker component with TypeScript support, multiple interactive variants, and extensive customization options.

Live demo: https://color-picker.zenui.net/

Contents

• Features
• Installation
• Quick Start
• Usage Examples
• API Reference
  • ColorPicker
  • Types
  • Utilities
• Theming & Customization
• Compatibility / Requirements
• FAQ
• Contributing
• License
• Support

🚀 Features

• Multiple color formats: hex, rgb, hsl, hsv, cmyk
• Interactive variants:
  • Wheel picker
  • Hue slider
  • Hue box
• Brightness/Value slider and fine-grained inputs
• Format switcher and copy-friendly output
• Favorites and quick presets
• Color history and reset
• Light/Dark themes with custom theme support
• Fully typed with TypeScript
• Accessible, keyboard-friendly interactions
• Small and tree-shakeable

📦 Installation

Using npm:

npm install @zenuilabs/color-picker-react

⚡ Quick Start

import React, {useState} from 'react';
import {ColorPicker} from '@zenuilabs/color-picker-react';

export default function App() {
    const [color, setColor] = useState('#3B82F6');

    return (
        <div>
            <ColorPicker
                value={color}
                format="hex"
                variant="wheel"
                onChange={(next) => setColor(next.hex)}
            />
            <p>Selected: {color}</p>
        </div>
    );
}

🧪 Usage Examples

Basic (HEX, wheel):

import React, {useState} from 'react';
import {ColorPicker} from '@zenuilabs/color-picker-react';

function BasicExample() {
    const [color, setColor] = useState('#4F46E5');

    return (
        <ColorPicker
            value={color}
            format="hex"
            variant="wheel"
            onChange={(val) => setColor(val.hex)}
        />
    );
}

Use picker as inline:

import React, {useState} from 'react';
import {ColorPicker} from '@zenuilabs/color-picker-react';

function BasicExample() {
    const [color, setColor] = useState('#4F46E5');

    return (
        <ColorPicker
            value={color}
            format="hex"
            inline={true} // now the picker will render as inline
            variant="wheel"
            onChange={(val) => setColor(val.hex)}
        />
    );
}

Change format and access multiple representations:

import React, {useState} from 'react';
import {ColorPicker, type ColorFormat} from '@zenuilabs/color-picker-react';

function FormatExample() {
    const [format, setFormat] = useState<ColorFormat>('rgb');
    const [value, setValue] = useState('#22C55E');

    return (
        <div>
            <ColorPicker
                value={value}
                format={format}
                variant="hue-slider"
                onChange={(val, fmt) => {
                    // Persist a specific representation
                    setValue(fmt === 'hex' ? val.hex : val.hex);
                    // You can also handle the active format
                    setFormat(fmt);
                    console.log('As HEX:', val.hex);
                    console.log('As RGB:', val.rgb);
                    console.log('As HSL:', val.hsl);
                    console.log('As HSV:', val.hsv);
                    console.log('As CMYK:', val.cmyk);
                }}
            />
        </div>
    );
}

Hue box variant with presets, alpha, and history:

import React, {useState} from 'react';
import {ColorPicker} from '@zenuilabs/color-picker-react';

const presetColors = ['#FF6B6B', '#4ECDC4', '#45B7D1', '#F7B267', '#A78BFA'];

function AdvancedExample() {
    const [color, setColor] = useState('#F59E0B');

    return (
        <ColorPicker
            value={color}
            format="hsl"
            variant="hue-box"
            showAlpha
            showHistory
            showFormats
            showCopyButton
            presetColors={presetColors}
            maxHistory={15}
            onChange={(val) => setColor(val.hex)}
        />
    );
}

📚 API Reference

ColorPicker

A controlled React component. Provide a value and handle updates via onChange.

Props:

Notes:

• ColorValue includes every representation of the color (HEX, RGB, HSL, HSV, CMYK) so you can store or display any format without re-conversion.
• The component is designed to be controlled; keeping value in your state is recommended.

Types

export type ColorFormat = 'hex' | 'rgb' | 'hsl' | 'hsv' | 'cmyk';
export type ColorPickerVariant = 'wheel' | 'hue-slider' | 'hue-box'
export type Themes = 'light' | 'dark';

export interface ColorValue {
    hex: string;
    rgb: { r: number; g: number; b: number; a?: number };
    hsl: { h: number; s: number; l: number; a?: number };
    hsv: { h: number; s: number; v: number; a?: number };
    cmyk: { c: number; m: number; y: number; k: number };
}

export interface ColorPickerTheme {
    primary: string;
    secondary: string;
    background: string;
    surface: string;
    text: string;
    textSecondary: string;
    border: string;
    borderHover: string;
    shadow: string;
}

export interface ColorPickerProps {
    value?: string;
    format?: ColorFormat;
    variant?: ColorPickerVariant;
    theme?: Themes;
    disabled?: boolean;
    inline?: boolean;
    showColorInput?: boolean;
    showTitle?: boolean;
    title?: string
    popupClasses?: string;
    showAlpha?: boolean;
    showHistory?: boolean;
    showFormats?: boolean;
    showCopyButton?: boolean;
    presetColors?: string[];
    maxHistory?: number;
    containerClasses?: string;
    containerStyle?: React.CSSProperties;
    onChange?: (color: ColorValue, format: ColorFormat) => void;
    onFormatChange?: (format: ColorFormat) => void;
    onOpen?: () => void;
    onClose?: () => void;
    enableHueSlider?: boolean;
    brandColor?: string;
    enableFavorite?: boolean;
    showPresets?: boolean;
    enableShuffle?: boolean;
    triggerRef?: React.RefObject<HTMLElement>;
    showDefaultButton?: boolean;
}

export interface UseColorPickerOptions {
    initialColor?: string;
    initialFormat?: ColorFormat;
    showAlpha?: boolean;
    maxHistory?: number;
}

Utilities

Useful helpers are available for parsing and formatting colors.

import {
    parseColor,
    formatColorValue,
    colorToValue,
    hsvToRgb,
    defaultPresetColors,
    type ColorValue,
    type ColorFormat,
} from '@zenuilabs/color-picker-react';

• parseColor(input: string): ColorValue — Parses a string (HEX, RGB, HSL, etc.) into a full ColorValue.
• formatColorValue(value: ColorValue, format: ColorFormat): string — Converts a ColorValue to a formatted string.
• colorToValue(input: string | ColorValue): ColorValue — Normalizes arbitrary input to a ColorValue.
• hsvToRgb(h: number, s: number, v: number): { r: number; g: number; b: number } — Low-level conversion utility.
• defaultPresetColors: string[] — A ready-to-use list of common swatches.

🎨 Theming & Customization

You can switch between built-in themes.

Built-in theme:

<ColorPicker theme="dark"/>

Presets:

<ColorPicker presetColors={['#FF6B6B', '#4ECDC4', '#45B7D1']}/>

Alpha channel:

<ColorPicker showAlpha format="rgb"/>

History and favorites:

<ColorPicker showHistory showFavorites maxHistory={12}/>

✅ Compatibility / Requirements

• React: 16.8 or newer (Hooks support required; 18+ recommended)
• TypeScript: 5.x recommended (type definitions included)
• Node.js: 18+ recommended
• Module format: ESM-first
• Browsers: Modern browsers with standard Canvas and Pointer Events support

⚠️ Note: Advanced features may rely on newer web APIs. Ensure your target browsers support them.

❓ FAQ

• Controlled vs. uncontrolled?
  • The component is designed for controlled usage via value and onChange.
• How to store colors?
  • Store ColorValue if you need multiple formats. Otherwise, store a single string (e.g., hex) and derive other formats when necessary.
• Can I disable certain UI parts?
  • Use the boolean props like showFormats, showCopyButton, showHistory, etc., to tailor the UI.

🤝 Contributing

Contributions are welcome!

• Fork the repository
• Create a feature branch
• Commit your changes with clear messages
• Add/adjust tests where applicable
• Submit a pull request describing your changes and rationale

Before submitting:

• Ensure linting and type checks pass
• Ensure the demo/playground still works
• Update documentation if props or behavior changed

📄 License

MIT License

🆘 Support

• Issues: open a ticket at https://github.com/zenui-labs/zenui-color-picker/issues/new
• Contact: create an issue with details or reach us via your preferred channel

🧾 Type Definitions

This package ships with first-class TypeScript support. Types can be imported directly:

import type {
    ColorFormat,
    ColorValue,
    ColorPickerVariant,
    ColorPickerTheme,
} from '@zenuilabs/color-picker-react';

🛠️ Release & Build

• The package is published on npm as @zenuilabs/color-picker-react.
• ESM build with tree-shaking-friendly structure.
• CSS: no global stylesheet required; theming is provided via props and CSS variables.

A Product of @zenui-labs