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
from citry import Component
class ControlledColorPicker(Component):
template = """
<section >
<c-CColorPicker
label="Controlled accent"
:value="color"
:open="open"
:onValueChange="(next)=>color=next"
:onOpenChange="(next)=>open=next"
/>
<output v-text="color">#7f56d9</output>
</section>
"""
js = """
$component({
data() {
return {
color:'#7f56d9',open:false
};
},
});
"""
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.
Add root attributes
attrs accepts ordinary native, ARIA, and data attributes for the root. It rejects the attributes Color Picker sets itself (such as role and data-open), Citry runtime attributes, and any Vue directive syntax: names starting with v-, :, ., ^, @, or #. Write Vue bindings and listeners on the component tag in your template instead.
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 popup visibility. A server re-render that changes it opens or closes the popup. A re-render that leaves it unchanged keeps the current state. |
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 native Vue :prop bindings 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 and the close caused by disabling an open popup. |
Slots
-
Events
Component events are callback inputs supplied through native Vue :prop bindings. Native browser events remain available through Vue @... 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, disabling closes an open popup, or a dialog or popover around the picker closes it. | {open, reason, sourceEvent} (CColorPickerOpenChangeDetail) | Commits only while uncontrolled, except that disabling or a closing ancestor closes the popup either way. |
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 selection disabled or ancestor 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(). |