Oklume


A production-ready OKLCH color picker with zero dependencies

Oklume is a modern, lightweight color picker built for the OKLCH (Oklab) color space — a perceptually uniform color model that makes color selection more intuitive and predictable. Perfect for designers and developers who want accurate, accessible color tools.

---

Table of Contents

- Features
- Quick Start
- Installation
- Usage Examples
- Configuration Options
- API Reference
- Color Formats
- Customization
- Browser Support
- Why OKLCH?
- License

---

Features

- Zero Dependencies — Pure vanilla JavaScript, no external libraries required
- OKLCH Color Space — Perceptually uniform colors that look natural
- Multiple Formats — Export to OKLCH, RGB, HEX, and HSL (all CSS-ready strings)
- Two Display Modes — Expanded (inline) and compact (popup)
- Customizable UI — Show/hide sliders, preview, and output formats as needed
- 160 Curated Colors — 18 hue families (8 shades each) + 16 grayscales covering the full spectrum
- Editable Values — Click any color value to edit it directly (supports all formats)
- Keyboard Friendly — ESC to close, Enter to apply, click outside to dismiss
- Responsive Design — Works seamlessly on mobile and desktop
- Custom Palettes — Use your own color collections
- Production Ready — Stable, tested, and optimized

---

Quick Start

Choose your preferred installation method:

$3

1. Install via npm:

``bash
npm install oklume
`

2. Import in your JavaScript:

`javascript
import Oklume from 'oklume';
import 'oklume/style.css';
`

3. Add a container element:

`html



`

4. Initialize Oklume:

`javascript
const picker = new Oklume('#color-picker', {
onChange: (color) => {
console.log(color.oklch);
document.body.style.backgroundColor = color.oklch;
}
});
`

---

$3

1. Include Oklume from CDN:

`html


`

2. Add a container element:

`html



`

3. Initialize Oklume:

`javascript
const picker = new Oklume('#color-picker', {
onChange: (color) => {
console.log(color.oklch);
document.body.style.backgroundColor = color.oklch;
}
});
`

---

$3

1. Download the files:
- oklume.css — Stylesheet (15KB)
- oklume.js — JavaScript (36KB)

2. Include in your HTML:

`html


`

3. Add a container element:

`html



`

4. Initialize Oklume:

`javascript
const picker = new Oklume('#color-picker', {
onChange: (color) => {
console.log(color.oklch);
document.body.style.backgroundColor = color.oklch;
}
});
`

---

$3

Initialize with element reference:

`javascript
const element = document.querySelector('#color-picker');
const picker = new Oklume(element, options);
`

Create multiple pickers:

`javascript
const picker1 = new Oklume('#picker-1');
const picker2 = new Oklume('#picker-2', { mode: 'compact', trigger: '#btn-2' });
`

---

Installation

$3

`bash
npm install oklume
`

Then import in your JavaScript:

`javascript
// ES Modules
import Oklume from 'oklume';
import 'oklume/css';

// CommonJS
const Oklume = require('oklume');
`

And in your HTML or bundler config, include the CSS:

`html

`

Or if using a bundler (Webpack, Vite, Rollup), import directly:

`javascript
import 'oklume/style.css';
`

$3

`html


`

$3

Download the latest version from this repository:

- oklume.css — Stylesheet (15KB)
- oklume.js — JavaScript (36KB)

Include the files in your HTML:

`html


`

---

Usage Examples

$3

Display the color picker directly on the page:

`html



`

$3

Open the picker in a popup when clicking a button:

`html
Choose Color



`

Compact Mode Features:
- Click the trigger button to open/close the picker
- Press ESC to close the picker
- Click outside the picker (on backdrop) to close
- The trigger button's background color updates to match the selected color
- Includes a "Close" button inside the picker

$3

Use the color picker with forms:

`html


Background Color:
Pick Color


`

$3

Use your own color palette:

`javascript
const customPalette = [
{ l: 0.5, c: 0.2, h: 0 }, // Red
{ l: 0.6, c: 0.25, h: 130 }, // Green
{ l: 0.55, c: 0.26, h: 240 }, // Blue
{ l: 0.9, c: 0.1, h: 70 }, // Yellow
];

const picker = new Oklume('#picker', {
palette: customPalette
});
`

$3

Show only the color palette without sliders or output:

`javascript
const picker = new Oklume('#picker', {
showSliders: false,
showFormats: false,
onChange: (color) => {
document.body.style.backgroundColor = color.oklch;
}
});
`

$3

Set and get colors programmatically:

`javascript
const picker = new Oklume('#picker');

// Set to a warm orange
picker.setColor(0.7, 0.15, 30);

// Get current color
const currentColor = picker.getColor();
console.log(currentColor.oklch); // 'oklch(0.7 0.15 30)'
console.log(currentColor.hex); // '#d99f7f'
console.log(currentColor.rgb); // 'rgb(217, 159, 127)'
`

$3

Customize which UI elements are visible:

`javascript
// Hide preview section
const picker1 = new Oklume('#picker1', {
showPreview: false
});

// Show only specific color formats
const picker2 = new Oklume('#picker2', {
showFormats: ['oklch', 'hex']
});

// Ultra minimal - only palette
const picker3 = new Oklume('#picker3', {
showPreview: false,
showSliders: false,
showFormats: false
});
`

---

Configuration Options

When creating a new Oklume instance, you can pass these options:

`javascript
const picker = new Oklume(container, {
mode: 'expanded',
trigger: null,
palette: null,
onChange: null,
showPreview: true,
showSliders: true,
showFormats: ['oklch', 'rgb', 'hex', 'hsl']
});
`

$3

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| mode | string | 'expanded' | Display mode: 'expanded' (inline) or 'compact' (popup) |
| trigger | string\|HTMLElement | null | Required for compact mode: Button or element that opens the picker |
| palette | Array<{l, c, h}> | 160 default colors | Custom palette of OKLCH colors |
| onChange | Function | null | Callback fired when color changes. Receives color object: {oklch, rgb, hex, hsl} |
| showPreview | boolean | true | Show/hide the preview box |
| showSliders | boolean | true | Show/hide the sliders (Lightness, Chroma, Hue) |
| showFormats | Array\|false | ['oklch','rgb','hex','hsl'] | Array of format names to display, or false to hide all |

---

API Reference

$3

`javascript
new Oklume(container, options)
`

Parameters:
- container (string|HTMLElement) — CSS selector or DOM element where the picker will be rendered
- options (Object) — Configuration options (see Configuration Options)

Example:
`javascript
const picker = new Oklume('#my-picker', {
mode: 'expanded',
onChange: (color) => console.log(color)
});
`

---

$3

#### setColor(l, c, h)

Programmatically set the current color.

`javascript
picker.setColor(0.7, 0.15, 30);
`

Parameters:
- l (number) — Lightness (0-1)
- c (number) — Chroma (0-0.4)
- h (number) — Hue (0-360)

---

#### getColor()

Get the current color in all supported formats.

`javascript
const color = picker.getColor();
// Returns:
// {
// oklch: 'oklch(0.7 0.15 30)',
// rgb: 'rgb(217, 159, 127)',
// hex: '#d99f7f',
// hsl: 'hsl(21, 56%, 67%)'
// }
`

Returns: Object with CSS-ready color strings

---

#### togglePicker()

Toggle the picker open/closed (compact mode only).

`javascript
picker.togglePicker();
`

---

#### destroy()

Remove the picker from the DOM and clean up all event listeners.

`javascript
picker.destroy();
`

---

#### checkBrowserSupport()

Check if the current browser supports OKLCH colors.

`javascript
if (!picker.checkBrowserSupport()) {
console.warn('OKLCH not fully supported in this browser');
}
`

Returns: boolean — true if OKLCH is supported

---

Color Formats

Oklume outputs colors in four CSS-ready formats:

$3

`javascript
'oklch(0.7 0.15 30)'
`

- Lightness: 0 (black) to 1 (white)
- Chroma: 0 (gray) to 0.4 (maximum saturation)
- Hue: 0-360 degrees

$3

`javascript
'rgb(217, 159, 127)'
`

$3

`javascript
'#d99f7f'
`

$3

`javascript
'hsl(21, 56%, 67%)'
`

$3

All displayed color values are editable. Click on any value to edit it:

- OKLCH: oklch(0.7 0.15 30) or 0.7 0.15 30
- RGB: rgb(217, 159, 127) or 217, 159, 127
- HEX: #d99f7f or d99f7f or #fff (3-digit shorthand supported)
- HSL: hsl(21, 56%, 67%) or 21, 56%, 67%

Keyboard Shortcuts:
- Press Enter to apply changes
- Click outside the field to apply changes
- Press ESC (in compact mode) to close the picker

The picker automatically parses various color format inputs and converts them to OKLCH internally.

---

Customization

$3

Customize the appearance using CSS custom properties:

`css
:root {
/ Colors /
--oklume-bg: oklch(1 0 0); / Background /
--oklume-border: oklch(0.9 0 0); / Borders /
--oklume-text: oklch(0.25 0 0); / Text /
--oklume-text-muted: oklch(0.45 0 0); / Muted text /
--oklume-accent: oklch(0.5 0.25 250); / Accent color /

/ Dimensions /
--oklume-max-width: min(350px, 100vw - 32px);
--oklume-preview-height: clamp(80px, 20vw, 120px);
--oklume-swatch-size: clamp(28px, 8vw, 36px);

/ Spacing /
--oklume-gap: clamp(3px, 1vw, 6px);
--oklume-gap-section: clamp(12px, 4vw, 20px);
--oklume-padding: clamp(8px, 3vw, 16px);

/ Border radius /
--oklume-radius: clamp(4px, 1.5vw, 8px);

/ Animation /
--oklume-transition-speed: 0.2s;
}
`

$3

`css
:root {
--oklume-bg: oklch(0.2 0 0);
--oklume-border: oklch(0.3 0 0);
--oklume-text: oklch(0.9 0 0);
--oklume-text-muted: oklch(0.7 0 0);
--oklume-accent: oklch(0.6 0.25 280);
}
`

$3

Style your trigger button however you want:

`html

Pick Color

`

---

Browser Support

Oklume requires modern browsers with OKLCH support:

| Browser | Minimum Version |
|---------|----------------|
| Chrome | 111+ |
| Safari | 15.4+ |
| Firefox | 113+ |
| Edge | 111+ |

The library automatically checks for browser support and displays a warning if OKLCH is not available.

$3

`javascript
const picker = new Oklume('#picker');

if (!picker.checkBrowserSupport()) {
// Provide fallback UI or use RGB values
console.warn('OKLCH not supported, falling back to RGB');
}
`

---

Why OKLCH?

OKLCH (Oklab with Lightness, Chroma, Hue) is a perceptually uniform color space that offers significant advantages over traditional RGB/HSL:

$3

- Perceptual Uniformity — Equal changes in values produce equal perceived color differences
- Predictable Lightness — L=0.5 looks 50% bright regardless of hue
- Better Gradients — Smooth color transitions without muddy middle tones
- Wider Gamut — Access to more vibrant colors than sRGB
- Accessible — Easier to maintain consistent contrast ratios

$3

Oklume includes 160 carefully curated OKLCH colors:

- 18 hue families spanning the full color spectrum (Red, Orange, Yellow, Green, Cyan, Blue, Purple, Pink, etc.)
- 8 shades per family from light to dark
- 16 grayscale colors from pure white to pure black
- All colors are perceptually uniform and harmonious
- Default starting color: warm orange oklch(0.7 0.15 30)`

$3

- OKLCH Color Space Guide
- A perceptual color space for image processing
- MDN: OKLCH Colors

---

License

MIT License with attribution requirement

Copyright (c) 2025 Anton Ipatov

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

Attribution requirement: If you use this software in a publicly distributed product, you must include attribution to "Oklume by Anton Ipatov" in your documentation or user interface.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

---

Author

Anton Ipatov
Twitter: @ipatovanton

---

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

---

Changelog

$3

- Initial release
- Expanded and compact display modes
- 160 curated OKLCH colors
- Multiple color format outputs (OKLCH, RGB, HEX, HSL)
- Customizable UI: show/hide sliders and output formats
- Editable color values
- Responsive design
- Accessibility features