Color Field
Overview
An input for editing either a full color string or a single channel, with support for hex, rgb, hsl, and oklch output. SColorField combines the Aria ColorFieldRoot/ColorFieldInput primitives with the colorFieldVariants style recipe (2 slots, 6 sizes).
Use a color field for typed color entry or for editing a single channel numerically inside a color picker (paired with color-area/color-slider).
Usage
Features
- 🧩 Aria/styled split —
ColorFieldCompactcomposes the root + input;SColorFieldonly injects styles and forwards props/events - 🎨 Formats —
hex/rgb/hsl/oklchoutput viaformat;colorSpace+channelfor single-channel editing - ⌨️ Keyboard — ArrowUp/Down, PageUp/Down, Home/End increment/decrement the focused channel (with
step) - 🖱️ Wheel — scroll adjusts the channel unless
disableWheelChange - 🏷️ Placeholder/disabled/readonly —
placeholder,disabled,readonly - 📝 Form field — a hidden input via
namefor native form submission - 📐 6 sizes — xs–2xl
size; per-slotuioverrides
Component family
SColorField(styled) — the entry wrapper;colorFieldVariantsrecipe with dynamic slot forwardingColorFieldRoot(Aria) — the state owner;modelValue/color,format/colorSpace/channel, keyboard/wheel increment helpersColorFieldInput(Aria) — the text input bound to the color/channelColorFieldCompact(Aria) — the aggregated composite; composes root + input
Demo
Basic
100%
#0ea5e9
API
Aria Layer
4ColorField
18 Props2 Emits
Props
| Prop | Type | Default | Description |
|---|---|---|---|
class | ClassValue | — | Additional class names applied to the root element. |
size | ThemeSize | — | Visual size of the component. |
ui | Partial<ColorFieldUi> | — | Per-slot class overrides for the component. |
inputProps | ColorFieldInputProps | — | Properties forwarded to the input element. |
modelValue | import("@soybeanjs/colord").AnyColor | — | Current model value. |
defaultValue | import("@soybeanjs/colord").AnyColor | — | Default value. |
colorSpace | ColorSpace | — | Color space. |
channel | ColorChannel | — | Channel. |
format | ColorFormat | — | Format. |
placeholder | string | — | Placeholder. |
disabled | boolean | — | Whether the component is disabled. |
readonly | boolean | — | Whether the component is readonly. |
disableWheelChange | boolean | — | Whether to disable wheel change. |
step | number | — | Step. |
name | string | — | The name of the field. Submitted with its owning form as part of a name/value pair. |
required | boolean | — | When `true`, indicates that the user must set the value before the owning form can be submitted. |
asChild | boolean | — | Change the default rendered element for the one passed as a child, merging their props and behavior. |
as | AsTag | Component | 'div' | The element or component this component should render as. Can be overwrite by `asChild` |
Emits
| Emit Name | Parameters | Description |
|---|---|---|
update:modelValue | string | Emitted when the model value changes. |
update:color | NormalizedColor | Emitted when the color value changes. |
ColorFieldCompact
15 Props2 Emits
Props
| Prop | Type | Default | Description |
|---|---|---|---|
inputProps | ColorFieldInputProps | — | Properties forwarded to the input element. |
modelValue | import("@soybeanjs/colord").AnyColor | — | Current model value. |
defaultValue | import("@soybeanjs/colord").AnyColor | — | Default value. |
colorSpace | ColorSpace | — | Color space. |
channel | ColorChannel | — | Channel. |
format | ColorFormat | — | Format. |
placeholder | string | — | Placeholder. |
disabled | boolean | — | Whether the component is disabled. |
readonly | boolean | — | Whether the component is readonly. |
disableWheelChange | boolean | — | Whether to disable wheel change. |
step | number | — | Step. |
name | string | — | The name of the field. Submitted with its owning form as part of a name/value pair. |
required | boolean | — | When `true`, indicates that the user must set the value before the owning form can be submitted. |
asChild | boolean | — | Change the default rendered element for the one passed as a child, merging their props and behavior. |
as | AsTag | Component | 'div' | The element or component this component should render as. Can be overwrite by `asChild` |
Emits
| Emit Name | Parameters | Description |
|---|---|---|
update:modelValue | string | Emitted when the model value changes. |
update:color | NormalizedColor | Emitted when the color value changes. |
ColorFieldInput
ColorFieldRoot
14 Props2 Emits
Props
| Prop | Type | Default | Description |
|---|---|---|---|
modelValue | import("@soybeanjs/colord").AnyColor | — | Current model value. |
defaultValue | import("@soybeanjs/colord").AnyColor | — | Default value. |
colorSpace | ColorSpace | — | Color space. |
channel | ColorChannel | — | Channel. |
format | ColorFormat | — | Format. |
placeholder | string | — | Placeholder. |
disabled | boolean | — | Whether the component is disabled. |
readonly | boolean | — | Whether the component is readonly. |
disableWheelChange | boolean | — | Whether to disable wheel change. |
step | number | — | Step. |
name | string | — | The name of the field. Submitted with its owning form as part of a name/value pair. |
required | boolean | — | When `true`, indicates that the user must set the value before the owning form can be submitted. |
asChild | boolean | — | Change the default rendered element for the one passed as a child, merging their props and behavior. |
as | AsTag | Component | 'div' | The element or component this component should render as. Can be overwrite by `asChild` |
Emits
| Emit Name | Parameters | Description |
|---|---|---|
update:modelValue | string | Emitted when the model value changes. |
update:color | NormalizedColor | Emitted when the color value changes. |
Notes
Architecture and benchmark differences
ColorFieldCompact owns the root/input composition while every primitive stays style-free and only the UI wrapper injects the colorFieldVariants classes. This mirrors radix-ui-color/shadcn-ui headless split. Ant Design, Element Plus, Mantine and Naive UI ship a single color-picker with a hex input; VeanUI exposes a standalone color field with full format/channel control, keyboard/wheel editing and a native form input.
| Capability | VeanUI | shadcn/ui | Ant Design | Element Plus | Mantine | Naive UI |
|---|---|---|---|---|---|---|
| Aria/styled split | ✅ | ✅ | — | — | — | — |
| Multiple formats | ✅ | ✅ | ✅ | ✅ | ✅ | — |
| Single-channel edit | ✅ | ✅ | — | — | — | — |
| Keyboard + wheel | ✅ | ✅ | — | — | — | — |
| Native form input | ✅ | ✅ | — | — | — | — |
| Sizes (6) | ✅ | — | — | — | — | — |
— = unsupported or a different interaction model.
Cautions
modelValueaccepts a color string orColorValue;formatcontrols the emitted string format.- To edit a single channel, set
channelwith a matchingcolorSpace(e.g.lightnessinhsl); otherwise the full string is edited. - Keyboard (Arrow/Page/Home/End) and wheel change the focused channel by
step(default); setdisableWheelChangeto suppress wheel edits. - Provide
nameto submit the color as a hidden form field. - Use with
color-area/color-sliderinside acolor-pickerfor a complete editor.
Roadmap
N/A — color-field is feature-complete for the current parity set.
FAQ
How do I use a color field?
Bind model-value and choose a format:
<SColorField v-model:model-value="color" format="hex" />How do I edit a single channel?
Set channel with a matching color-space:
<SColorField v-model:model-value="color" channel="lightness" color-space="hsl" format="hsl" />How do I disable wheel editing?
Set disable-wheel-change:
<SColorField v-model:model-value="color" format="hex" disable-wheel-change />