Alwan

A lightweight, customizable, and touch-friendly color picker implemented in vanilla JavaScript, with no external dependencies.

           

Demo

👉 Try it live

Features

• Lightweight and efficient.
• Touch-friendly interface.
• Supports dark theme.
• Includes alpha channel (opacity) control.
• Supports multiple color formats: HSL, RGB, and HEX.
• Fully keyboard accessible.
• Simple and intuitive user interface, inspired by Google Chrome’s color picker.
• No external dependencies.
• Allows copying color values to the clipboard.

Getting started

Install using package manager:

npm install alwan

or

yarn add alwan

Import files

// Import javascript.
import Alwan from 'alwan';
// Import css.
import 'alwan/css';

CDN

Add it to your page.

CSS (required)

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/alwan@2/dist/css/alwan.min.css"/>

Javascript (Choose one)

• UMD

<script src="https://cdn.jsdelivr.net/npm/alwan@2/dist/js/alwan.min.js"></script>

• ES Module

<script type="module">
    import Alwan from "https://cdn.jsdelivr.net/npm/alwan@2/dist/js/esm/alwan.min.js";
</script>

• IIFE

<script src="https://unpkg.com/alwan@2/dist/js/iife/alwan.min.js"></script>

Note: You can also use the unpkg CDN as an alternative.

Usage

Alwan accepts two arguments: a reference element, which can be either a selector or an HTML element (required), and an optional options object.

const alwan = new Alwan('#reference', {
    // Options...
});

Options

You can explore and experiment with these options in the demo.

Note: In the reference element you can access the CSS custom property --color (--alwan-color before v2.0.0) to get color value

Accessibility

All interactive elements include ARIA labels with default values in English. These labels can be customized through the i18n option.

ℹ️ Note:: title and aria-label are identical for all buttons except swatches

// i18n default values.
    {
        i18n: {
            // Deprecated – use `picker` instead.
            palette: 'Color picker',
            // ARIA label for the color picking area.
            picker: 'Color picker',

            buttons: {
                // ARIA label and title for the copy button.
                copy: 'Copy color to clipboard',

                // ARIA label and title for the change-format button.
                changeFormat: 'Change color format',

                // Template for ARIA labels of swatch buttons. %label% is replaced with the swatch label or color value.
                // The title (tooltip) shows the swatch label or color value.
                // Ex:
                //   { color: '#008080', label: 'teal' }
                //     ARIA label  => 'Color swatch: teal'
                //     Title (tooltip) => 'teal'
                // Or a color value only:
                //   '#008080'
                //     ARIA label  => 'Color swatch: #008080'
                //     Title (tooltip) => '#008080'
                swatch: 'Color swatch: %label%',

                // ARIA label and title for the toggle-swatches button (since v2.0.0).
                toggleSwatches: 'Toggle Swatches'
            },

            sliders: {
                // ARIA label for the hue slider.
                hue: 'Change hue',
                // ARIA label for the alpha slider.
                alpha: 'Change opacity'
            }
        }
    }

Events

Use the on method, which accepts two parameters: event and handler (a callback function).

alwan.on('event', (ev) => {
    // ...
});

Event object (since v1.3)

• type — Event type.
• source — The color picker instance that triggered the event handler.
• h: number — Hue.
• s: number — Saturation.
• l: number — Lightness.
• r: number — Red.
• g: number — Green.
• b: number — Blue.
• a: number — alpha.
• rgb: string — RGB color string.
• hsl: string — HSL color string.
• hex: string — Hex color.

// e.g.
alwan.on('change', (ev) => {
    ev.type; // change
    ev.source; // Color picker instance.

    // HSL color components.
    ev.h;
    ev.s;
    ev.l;

    // RGB color components.
    ev.r;
    ev.g;
    ev.b;

    // Alpha channel.
    ev.a;

    // Colors strings.
    ev.rgb;
    ev.hsl;
    ev.hex;
});

Methods

Static methods:

• version(): string — Returns the version.
• setDefaults(defaults: alwanOptions) — Updates the default options for all new instances (does not affect existing ones).

Instance methods:

• setColor(color: Color) : Alwan — Sets the picker's color programmatically. Accepts any supported color format (hex, rgb, or hsl).
• getColor() : alwanValue — Returns the color object.
• open() — Opens or shows the color picker.
• close() — Closes or hides the color picker.
• isOpen() : boolean — true when the picker is open, false when closed.
• toggle() — Opens the picker if closed, or closes it if open.
• setOptions(options: alwanOptions) — Updates the picker's options dynamically.
• trigger(event: alwanEventType) — Programmatically triggers the specified event on the color picker.
• on(event: alwanEventType, handler: alwanEventHandler) — Attaches an event handler to the color picker.
• off(event?: alwanEventType, handler?: alwanEventHandler) — Detaches event handlers; omit handler to remove all handlers for an event, omit event to remove all handlers entirely.
• disable() — Disables the color picker, preventing any user interaction.
• enable() — Enables the color picker, allowing user interaction.
• reposition() — Updates the popover’s position relative to its target element.
• addSwatches(...swatches: Array<Swatch>) — Adds one or more color values to the picker's swatches array.
• removeSwatches(...items: Array<Swatch | number>) — Removes one or more color swatches. Each item can be a color value or its index in the config.swatches array.
• reset() — Resets the color picker to its default color.
• destroy() — Completely removes the color picker functionality and frees associated memory.

See also

• react-alwan – React wrapper for this library