Color Picker

Overview

ColorPicker owns a color as an HSVA model and projects it to Value through Format (hex / rgb / rgba / hsl / hsla). The Area, HueSlider and AlphaSlider each drive one channel; the Field commits a typed hex/rgb/hsl string and the Swatches apply a preset; every surface writes back to the same model. It can be controlled (@bind-Value) or uncontrolled (DefaultValue), and mirrors the projected string into native form submission via a hidden input when Name is set.

Anatomy

@using Navius.Primitives.Components.ColorPicker

<NaviusColorPicker>
    <NaviusColorPickerArea />
    <NaviusColorPickerHueSlider />
    <NaviusColorPickerAlphaSlider />
    <NaviusColorPickerSwatch />
    <NaviusColorPickerField />
    <NaviusColorPickerSwatches>
        <NaviusColorPickerSwatchItem />
    </NaviusColorPickerSwatches>
</NaviusColorPicker>

Root

Owns the HSVA color and projects it to Value. Cascades the ColorPicker context. Renders a div.

Prop	Type	Default	Description
Value	string?	-	Controlled color string. Pair with ValueChanged (@bind-Value).
ValueChanged	EventCallback<string>	-	Fires when the controlled Value should change.
DefaultValue	string?	-	Uncontrolled initial color string.
Format	string	"hex"	Output format: hex, rgb, rgba, hsl, hsla.
AlphaEnabled	bool	false	Exposes an alpha channel: an AlphaSlider and alpha in the projected string.
Disabled	bool	false	Disables every part.
ReadOnly	bool	false	Prevents value changes while keeping the parts focusable.
Name	string?	-	Optional form field name; renders a hidden input mirroring the projected string for native submission.
ChildContent	RenderFragment?	-	The color picker’s parts.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

Area

The 2D saturation/value canvas: a role="group" holding a visible saturation thumb and a visually-hidden brightness thumb, each its own role="slider". Renders a div.

Prop	Type	Default	Description
AriaLabel	string?	"Color"	Accessible name for the group.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

HueSlider

The horizontal rainbow track with a role="slider" thumb. Renders a div.

Prop	Type	Default	Description
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

AlphaSlider

The optional opacity track (transparent to opaque over a checkerboard), meaningful only with AlphaEnabled. Renders a div.

Prop	Type	Default	Description
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

Swatch

A non-interactive preview of the current color; the color string is its accessible name. Renders a div with role="img".

Prop	Type	Default	Description
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

Field

A text field that commits a typed hex/rgb/hsl string on change; a value that fails to parse flips data-invalid and aria-invalid without disturbing the color. Renders an input.

Prop	Type	Default	Description
AriaLabel	string?	"Hex color"	Accessible name for the field.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered input.

Swatches

A preset grid (role="listbox"); auto-renders SwatchItems from Colors, or takes explicit children. Renders a div.

Prop	Type	Default	Description
AriaLabel	string?	"Swatches"	Accessible name for the listbox.
Colors	IReadOnlyList<string>?	-	Preset color strings to auto-render as SwatchItem options.
ChildContent	RenderFragment?	-	Explicit SwatchItem children, used instead of Colors.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

SwatchItem

One preset option (role="option") inside a Swatches listbox; click, Space or Enter applies it. Renders a button.

Prop	Type	Default	Description
Value	string	""	The preset color string, also its accessible name.
ChildContent	RenderFragment?	-	Item content.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered button.

Data attributes

Part	Attribute	Description
Root	data-navius-color-picker	Present on the root.
Root	data-disabled	Present when disabled.
Area	data-navius-color-picker-area	Present on the canvas group.
Area	data-navius-color-picker-area-thumb	The visible saturation (x) thumb.
Area	data-navius-color-picker-area-thumb-y	The visually-hidden brightness (y) slider.
Area	data-channel	"saturation" | "brightness".
Area	data-dragging	Present on a thumb while dragging.
Area	data-disabled	Present when disabled.
HueSlider	data-navius-color-picker-hue	Present on the hue track.
HueSlider	data-navius-color-picker-hue-thumb	The hue slider thumb.
HueSlider	data-orientation	"horizontal".
HueSlider	data-dragging	Present on the thumb while dragging.
AlphaSlider	data-navius-color-picker-alpha	Present on the alpha track.
AlphaSlider	data-navius-color-picker-alpha-thumb	The alpha slider thumb.
AlphaSlider	data-orientation	"horizontal".
AlphaSlider	data-dragging	Present on the thumb while dragging.
Field	data-navius-color-picker-field	Present on the input.
Field	data-invalid	Present when the typed value did not parse.
Swatches	data-navius-color-picker-swatches	Present on the listbox.
SwatchItem	data-navius-color-picker-swatch-item	Present on the option button.
SwatchItem	data-selected	Present when it matches the current color.
SwatchItem	data-disabled	Present when disabled.

Keyboard interactions

Key	Behavior
Arrow keys (Area)	Left/Right adjust saturation, Up/Down adjust brightness (Shift takes a larger step).
Home / End (Area)	Jumps saturation to its extremes.
Arrow keys (Hue / Alpha)	Decrement / increment the channel by 1 (1% for alpha); Shift or Page steps by 10.
Home / End (Hue / Alpha)	Jumps the channel to its extremes.
Arrow keys (Swatches)	Moves focus among the preset options.
Home / End (Swatches)	Moves focus to the first / last preset option.
Space / Enter (Swatches)	Applies the focused preset.

ARIA mechanism

The Area wires role="group" around two role="slider" thumbs (saturation and brightness), each exposing its own aria-valuenow and a shared aria-valuetext announcing the resulting color. The HueSlider and AlphaSlider are single role="slider" tracks with the same aria-valuetext mechanism. The Field wires aria-invalid when a typed value fails to parse. The Swatches wire role="listbox" with roving tabindex; each SwatchItem wires role="option" and aria-selected, with its color string as the accessible name. This mechanism is covered by the Playwright browser test suite and gated by axe-core in CI.