hcg-color-picker-react

A Google Chrome style color picker — React component, lightweight, alpha support, EyeDropper API.

Also available as: Vanilla JS  ·  Vanilla JS npm  ·  npm package

---

Preview

---

Features

• Native React component — no vanilla JS wrapper needed
• Multiple instances — each picker is fully independent, no shared state
• Three color modes — HEX, RGBA, HSLA
• Alpha / opacity control — enable or disable per instance
• EyeDropper API — pick any color from the screen (Chrome/Edge)
• Touch support — works on mobile and tablet
• Debounce option — built-in debounce prop for throttling the change event
• Ref API — call setColor, getColor, open, close and more from parent
• Portal rendering — picker renders at document.body level, no overflow issues

---

Installation

npm install hcg-color-picker-react

---

Import

import ColorPicker from 'hcg-color-picker-react';
import 'hcg-color-picker-react/ColorPicker.css';

createPortal is used internally — no extra setup needed.

---

Basic Usage

import ColorPicker from 'hcg-color-picker-react';
import 'hcg-color-picker-react/ColorPicker.css';

function App() {
    return (
        <ColorPicker
            color="#ff0000"
            onChange={(colors, source) => {
                console.log(colors.hex);   // "#ff0000"
                console.log(colors.rgba);  // "rgba(255, 0, 0, 1)"
                console.log(colors.hsla);  // "hsla(0, 100%, 50%, 1)"
                console.log(source);       // "drag" | "input" | "api" | "eyedropper"
            }}
        />
    );
}

---

Props

Prop	Type	Default	Description
color	string	'#ff0000'	Initial color — HEX, RGB, HSL formats
onChange	function	—	Called with (colors, source) every time the color changes
onOpen	function	—	Called with the current hex when the picker opens
onClose	function	—	Called with the final hex when the picker closes
alpha	boolean	true	Set to false to disable alpha control
debounce	number	0	ms to debounce the change event (0 = off)
disabled	boolean	false	Prevents the picker from opening
className	string	—	CSS class applied to the trigger button
style	object	—	Inline styles for the trigger button

---

Color Formats

<ColorPicker color="#ff0000" />               // 6-digit HEX
<ColorPicker color="#ff0000ff" />             // 8-digit HEX with alpha
<ColorPicker color="#f00" />                  // 3-digit HEX shorthand
<ColorPicker color="#f00a" />                 // 4-digit HEX shorthand with alpha
<ColorPicker color="rgb(255, 0, 0)" />        // RGB
<ColorPicker color="rgba(255, 0, 0, 0.5)" />  // RGBA
<ColorPicker color="hsl(0, 100%, 50%)" />     // HSL
<ColorPicker color="hsla(0, 100%, 50%, 1)" /> // HSLA

---

onChange — callback signature

<ColorPicker onChange={(colors, source) => { /* ... */ }} />

colors object

{
    hex:  "#ff0000",
    hexa: "#ff0000ff",
    rgb:  "rgb(255, 0, 0)",
    rgba: "rgba(255, 0, 0, 1)",
    hsl:  "hsl(0, 100%, 50%)",
    hsla: "hsla(0, 100%, 50%, 1)"
}

source string

The second argument identifies what triggered the color change:

Value	Triggered by
"drag"	Dragging the color box, hue, or alpha slider
"input"	Typing into HEX, RGBA, or HSLA inputs
"api"	Calling ref.current.setColor() programmatically
"eyedropper"	Picking a color with the EyeDropper API

<ColorPicker
    onChange={(colors, source) => {
        if (source === 'drag') { /* update live preview only */ }
        if (source === 'api')  { /* skip — we triggered this */ }
    }}
/>

---

Examples

No alpha

<ColorPicker color="#ff0000" alpha={false} onChange={handleChange} />

Debounce

Fire onChange only after the user stops dragging for 200ms — useful for expensive handlers like API calls or heavy re-renders:

<ColorPicker color="#ff0000" debounce={200} onChange={handleChange} />

Disabled

<ColorPicker color="#ff0000" disabled={true} />

---

Programmatic API via ref

Use ref to call methods directly from a parent component:

import { useRef } from 'react';
import ColorPicker from 'hcg-color-picker-react';
import 'hcg-color-picker-react/ColorPicker.css';

function App() {
    const pickerRef = useRef(null);

    return (
        <div>
            <ColorPicker
                ref={pickerRef}
                color="#ff9800"
                onChange={colors => console.log(colors.hex)}
            />

            <button onClick={() => pickerRef.current.setColor('#e91e63')}>Set Pink</button>
            <button onClick={() => alert(pickerRef.current.getColor().hex)}>Get Color</button>
            <button onClick={() => pickerRef.current.open()}>Open</button>
            <button onClick={() => pickerRef.current.close()}>Close</button>
            <button onClick={() => pickerRef.current.setAlphaEnabled(false)}>Disable Alpha</button>
        </div>
    );
}

Ref Methods

Method	Description
.setColor(color)	Programmatically set the color
.getColor()	Returns current color as an object
.setAlphaEnabled(bool)	Show or hide the alpha slider at runtime
.open()	Programmatically open the picker
.close()	Programmatically close the picker
.enable()	Enable the picker
.disable()	Disable the picker

.getColor()

pickerRef.current.getColor();
// {
//     hex:  "#ff0000",
//     hexa: "#ff0000ff",
//     rgb:  "rgb(255, 0, 0)",
//     rgba: "rgba(255, 0, 0, 1)",
//     hsl:  "hsl(0, 100%, 50%)",
//     hsla: "hsla(0, 100%, 50%, 1)"
// }

pickerRef.current.getColor().hex   // "#ff0000"
pickerRef.current.getColor().rgba  // "rgba(255, 0, 0, 1)"
pickerRef.current.getColor().hsla  // "hsla(0, 100%, 50%, 1)"

---

Multiple Instances

Each <ColorPicker> is fully independent — no shared state:

function App() {
    return (
        <div>
            <ColorPicker color="#f44336" onChange={c => console.log('Picker 1:', c.hex)} />
            <ColorPicker color="#4caf50" onChange={c => console.log('Picker 2:', c.hex)} />
            <ColorPicker color="#2196f3" alpha={false} onChange={c => console.log('Picker 3:', c.hex)} />
        </div>
    );
}

---

TypeScript

The package ships with a bundled index.d.ts — no @types/ install needed.

import { useRef } from 'react';
import ColorPicker, {
    HcgColorSet,
    HcgColorSource,
    ColorPickerRef,
    ColorPickerProps,
} from 'hcg-color-picker-react';
import 'hcg-color-picker-react/ColorPicker.css';

function App() {
    const pickerRef = useRef<ColorPickerRef>(null);

    const handleChange = (colors: HcgColorSet, source: HcgColorSource) => {
        console.log(colors.hex);   // "#ff0000"
        console.log(colors.rgba);  // "rgba(255, 0, 0, 1)"
        console.log(source);       // "drag" | "input" | "api" | "eyedropper"
    };

    const props: ColorPickerProps = {
        color:    '#ff0000',
        alpha:    true,
        debounce: 150,
        onChange: handleChange,
    };

    return (
        <div>
            <ColorPicker ref={pickerRef} {...props} />
            <button onClick={() => pickerRef.current?.setColor('#00ff00')}>Set Green</button>
            <button onClick={() => console.log(pickerRef.current?.getColor())}>Get Color</button>
        </div>
    );
}

---

Browser Support

Feature	Support
Color picker UI	All modern browsers
Touch events	iOS Safari, Android Chrome
EyeDropper API	Chrome 95+, Edge 95+ (not Firefox / Safari)

---

License

MIT