ColorPicker
Introduction
An advanced input control that allows users to select and customize colors via a saturation/brightness area, hue and alpha sliders, editable channel inputs (HEX, RGBA, HSLA), and pre-defined swatches.
The ColorPicker component is fully integrated as an interactive colorPicker block in the Page Builder, allowing content authors and developers to easily configure labels, default states, Popover trigger modes, and sizing scales directly within the CMS.
Usage
These examples illustrate how content editors bind and structure color picker components.
1. Inline Customizer (Standard Hex Default)
An inline color picker that occupies block-level space in the page layout, rendering the saturation field, hue sliders, and channel inputs immediately on load.
{
"type": "colorPicker",
"label": "Brand Primary Color",
"defaultValue": "#7c3aed",
"interactive": true
}
2. Popover Swatch Trigger with Close On Selection
An elegant, space-saving design option that renders a small colored swatch trigger. Clicking the swatch opens the color picker panel inside a popover layer, automatically closing upon selecting a preset color swatch.
{
"type": "colorPicker",
"label": "Choose Theme Accent",
"defaultValue": "#22c55e",
"trigger": true,
"closeOnSelect": true,
"interactive": true
}
3. Disabled Picker State
Demonstrates a locked or inactive color customizer. This disables all sliders, input channels, swatch selection buttons, and triggers.
{
"type": "colorPicker",
"label": "Accent Tint (Inactive)",
"defaultValue": "#e2e8f0",
"disabled": true,
"interactive": true
}
Props
| Property | CMS Field Type | Default | Description / Supported Options |
|---|---|---|---|
Label Text (label) | string | - | Optional visual companion text positioned above the color picker area or popover trigger. |
Default Value (defaultValue) | string | "#7c3aed" | Initial active color. Accepts hex format strings (e.g. "#7c3aed", "#3b82f6"). |
Trigger (Popover) (trigger) | boolean | false | When true, replaces the full inline picker layout with a floating popover card anchored to a colored swatch button. |
Close On Select (closeOnSelect) | boolean | false | When true, closes the popover immediately after selecting a preset swatch. (Only applicable when trigger is true). |
Disabled (disabled) | boolean | false | Freezes all visual sliders, custom preset selections, eye-droppers, and input fields. |
Size Scale (size) | select | "md" | Scales the width and height of the saturation board, swatches, and margins. • Options: "sm", "md", "lg". |
Developer Notes & Accessibility
- Smart Hydration Island: To handle mouse dragging on the saturation grid and dynamic slider positioning, the ColorPicker automatically hydrates as a Preact island on client machines.
- Form Integration: It outputs a native hidden
<input type="hidden">carrying the active color's hex string value. This guarantees native form submissions capture active values out-of-the-box. - Aria Accessible Sliders: All slider fields, sliders boards, and input fields carry semantic ARIA attributes (
role="slider",aria-valuemin,aria-valuemax,aria-valuenow). Standard keyboard navigation (left/right/up/down arrows) is fully supported natively. - Accurate Conversions: Conversions between HSVA, HSL, RGB, and Hex formats occur internally at the render level. This prevents color drift and rounding mismatches across selected input formats.