API

Every prop, read from the published type declarations at build time, so this table cannot disagree with what you actually get.

Props

Prop	Type	Default	Notes
`value` *	`string \| null \| undefined`	-	`oklch(L C H)` or hex.
`onChange` *	`(colour: string) => void`	-	Called with a canonical, gamut-clamped `oklch(L C H)` string.
`presets`	`string[]`	-
`recents`	`string[]`	-	Recently used colours, most recent first. Omit to let the picker keep its own list for the session; pass one to store them yourself, in a backend, or shared between pickers.
`onRecentsChange`	`(recents: string[]) => void`	-	Called with the new list when a colour is committed, for the controlled form above. Fires on commit, so on a pointer release, a preset, or a hex entry. Not on every value a drag passes through.
`maxRecents`	`number`	`8`	How many recents to keep. Ignored when `recents` is controlled: the list you pass is the list that renders.
`layout`	`PickerLayout`	`"chart"`	Visual arrangement. `chart` (the default) shows one large lightness x chroma plot above all three sliders; `side-by-side` adds a right rail for the readout and presets; `compact` drops the charts entirely and inlines each label with its slider; `stacked` gives every axis its own thin chart.
`parts`	`PickerParts`	`all on except gamutSwitch`	Turn parts off, e.g. `{ charts: false, name: false }`. All on by default.
`labels`	`Partial<Record<LabelKey, string>>`	`English`	Override for translation. Keys are the three axes, `outOfGamut`, and `outOf:<gamut id>` for a wider space's own notice.
`gamut`	`Gamut`	`SRGB`	The output space: what the sliders reach, what is clamped, and what is emitted. Defaults to sRGB. Import wider spaces from `@oklch-picker/core/gamuts`; omitting this ships none of that code.
`references`	`Gamut[]`	`[SRGB] when gamut is wider`	Spaces to outline on the charts without clamping to them. Defaults to sRGB whenever `gamut` is wider, so the safe region stays visible.
`gamutChoices`	`Gamut[]`	`gamut + references`	What the switcher offers, when `parts.gamutSwitch` is on. Defaults to the output gamut plus its references.
`onGamutChange`	`(gamut: Gamut) => void`	-	Called when a switcher button is pressed. Omit to leave the buttons inert. The app is driving `gamut` as a prop either way.
`classPrefix`	`string`	`"oklch-picker"`	Class prefix for every element, so styles can be overridden.
`className`	`string`	-

* required.

Names in each framework

The table above uses the React names. The others follow their own idiom for the value binding; everything else is identical.

Framework	Value	Change
React / Preact	`value`	`onChange`
Vue	`v-model`, or `:value` + `@change`
Svelte	`bind:value`
Solid	`value`	`onChange`
No framework	`value` attribute or property	`change` event

Events on the custom element

The element emits three events, each carrying its payload indetail. It deliberately stops its inner inputs' events, so a listener above the host only ever sees these:

Event	`detail`	Fires
`change`	`{ colour: string }`	On every value change, canonical and gamut-clamped
`gamutchange`	`{ gamut: Gamut }`	When a switcher button is pressed
`recentschange`	`{ recents: string[] }`	On commit, not during a drag

Colour utilities

The maths is exported separately and documented on its own page.