Color Field
Enter a color value as text.
1use herogpui::components::color_picker::ColorField;Usage
1use herogpui::prelude::ColorField;
2
3ColorField::new("color-field", value)
4 .state(self.demo_text("cf-usage", "#0085F5", cx))
5 // v3's Usage is uncontrolled: `defaultValue="#0085F5"`.
6 .default_value(value)
7 .label("Color")Live HeroGPUI compiled to WebAssembly. Select any example without loading another WASM instance.
Anatomy
Rust types
ColorFieldColorSwatch
Color Field is assembled from these builders. The API reference lists each one.
Customization
Appearance builders and theme tokens Color Field uses.
Styling
| Style | Description |
|---|---|
flex_col + gap(4) | Four-pixel field-part spacing matches. |
Input validity branch | Resolved error content replaces the description row rather than drawing both. |
full_width(bool) + root/group w_full | Both the wrapper and inner group stretch, including in a non-stretching flex parent. |
Input + FIELD_HEIGHT/FIELD_TEXT + apply_field_chrome | Height, alignment, field radius/fill, zero border, 14px type, clipping, and primary shadow match. |
apply_field_chrome(focused) | Focused input draws the shared two-pixel focus ring. |
apply_field_chrome(invalid) | Danger outline/ring matches; keeps the variant fill rather than switching to the field-focus fill. |
Input::is_disabled | Disabled opacity and listener suppression match. |
Input | State-backed Input supplies the cursor, horizontal inset, transparent fill, and unified 36px/14px field metrics. |
Input start_content(ColorSwatch) | The fixed 16px swatch starts at the 12px field inset; text follows after the eight-pixel prefix gap. |
suffix + Input::end_content | Editable and display suffix content stays at the trailing 12px inset and uses a 20px line height. |
FieldVariant::Secondary | Resting fill and shadow match; the absent group hover leaves the hover token undrawn. |
API reference
Builders
| Builder | Type | Default | Description |
|---|---|---|---|
content( | AnyElement | | — | Replacement content receives disabled, invalid, read-only, required, focused, focus-within, and focus-visible state. |
full_width( | bool | false | Stretches the root and input group in editable and display modes. |
new( | id, | — | Stable GPUI element identity is required by the constructor. |
new( | id, | — | Controlled concrete colors wait for owner acceptance; cannot represent a controlled null value. |
default_value( | PickerColor | — | Seeds picker-owned concrete color state once; a null seed is unavailable. |
on_change( | Fn( | — | Reports a parsed color or None while text is incomplete or invalid. |
color_space( | ColorSpace | — | Selects the channel interpretation when channel is present. |
channel( | ColorChannel | — | Switches from hexadecimal editing to one numeric channel. |
is_required( | bool | false | Marks the label and form field required, but the concrete-only value model cannot express v3's empty null value. |
is_invalid( | bool | — | Forces invalid chrome and render state. |
validate( | Fn( | — | Custom validation contributes to field chrome, form validity, error text, and render state. |
validation_behavior( | ValidationBehavior | ValidationBehavior:: | Native blocks submission; Allow exposes invalid state without blocking. |
is_disabled( | bool | false | Removes editing, focus, wheel changes, and successful form submission. |
is_read_only( | bool | false | Keeps the editable input focusable while preventing changes. |
is_wheel_disabled( | bool | false | Suppresses focused wheel stepping for channel fields. |
name( | text) + form_field( | — | Registers the current hex text or channel number for FormData. |
auto_focus( | bool | false | Focuses the editable input on its first render. |
variant( | FieldVariant | FieldVariant:: | Selects field or default fill and primary shadow. |
placeholder( | text | — | Shows caller text, or the resolved current color when omitted. |
built-in ColorSwatch | AnyElement | — | Always renders the current ColorSwatch and cannot replace the prefix independently. |
suffix( | AnyElement | — | Caller content remains present in editable and display compositions. |
Parts
| Part | Description |
|---|---|
ColorField | Value, validation, form, and complete render-state owner. |
ColorField | Optional string label with required, disabled, and invalid state; composes field::Label. |
ColorField | Field chrome drawn by ColorField surrounding prefix, input, and suffix; the input is a composed Input. |
ColorSwatch | Fixed current-color swatch; arbitrary replacement is unavailable. |
ColorField | State-backed text input with parsing, channel keys, wheel editing, and focus; backed by a composed input::InputState. |
ColorField | Caller-provided trailing content in placeholder color. |
ColorField | Optional helper text replaced by resolved error content when invalid; composes field::Description. |
ColorField | Resolved controlled, server, or validator message handed to the composed Input's error_message; arbitrary child composition is unavailable. |
States
| Builder | State | Description |
|---|---|---|
validation::resolve + Input | Invalid | Hides description, shows the resolved message, draws danger chrome, blocks native forms, and reaches render state. |
is_required | Required | Marks the label and reaches render state; concrete-only color state cannot represent v3's empty null value. |
is_disabled | Disabled | Dims the group, removes input and wheel behavior, omits FormData, and reaches render state. |
is_read_only | Read only | Keeps the editable input focusable but blocks mutations and reaches render state. |
ColorFieldRenderState | Focused | Reports focus on the state-backed input. |
focus_handle.contains_focused | Focus within | Focus anywhere in the composed field drives focused chrome and render state. |
focus_visible | Focus visible | Keyboard-origin focus reaches the render function and the shared field ring. |