# Alwan
A lightweight, customizable, and touch-friendly color picker implemented in vanilla JavaScript, with no external dependencies.
---
---
## Demo
π [Try it live](https://sefianecho.github.io/alwan/)
## 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:
```shell
npm install alwan
```
or
```
yarn add alwan
```
Import files
```javascript
// Import javascript.
import Alwan from 'alwan';
// Import css.
import 'alwan/css';
```
## CDN
Add it to your page.
### CSS (required)
```html
```
### Javascript (Choose one)
- UMD
```html
```
- ES Module
```html
```
- IIFE
```html
```
**Note:** You can also use the [unpkg CDN](https://unpkg.com/alwan@2/dist/) 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.
```javascript
const alwan = new Alwan('#reference', {
// Options...
});
```
## Options
> _You can explore and experiment with these options in the [demo](https://sefianecho.github.io/alwan/)_.
| Option | Type | Default | Description |
|------------------|-------------------------|----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id` | `string` | `""` | Assign an ID to the color picker widget. |
| `classname` | `string` | `""` | Adds one or more classes (separated by spaces) to the preset button. |
| `theme` | `light\|dark` | `light` | Choose between the 'dark' and 'light' themes. |
| `toggle` | `boolean` | `true` | Toggles the visibility of the color picker. Setting this option to false keeps the picker always visible. |
| `popover` | `boolean` | `true` | Determines whether the color picker is displayed as a popover (true) or inline within the page content (false). |
| `position` | `popoverPosition` | `bottomβstart` | Sets the popoverβs placement relative to the target or reference element. Format: side-alignment (side: top, right, bottom, left; alignment: start, center, end, with center optional). The picker will automatically adjust if there is insufficient space. |
| `margin` | `number` | `4` | Sets the distance, in pixels, between the picker container and the popover target element (either `target` or the reference element). |
| `preset` | `boolean` | `true` | Replaces the reference element with a pre-styled button. |
| `color` | `Color` | `#000` | Sets the initial color of the color picker. |
| `default` | `Color` | `""` | Specifies the default color of the color picker. |
| `target` | `string\|Element` | `""` | A selector or HTML element used as the reference. When popover is true, the picker is positioned relative to it; when false, the picker is inserted immediately after it. |
| `disabled` | `boolean` | `false` | Disables the color picker, preventing users from selecting colors. |
| `format` | `colorFormat` | `rgb` | Determines how the color value is represented (hex, rgb, or hsl). |
| `inputs` | `boolean\|inputFormats` | `true` | Controls color input fields. Accepts true (all inputs), false (no inputs), or an object to enable specific formats (e.g., `{ hsl: true, rgb: false, hex: true }`). |
| `singleInput` | `boolean` | `false` | Uses one input for the full color value instead of separate inputs for each color component. |
| `opacity` | `boolean` | `true` | Enables alpha channel for transparency. |
| `preview` | `boolean` | `true` | Adds a preview element for the selected color. |
| `copy` | `boolean` | `true` | Adds a button to copy the selected color. |
| `swatches` | `Swatch[]` | `[]` | Array of swatches, where each item is a color or an object with a color and optional label, invalid values default to `#000`. _See the [Accessibility](#accessibility) section for details about labeling._ |
| `toggleSwatches` | `boolean` | `false` | Adds a button to toggle the swatches container. |
| `colorOnScroll` | `boolean` | `false` | Closes the popover picker on scroll. |
| `parent` | `string\|Element` | `""` | Selector or HTML element that the picker container is appended to. |
**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_
```javascript
// 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).
```javascript
alwan.on('event', (ev) => {
// ...
});
```
| Event | Argument | Description |
| -------- | -------- | -------------------------------------------------------------------------------------------------- |
| `open` | `event` | Fired when the color picker is opened. |
| `close` | `event` | Fired when the color picker is closed. |
| `change` | `event` | Fired when a change to the color is committed, similar to the native DOM `change` event. |
| `color` | `event` | Fired continuously as the color changes, similar to the native DOM input event. |
### 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.
```javascript
// 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`) β Adds one or more color values to the picker's swatches array.
- **removeSwatches**(...items: `Array`) β 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](https://github.com/sefianecho/react-alwan) β React wrapper for this library
