Color Picker

A compact color swatch that opens a popover panel with a saturation/lightness palette, a hue slider, an alpha slider, and a HEX/RGB value input. Its value accepts and emits standard CSS color strings.

Use when you need to let users pick a color with a saturation/hue/alpha panel and HEX/RGB input: <r-colorpicker> accepts and emits standard CSS color strings and reports every format on change.

Quick Start

Basic Usage

<r-colorpicker value="#006bff"></r-colorpicker> <r-colorpicker value="rgba(255,0,0,0.5)"></r-colorpicker>

Click the swatch (or focus it and press Enter/Space) to open the panel. The hue and alpha sliders are keyboard-operable: arrow keys step by 1, Shift+arrow by 10, and Home/End jump to the ends.

API Reference

Properties

Value value

The current color, as a CSS color string. Accepts HEX (#1677FF, #fff), rgb(...), and rgba(...) on the way in. On the way out, the canonical value read back is a 6-digit HEX string when the color is fully opaque, or an rgba(...) string when alpha is below 1.

<r-colorpicker value="#00c853"></r-colorpicker>
<r-colorpicker value="rgb(22, 119, 255)"></r-colorpicker>
<r-colorpicker value="rgba(255, 0, 0, 0.5)"></r-colorpicker>

const picker = document.createElement('r-colorpicker');
picker.value = '#00c853';
console.log(picker.value); // reads back the current color
toolbar.append(picker);

Disabled disabled

Add the disabled attribute to make the picker inert: the swatch no longer opens the panel (via mouse or keyboard), it is taken out of the tab order, and the host is marked aria-disabled="true". Removing the attribute restores normal interaction.

<r-colorpicker value="#006bff" disabled></r-colorpicker>

const picker = document.createElement('r-colorpicker');
picker.disabled = true; // block interaction
picker.disabled = false; // re-enable
toolbar.append(picker);

External Styles sheet

CSS injected into the component's shadow DOM. It follows the same sheet convention used by every other ranui component.

<r-colorpicker value="#006bff" sheet=".ran-colorpicker { border-radius: 6px; }"></r-colorpicker>

Events

change

Fires whenever the color changes: dragging the palette, moving a slider, editing the value input, or setting the value attribute. It bubbles and is composed (crosses shadow boundaries). event.detail carries the color in every format:

<r-colorpicker value="#1677ff"></r-colorpicker>

<script>
  const picker = document.createElement('r-colorpicker');
  picker.addEventListener('change', (e) => {
    console.log(e.detail.hex, e.detail.alpha);
  });
  toolbar.append(picker);
</script>

CSS Parts

The trigger swatch exposes two parts for styling from outside the shadow DOM:

r-colorpicker::part(block) {
  box-shadow: 0 0 0 1px var(--line);
}

The popover panel is portaled into document.body, so its styles are namespaced (.ran-color-picker-*) and travel with the panel rather than living on the host.

CSS Variables

The trigger swatch reads these tokens:

r-colorpicker {
  --ran-colorpicker-border-radius: 6px;
}

Best Practices

• Input formats: Feed value any CSS color string: HEX, rgb(...), or rgba(...); the picker normalizes it internally.
• Reading the result: Listen for change and read event.detail for the exact format you need (hex, rgb, rgba, alpha).
• Alpha: Use rgba(...) input or the alpha slider when you need transparency; the read-back value becomes an rgba(...) string whenever alpha drops below 1.
• Keyboard: The swatch and both sliders are focusable and keyboard-operable; no mouse is required.
• Importing: Load via import 'ranui' (registers every component) or the standalone import 'ranui/colorpicker'.