Color Picker
CColorPicker combines a native color input with an enhanced spectrum, hue control, editable representation, and named swatches. Values are canonical lowercase #rrggbb strings.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class ColorPickerAtAGlance(Component):
template = '<c-CColorPicker label="Brand color" value="#7f56d9" />'
preview = ColorPickerAtAGlance()
preview # noqa: B018
Switch representations
Set format to hex, rgb, or hsl. The format changes only the editable representation; the submitted and callback value remains canonical HEX.
Show code
# ruff: noqa: E501 - embedded Citry templates remain readable as authored HTML
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class ColorPickerFormats(Component):
template = """<div class="color-format-grid"><c-CColorPicker label="RGB color" value="#12b76a" format="rgb" /><c-CColorPicker label="HSL color" value="#f79009" format="hsl" /></div>"""
css = ":where(.color-format-grid){display:grid;grid-template-columns:repeat(auto-fit,minmax(15rem,1fr));gap:1rem}"
preview = ColorPickerFormats()
preview # noqa: B018
Offer named swatches
Pass CColorSwatch records with validated color values and meaningful labels. Swatches are shortcuts, not a separate source of truth.
Show code
# ruff: noqa: ANN001, ANN201 - public snippets keep focus on component use
import citry_ui
from citry import Component, citry
from citry_ui import CColorSwatch
citry.register_library(citry_ui)
class ColorPickerSwatches(Component):
def template_data(self, _kwargs, _slots):
return {
"swatches": [
CColorSwatch("#7f56d9", "Violet"),
CColorSwatch("#12b76a", "Green"),
CColorSwatch("#f04438", "Red"),
CColorSwatch("#f79009", "Orange"),
]
}
template = '<c-CColorPicker label="Accent" c-swatches="swatches" />'
preview = ColorPickerSwatches()
preview # noqa: B018
Own value and popup state
Client value and open props are controlled. Change callbacks receive the requested value or state and details about the interaction.
Show code
# ruff: noqa: E501 - Alpine expression remains readable in the public example
from citry import Component
class ControlledColorPicker(Component):
template = """
<section x-data="{color:'#7f56d9',open:false}">
<c-CColorPicker label="Controlled accent" $c-props="{value:color,open,onValueChange:(next)=>color=next,onOpenChange:(next)=>open=next}" />
<output x-text="color">#7f56d9</output>
</section>
"""
preview = ControlledColorPicker()
preview # noqa: B018
Submit with native forms
The native color input remains the successful form control. It also owns form reset behavior, so the no-script and enhanced paths agree.
Show code
# ruff: noqa: E501 - embedded Citry templates remain readable as authored HTML
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class NativeColorForm(Component):
template = """<form><c-CColorPicker label="Profile color" name="profile_color" value="#1570ef" /><button type="reset">Reset</button><button type="submit">Save</button></form>"""
preview = NativeColorForm()
preview # noqa: B018
Keep the field understandable
Provide a concise visible field label and meaningful swatch labels. Readonly keeps the chosen value available while preventing color changes.
Show code
# ruff: noqa: ANN001, ANN201 - public snippets keep focus on component use
import citry_ui
from citry import Component, citry
from citry_ui import CColorSwatch
citry.register_library(citry_ui)
class AccessibleColorPicker(Component):
def template_data(self, _kwargs, _slots):
return {"swatches": [CColorSwatch("#005ea8", "Accessible blue"), CColorSwatch("#00703c", "Accessible green")]}
template = '<c-CColorPicker label="Published theme color" value="#005ea8" c-swatches="swatches" readonly />'
preview = AccessibleColorPicker()
preview # noqa: B018
Alpha, gradients, image sampling, EyeDropper permissions, and wide-gamut color spaces are outside this first solid-color contract.
API reference
Inputs
CColorPicker server inputs
Server inputs are passed in a template through <c-CColorPicker ... /> or in Python through CColorPicker(...).
| Input | Type | Default | Effect |
|---|---|---|---|
label | str | required | Supplies the visible field label. |
value | str | "#7f56d9" | Sets a '#rgb' or '#rrggbb' color normalized to lowercase six-digit HEX. |
id | str | None | generated | Sets the root ID and derived control IDs. |
name | str | None | None | Names the native color form control. |
form | str | None | None | Associates the native input with an external form. |
format | CColorPickerFormat (CColorPickerFormat) | "hex" | Chooses the editable HEX RGB or HSL representation. |
swatches | Sequence[CColorSwatch] | "()" | Adds unique named solid-color shortcuts. |
open | bool | False | Sets initial popup visibility. |
disabled | bool | False | Disables focus mutation and form submission. |
readonly | bool | False | Prevents color mutation while retaining the value. |
size | CColorPickerSize (CColorPickerSize) | "md" | Selects trigger height. |
variant | CColorPickerVariant (CColorPickerVariant) | "outline" | Selects outline soft or plain trigger styling. |
open_label | str | "Open color picker" | Overrides the catalog-backed trigger title. |
area_label | str | "Saturation and brightness" | Overrides the compound slider name. |
hue_label | str | "Hue" | Overrides the hue label. |
format_label | str | "Color format" | Overrides the format label. |
value_label | str | "Color value" | Overrides the text input label. |
invalid_label | str | "Enter a valid color value" | Overrides invalid edit announcements. |
selected_label | str containing '{color}' | "Selected {color}" | Overrides selection announcements. |
class_ | CClassValue | None (CClassValue) | None | Adds root classes. |
style | CStyleValue | None (CStyleValue) | None | Adds root styles. |
attrs | Mapping[str, object] | None | None | Adds copied allowed root attributes. |
CColorPicker client inputs
Client inputs are passed in the browser through the $c-props="{ ... }" attribute on <c-CColorPicker />.
| Input | Type | Omitted behavior | Effect |
|---|---|---|---|
value | string | Uses uncontrolled state. | Controls the canonical HEX value. |
open | boolean | Uses uncontrolled popup state. | Controls popup visibility. |
disabled | boolean | Uses the server value. | Reactively disables the field. |
readonly | boolean | Uses the server value. | Reactively prevents mutation. |
format | CColorPickerFormat (CColorPickerFormat) | Uses the server value. | Controls the editable representation. |
onValueChange | function | No semantic callback runs. | Receives valid color requests. |
onOpenChange | function | No semantic callback runs. | Receives popup visibility requests. |
Slots
-
Events
Component events are callback inputs supplied through $c-props. Native browser events remain available through Alpine @... attributes.
CColorPicker events
| Event | Signature | Trigger and timing | Detail | Controlled and cancellation behavior |
|---|---|---|---|---|
onValueChange | (value: string, detail: CColorPickerValueChangeDetail) => void (CColorPickerValueChangeDetail) | A valid area hue text swatch native or reset request occurs. | {value, previousValue, rgb, hsl, hsv, controlled, source, sourceEvent} (CColorPickerValueChangeDetail) | Commits and dispatches native input and change only while uncontrolled. |
onOpenChange | (open: boolean, detail: CColorPickerOpenChangeDetail) => void (CColorPickerOpenChangeDetail) | The popup requests a visibility change. | {open, reason, sourceEvent} (CColorPickerOpenChangeDetail) | Commits only while uncontrolled. |
Methods
-
CSS
CSS variables to theme the components. Set them on an ancestor or the component itself.
CColorPicker CSS variables
Apply these variables to CColorPicker or one of its ancestors.
| Variable | Type | Purpose | Default |
|---|---|---|---|
--cui-color-picker-width | length | Trigger and popup width. | 20rem |
--cui-color-picker-area-height | length | Saturation and brightness area height. | 12rem |
--cui-color-picker-surface | color | Popup and trigger surface. | Canvas |
--cui-color-picker-border | complete border | Control boundaries. | Adaptive 1px neutral |
--cui-color-picker-radius | length | Popup radius. | 0.75rem |
--cui-color-picker-shadow | shadow | Popup elevation. | Adaptive shadow |
--cui-color-picker-focus | color | Focus and selected-swatch indicator. | Highlight |
Attributes
HTML attributes defined on the components that you can refer to for CSS, inspection, and testing. Read-only.
CColorPicker attributes
| Attribute | Element | Type | Meaning |
|---|---|---|---|
data-open | Root | present | absent | Reflects popup visibility. |
data-disabled | Root | present | absent | Reflects disabled state. |
data-readonly | Root | present | absent | Reflects readonly state. |
data-format | Root | CColorPickerFormat (CColorPickerFormat) | Reflects the editable representation. |
data-selected | Swatch | present | absent | Marks the current swatch. |
Selectors
Selectors for the DOM nodes in the components that you can use for CSS, inspection, and testing.
CColorPicker selectors
| Selector | Element | Purpose |
|---|---|---|
[data-citry-ui-part="color-picker"] | Root | State and root customization destination. |
[data-citry-ui-part="native"] | Native color input | Progressive fallback form and reset owner. |
[data-citry-ui-part="trigger"] | Button | Opens the enhanced picker. |
[data-citry-ui-part="popup"] | Dialog | Enhanced control container. |
[data-citry-ui-part="area"] | Compound slider | Changes saturation and brightness. |
[data-citry-ui-part="hue"] | Label and range | Changes hue. |
[data-citry-ui-part="format"] | Select | Chooses editable representation. |
[data-citry-ui-part="input"] | Text input | Commits a parsed color. |
[data-citry-ui-part="swatches"] | List | Groups named shortcuts. |
[data-citry-ui-part="swatch"] | Button | Requests a named color. |
[data-citry-ui-part="status"] | Polite status | Announces validation and selection. |
Interfaces
Aliases and data shapes referenced above.
Input type aliases
| Interface | Definition |
|---|---|
CClassValue | str | Mapping[str, bool] | Sequence[CClassValue] |
CStyleValue | str | Mapping[str, object] | Sequence[CStyleValue] |
CColorPickerFormat | Literal["hex", "rgb", "hsl"] |
CColorPickerSize | Literal["sm", "md", "lg"] |
CColorPickerVariant | Literal["outline", "soft", "plain"] |
CColorPickerSource | Literal["area", "hue", "text", "swatch", "native", "reset"] |
CColorSwatch | CColorSwatch(value: str, label: str) |
CColorPickerValueChangeDetail
| Field | Type | Default | Meaning |
|---|---|---|---|
value | str | - | Requested canonical HEX value. |
previousValue | str | - | Previous value. |
rgb | dict[str, int] | - | Requested integer RGB channels. |
hsl | dict[str, float] | - | Requested HSL channels. |
hsv | dict[str, float] | - | Requested HSV channels. |
controlled | bool | - | Whether client value owns state. |
source | CColorPickerSource | - | Interaction source. |
sourceEvent | object | - | Native Event. |
CColorPickerOpenChangeDetail
| Field | Type | Default | Meaning |
|---|---|---|---|
open | bool | - | Requested popup state. |
reason | str | - | Trigger outside escape or selection reason. |
sourceEvent | object | - | Native Event. |
Translation keys
Catalog keys used by this family. An explicit component input or slot listed in Override takes precedence over the catalog for that instance.
CColorPicker translation keys
| Key | Purpose | Variables | Override | Browser updates |
|---|---|---|---|---|
citry-ui-color-picker-open | Provides the enhanced trigger title. | none | open_label | Declarative $c-tr attribute binding. |
citry-ui-color-picker-area | Names the compound saturation and brightness slider. | none | area_label | Declarative $c-tr attribute binding. |
citry-ui-color-picker-hue | Labels the hue range. | none | hue_label | Declarative $c-tr text binding. |
citry-ui-color-picker-format | Labels the format select. | none | format_label | Declarative $c-tr text binding. |
citry-ui-color-picker-value | Labels the editable value. | none | value_label | Declarative $c-tr text binding. |
citry-ui-color-picker-invalid | Announces an invalid text edit. | none | invalid_label | Browser-created one-shot i18n.tr(). |
citry-ui-color-picker-selected | Announces an accepted color. | color: str | selected_label with {color} | Browser-created one-shot i18n.tr(). |