@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:

Prop	Type	Default	Description
value	string or ColorValue	—	Current color value (commonly HEX like #ffffff).
format	ColorFormat	'hex'	Active display/parse format: 'hex', 'rgb', 'hsl', 'hsv', or 'cmyk'.
variant	ColorPickerVariant	'wheel'	Visual variant: 'wheel', 'hue-slider', or 'hue-box'.
theme	Themes or ColorPickerTheme	'light'	Built-in theme ('light' or 'dark').
disabled	boolean	false	Disable all interactions.
showAlpha	boolean	true	Enable alpha channel control and display when supported.
showHistory	boolean	true	Track and display recently picked colors.
showTitle	boolean	true	Show a title of the picker.
showFormats	boolean	true	Show the format selector (HEX/RGB/HSL/HSV/CMYK).
showCopyButton	boolean	true	Show a one-click copy to clipboard for the active format.
presetColors	string[]	defaultPresetColors	Quick-access swatches displayed below the picker.
maxHistory	number	10	Maximum number of items kept in color history.
containerClasses	string	''	Additional CSS classes for the root element.
showColorInput	boolean	true	Show an input field to enter color values manually.
containerStyle	React.CSSProperties	—	Inline styles for the root element.
popupClasses	string	—	Additional CSS classes for the popup/colorContainer element.
onChange	(value: ColorValue, format: ColorFormat) => void	—	Called on any color change.
inline	boolean	false	Render the picker inline rather than in a popup.
title	string	'Color Picker'	Title text displayed on the picker.
enableHueSlider	boolean	false	Enable the hue slider for variant that supports it.
showPresets	boolean	true	Show preset color swatches.
onFormatChange	(format: ColorFormat) => void	—	Called when the active format changes.
onOpen	() => void	—	Callback fired when the color picker opens.
brandColor	string	—	Optional brand color used for styling or highlighting.
enableFavorite	boolean	false	Enable marking colors as favorites.
enableShuffle	boolean	false	Enable shuffle button for random colors.
onClose	() => void	—	Callback fired when the color picker closes.
triggerRef	React.RefObject	—	External reference to trigger the picker popup.
showDefaultButton	boolean	true	Show the default triggering button.

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