hcg-color-picker

A lightweight, dependency-free Google Chrome style color picker. Supports multiple instances, alpha control, touch input, and the EyeDropper API.

Links: GitHub  ·  React component  ·  React GitHub

Preview

Features

• No dependencies — pure vanilla JavaScript, no libraries required
• Multiple instances — attach a picker to any number of buttons, each remembers its own color
• Single shared UI — one picker element is reused across all instances, keeping memory usage minimal
• Three color modes — switch between HEX, RGBA, and HSLA input formats
• Alpha / opacity control — full transparency support, can be enabled or disabled per instance
• EyeDropper API — pick any color from the screen (supported browsers only)
• Touch support — works on mobile and tablet devices
• Keyboard accessible — color text inputs are fully keyboard navigable
• data-color attribute — current color always available on the trigger element
• Event system — subscribe and unsubscribe to color change events
• Programmatic API — set color, open/close, enable/disable, and destroy instances at runtime
• open / close events — listen for when the picker is shown or hidden
• Debounce option — built-in change event throttling for expensive handlers

Installation

npm install hcg-color-picker

Import

// ESM
import hcgColor from 'hcg-color-picker';

// CommonJS
const hcgColor = require('hcg-color-picker');

Also import the CSS:

import 'hcg-color-picker/hcg-color.css';

Basic Usage

import hcgColor from 'hcg-color-picker';
import 'hcg-color-picker/hcg-color.css';

const picker = new hcgColor(
    document.getElementById('my-color-btn'),
    { color: '#ff0000' }
);

picker.on('change', function (colors, source) {
    console.log(colors.hex);   // "#ff0000"
    console.log(source);       // "drag" | "input" | "api" | "eyedropper"
});

Constructor

new hcgColor(element, options)

| Parameter | Type | Required | Description | |-----------|---------------|----------|----------------------------| | element | HTMLElement | ✅ | The trigger button element | | options | object | ❌ | Configuration (see below) |

Options

| Option | Type | Default | Description | |------------|------------|-------------|-----------------------------------------------------| | color | string | data-color attr or '#ff0000' | Initial color — HEX, RGB, HSL formats | | onChange | function | — | Shorthand change callback (same as .on('change')) | | onOpen | function | — | Shorthand open callback (same as .on('open')) | | onClose | function | — | Shorthand close callback (same as .on('close')) | | alpha | boolean | true | Set to false to disable alpha control | | debounce | number | 0 | ms to debounce the change event during drag (0 = off) | | disabled | boolean | false | Start in disabled state — also reads element.disabled |

const picker = new hcgColor(btn, {
    color:    '#ff0000',
    onChange: colors => console.log(colors.hex),
    alpha:    true,
    debounce: 150,
    disabled: false
});

Initial Color Formats

new hcgColor(el, { color: '#ff0000' });               // 6-digit HEX
new hcgColor(el, { color: '#ff0000ff' });              // 8-digit HEX with alpha
new hcgColor(el, { color: '#f00' });                   // 3-digit HEX shorthand
new hcgColor(el, { color: '#f00a' });                  // 4-digit HEX shorthand with alpha
new hcgColor(el, { color: 'rgb(255, 0, 0)' });         // RGB
new hcgColor(el, { color: 'rgba(255, 0, 0, 0.5)' });   // RGBA
new hcgColor(el, { color: 'hsl(0, 100%, 50%)' });      // HSL
new hcgColor(el, { color: 'hsla(0, 100%, 50%, 1)' });  // HSLA

Instance Methods

.on(event, callback)

Subscribe to an event.

picker.on('change', function (colors, source) {
    console.log(colors.hex);   // "#ff0000"
    console.log(colors.rgb);   // "rgb(255, 0, 0)"
    console.log(colors.rgba);  // "rgba(255, 0, 0, 1)"
    console.log(colors.hsl);   // "hsl(0, 100%, 50%)"
    console.log(colors.hsla);  // "hsla(0, 100%, 50%, 1)"
    console.log(source);       // "drag" | "input" | "api" | "eyedropper"
});

.off(event, callback)

Unsubscribe a specific listener.

function onChange(colors) { console.log(colors.hex); }

picker.on('change', onChange);
picker.off('change', onChange);

.setColor(color)

Programmatically set the color. Fires the change event.

picker.setColor('#00ff00');
picker.setColor('rgb(0, 255, 0)');

.getColor()

Returns the current color as an object with all formats:

picker.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)"
// }

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

.setAlphaEnabled(boolean)

Enable or disable the alpha slider at runtime.

picker.setAlphaEnabled(false);
picker.setAlphaEnabled(true);

.open()

Programmatically open the picker.

picker.open();

.close()

Programmatically close the picker.

picker.close();

.isOpen (getter)

Returns true if this picker is currently open.

if (picker.isOpen) {
    picker.close();
}

.disable() / .enable()

Disable or re-enable the picker.

picker.disable();
picker.enable();

.destroy()

Remove the picker instance and clean up all event listeners.

picker.destroy();

Events

| Event | Callback args | Description | |----------|-----------------------|------------------------------------| | change | colors, source | Fired every time the color changes | | open | hex | Fired when the picker opens | | close | hex | Fired when the picker closes |

picker.on('open',  hex => console.log('opened with:', hex));
picker.on('close', hex => console.log('closed with:', hex));

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 to the change callback identifies what triggered the change:

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

picker.on('change', (colors, source) => {
    if (source === 'drag') { /* update live preview only */ }
    if (source === 'api')  { /* skip — we triggered this */ }
});

Multiple Instances

const picker1 = new hcgColor(document.getElementById('btn1'), { color: '#ff0000' });
const picker2 = new hcgColor(document.getElementById('btn2'), { color: '#0000ff' });
const picker3 = new hcgColor(document.getElementById('btn3'), { color: '#00ff00', alpha: false });

picker1.on('change', colors => console.log('Picker 1:', colors.hex));
picker2.on('change', colors => console.log('Picker 2:', colors.hex));

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