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:

Option 1: NPM (Recommended)

1. Install via npm:

npm install oklume

2. Import in your JavaScript:

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

3. Add a container element:

<div id="color-picker"></div>

4. Initialize Oklume:

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

Option 2: CDN (Fastest Setup)

1. Include Oklume from CDN:

<link rel="stylesheet" href="https://unpkg.com/oklume/oklume.css">
<script src="https://unpkg.com/oklume/oklume.js"></script>

2. Add a container element:

<div id="color-picker"></div>

3. Initialize Oklume:

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

Option 3: Manual Download

1. Download the files:

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

2. Include in your HTML:

<link rel="stylesheet" href="path/to/oklume.css">
<script src="path/to/oklume.js"></script>

3. Add a container element:

<div id="color-picker"></div>

4. Initialize Oklume:

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

Additional Examples

Initialize with element reference:

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

Create multiple pickers:

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

Installation

Via npm

npm install oklume

Then import in your 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:

<link rel="stylesheet" href="node_modules/oklume/oklume.css">

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

import 'oklume/style.css';

Via CDN

<link rel="stylesheet" href="https://unpkg.com/oklume/oklume.css">
<script src="https://unpkg.com/oklume/oklume.js"></script>

Manual Download

Download the latest version from this repository:

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

Include the files in your HTML:

<link rel="stylesheet" href="path/to/oklume.css">
<script src="path/to/oklume.js"></script>

Usage Examples

1. Expanded Mode (Inline Display)

Display the color picker directly on the page:

<div id="color-picker"></div>

<script>
    const picker = new Oklume('#color-picker', {
        mode: 'expanded',
        onChange: (color) => {
            console.log('Selected color:', color.oklch);
        }
    });
</script>

2. Compact Mode (Popup Display)

Open the picker in a popup when clicking a button:

<button id="color-button">Choose Color</button>
<div id="color-picker"></div>

<script>
    const picker = new Oklume('#color-picker', {
        mode: 'compact',
        trigger: '#color-button',
        onChange: (color) => {
            document.body.style.backgroundColor = color.oklch;
        }
    });
</script>

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. Form Integration

Use the color picker with forms:

<form>
    <label>Background Color:</label>
    <button type="button" id="color-btn">Pick Color</button>
    <input type="hidden" name="color" id="color-value">
    <div id="picker"></div>
</form>

<script>
    const colorInput = document.getElementById('color-value');

    const picker = new Oklume('#picker', {
        mode: 'compact',
        trigger: '#color-btn',
        onChange: (color) => {
            colorInput.value = color.oklch;
        }
    });

    // Set initial color
    picker.setColor(0.7, 0.15, 30);
    colorInput.value = picker.getColor().oklch;
</script>

4. Custom Palette

Use your own color palette:

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
});

5. Minimal Picker (Palette Only)

Show only the color palette without sliders or output:

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

6. Programmatic Color Control

Set and get colors programmatically:

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)'

7. Hide Specific UI Elements

Customize which UI elements are visible:

// 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:

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

Options Reference

| 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<string>\|false | ['oklch','rgb','hex','hsl'] | Array of format names to display, or false to hide all |

API Reference

Constructor

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:

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

Methods

setColor(l, c, h)

Programmatically set the current color.

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.

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).

picker.togglePicker();

destroy()

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

picker.destroy();

checkBrowserSupport()

Check if the current browser supports OKLCH colors.

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:

OKLCH (Recommended)

'oklch(0.7 0.15 30)'

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

RGB

'rgb(217, 159, 127)'

HEX

'#d99f7f'

HSL

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

Editable Values

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

CSS Variables

Customize the appearance using CSS custom properties:

: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;
}

Dark Theme Example

: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);
}

Custom Trigger Button (Compact Mode)

Style your trigger button however you want:

<button id="color-btn" style="
    width: 150px;
    height: 40px;
    border-radius: 20px;
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    color: white;
    border: none;
    cursor: pointer;
">
    Pick Color
</button>

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.

Feature Detection

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:

Key Benefits

• 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

Default Palette

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)

Learn More

• 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

Version 1.0.0

• 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