Skip to content

Color Picker ​

A palette of color swatches for picking a single color — a product paint configurator, a theme picker, a label color chooser. It renders as a radiogroup: arrow keys move through the swatches, and the selection is form-associated so it submits with a <form>.

Options are passed as JSON. Each option needs a color (any CSS color); value and label default to it when omitted.

Basic Usage ​

PreviewCode
RTL
html
<ore-color-picker
  label="Paint"
  value="midnight"
  options='[
    { "value": "midnight", "color": "#19202b", "label": "Midnight Black" },
    { "value": "pearl", "color": "#f2efe9", "label": "Pearl White" },
    { "value": "crimson", "color": "#7a1f2b", "label": "Crimson" }
  ]'>
</ore-color-picker>

Listen for the selection:

html
<ore-color-picker id="paint" label="Paint" options='[{ "color": "#19202b" }, { "color": "#f2efe9" }]'></ore-color-picker>

<script type="module">
  document.getElementById('paint').addEventListener('change', (event) => {
    console.log('Selected:', event.detail.values[0], event.detail.labels[0]);
  });
</script>

Raw Colors ​

When an option has only a color, the color doubles as the value and the accessible name. This is the shortest form, good for a plain palette.

PreviewCode
RTL
html
<ore-color-picker
  label="Accent"
  value="#7c3aed"
  options='[{ "color": "#19202b" }, { "color": "#7c3aed" }, { "color": "#0891b2" }, { "color": "#059669" }]'>
</ore-color-picker>

Disabled Options ​

Mark an individual option disabled to render it without allowing selection — a sold-out paint, for instance.

PreviewCode
RTL
html
<ore-color-picker
  label="Finish"
  value="graphite"
  options='[
    { "value": "graphite", "color": "#3f3f46", "label": "Graphite" },
    { "value": "cobalt", "color": "#1d4ed8", "label": "Cobalt", "disabled": true },
    { "value": "sand", "color": "#d6c7a1", "label": "Sand" }
  ]'>
</ore-color-picker>

Sizes ​

PreviewCode
RTL
html
<ore-color-picker size="sm" options='[{ "color": "#19202b" }, { "color": "#7c3aed" }]' label="Small"></ore-color-picker>
<ore-color-picker size="md" options='[{ "color": "#19202b" }, { "color": "#7c3aed" }]' label="Medium"></ore-color-picker>
<ore-color-picker size="lg" options='[{ "color": "#19202b" }, { "color": "#7c3aed" }]' label="Large"></ore-color-picker>

Helper and Error Text ​

Pass helper for a hint below the swatches, or error to mark the field invalid. error takes precedence and is announced with role="alert".

PreviewCode
RTL
html
<ore-color-picker
  label="Wall color"
  helper="Sample swatches ship in every finish."
  options='[{ "color": "#e7e5e4" }, { "color": "#a8a29e" }, { "color": "#57534e" }]'>
</ore-color-picker>

<ore-color-picker
  label="Pick a color"
  error="Choose a color to continue."
  options='[{ "color": "#dc2626" }, { "color": "#2563eb" }]'>
</ore-color-picker>

Disabled ​

PreviewCode
RTL
html
<ore-color-picker
  label="Locked selection"
  value="#19202b"
  disabled
  options='[{ "color": "#19202b" }, { "color": "#f2efe9" }]'>
</ore-color-picker>

API Reference ​

Attributes ​

AttributeTypeDefaultDescription
optionsOreColorPickerOption[]N/ASelectable colors (JSON)
valuestringN/AValue of the selected option
labelstringN/AGroup label, shown as the fieldset legend and used as the accessible name
namestringN/AForm field name
disabledbooleanfalseDisables every swatch
size'sm' | 'md' | 'lg''md'Swatch diameter
helperstringN/AHelper text shown below the swatches
errorstringN/AError message below the swatches (takes precedence over helper)

Option shape ​

FieldTypeDescription
colorstringCSS color painted as the swatch (required)
valuestringValue reported on selection; defaults to color
labelstringAccessible name; defaults to value, then color
disabledbooleanRender the swatch but block selection

Events ​

EventDetailDescription
change{ values: string[]; labels: string[]; originalEvent?: Event }Fired when a color is selected

Parts ​

PartDescription
swatchesSwatch container
swatchA swatch button
legendGroup label
helper-textThe helper/error text element

CSS Custom Properties ​

PropertyDefaultDescription
--color-picker-swatch-sizesize presetSwatch diameter
--color-picker-swatch-radiusa circleSwatch corner radius
--color-picker-gapvar(--size-2)Gap between swatches

Accessibility ​

The control is a radiogroup and each swatch is a role="radio" with aria-checked reflecting the selection. The group's accessible name comes from label.

Exactly one swatch is a tab stop at a time (roving tabindex). When value is unset, or names an option that does not exist or is disabled, the tab stop falls back to the first enabled swatch — matching a native radio group, so the control is never unreachable by keyboard. ↑/← and ↓/→ move and commit the selection; Home/End jump to the first/last enabled swatch.

  • Radio Group: grouped native radio inputs
  • Rating: a star-based value picker with the same radiogroup semantics