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.

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

License

MIT License with attribution requirement

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

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE.md		LICENSE.md
README.md		README.md
oklume.css		oklume.css
oklume.js		oklume.js
oklume.min.js		oklume.min.js
oklume.min.js.map		oklume.min.js.map
package.json		package.json

License

ipatovanton/Oklume

Folders and files

Latest commit

History

Repository files navigation

Oklume

Table of Contents

Features

Quick Start

Option 1: NPM (Recommended)

Option 2: CDN (Fastest Setup)

Option 3: Manual Download

Additional Examples

Installation

Via npm

Via CDN

Manual Download

Usage Examples

1. Expanded Mode (Inline Display)

2. Compact Mode (Popup Display)

3. Form Integration

4. Custom Palette

5. Minimal Picker (Palette Only)

6. Programmatic Color Control

7. Hide Specific UI Elements

Configuration Options

Options Reference

API Reference

Constructor

Methods

setColor(l, c, h)

getColor()

togglePicker()

destroy()

checkBrowserSupport()

Color Formats

OKLCH (Recommended)

RGB

HEX

HSL

Editable Values

Customization

CSS Variables

Dark Theme Example

Custom Trigger Button (Compact Mode)

Browser Support

Feature Detection

Why OKLCH?

Key Benefits

Default Palette

Learn More

License

Author

Contributing

Changelog

Version 1.0.0

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

`setColor(l, c, h)`

`getColor()`

`togglePicker()`

`destroy()`

`checkBrowserSupport()`

Packages