Reference

Options, methods and events

Options

createColorPicker(target, {
  value: '#3a86ff',
  format: 'hex',
  formats: ['hex', 'rgb', 'hsl', 'oklch'],
  alpha: true,
  swatches: [],
  eyedropper: true,
  copy: true,
  contrastAgainst: undefined,
  theme: 'auto',
  classNames: {},
  strings: {},
  onChange: undefined,
  onCommit: undefined,
});

Option	Type	Default	What it does
`value`	`string`	the target's value, else `#3a86ff`	The starting colour, in any notation.
`format`	`'hex' \| 'rgb' \| 'hsl' \| 'oklch'`	`'hex'`	Which notation the field shows first.
`formats`	`Format[]`	all four	Which ones the button cycles through. Give it one to hide the button's effect.
`alpha`	`boolean`	`true`	The opacity slider.
`swatches`	`string[]`	`[]`	Colours offered under the picker, as labelled buttons.
`eyedropper`	`boolean`	`true`	Shown only where the browser has the EyeDropper API.
`copy`	`boolean`	`true`	The copy button.
`contrastAgainst`	`string`	—	Show the WCAG contrast against this colour.
`theme`	`'light' \| 'dark' \| 'auto'`	`'auto'`	`auto` reads the page and keeps up with it.
`classNames`	`Partial<Record<PickerPart, string>>`	`{}`	Your classes, on any part.
`strings`	`Partial<PickerStrings>`	English	Every word the widget says.
`onChange`	`(value, picker) => void`	—	While the colour moves.
`onCommit`	`(value, picker) => void`	—	When it settles: a key press, a typed value, a swatch, letting go of the square.

target may be an <input> — which keeps its name and carries the value — or any element, which the picker simply renders into.

Methods

picker.element;           // the widget's root element
picker.getValue();        // '#3a86ff' — the notation on show
picker.getValue('oklch'); // 'oklch(63.7% 0.1953 259.5)'
picker.getRgb();          // { r: 58, g: 134, b: 255, a: 1 }
picker.setValue('#ffbe0b');
picker.setValue('#ffbe0b', true);   // silently: no callbacks, no events
picker.setFormat('hsl');
picker.destroy();         // gives the page its own input back, untouched

Events

Both are CustomEvents on the widget's root, and both bubble:

picker.element.addEventListener('dx:colorcommit', (event) => {
  event.detail.value;   // '#3a86ff'
  event.detail.rgb;     // { r: 58, g: 134, b: 255, a: 1 }
});

Event	When
`dx:colorchange`	The colour moved.
`dx:colorcommit`	It settled.

When the picker is mounted on an <input>, that input also gets the native input and change events, in the same places — which is what Livewire, Alpine, FormData, jQuery and any server-rendered form already listen for. Nothing else is needed to make a form work.

Words

createColorPicker(input, {
  strings: {
    area: 'التشبّع والسطوع',
    saturation: 'التشبّع',
    brightness: 'السطوع',
    hue: 'درجة اللون',
    alpha: 'الشفافية',
    value: 'قيمة اللون',
    format: 'صيغة اللون',
    eyedropper: 'التقط لونًا من الشاشة',
    copy: 'نسخ',
    copied: 'تم النسخ',
    areaValue: (s, v) => `التشبّع ${s}%، السطوع ${v}%`,
    swatch: (color) => `استخدم ${color}`,
    contrast: (ratio, rating) => `التباين ${ratio} إلى 1 — ${rating}`,
    outOfGamut: 'خارج نطاق sRGB — ستعرض هذه الشاشة أقرب لون ممكن',
  },
});

RTL needs nothing else: the layout uses logical properties, so dir="rtl" mirrors it.

Updated 12 Sep 2026

Options, methods and events

Options#

Methods#

Events#

Words#

Options

Methods

Events

Words