Bridge UI

ColorField

Form field that opens a ColorPicker in an overlay (auto by default: menu on desktop, bottom drawer on mobile).

Introduction

ColorField is a complete form control: a label, an input that displays the selected color, a start swatch, and a ColorPicker that opens in an overlay (auto by default: menu on desktop, bottom drawer on mobile). It wraps FormField chrome around a native <input> and an inline ColorPicker, so you get consistent layout, validation styling, and color selection without assembling those pieces yourself.

It uses the semantic palette icon by default at the inline end of the field. The bound value is a serialized color string (hex by default).

Import

import { ColorField } from "@bridge-ui/vue/Components/ColorField";
import { ColorField } from "@bridge-ui/react/Components/ColorField";

Basic usage

Provide a label and placeholder. Bind the value with value/onChange in React or v-model in Vue. For uncontrolled usage with an initial value, use defaultValue in React or default-value in Vue. Clicking the field opens a color picker; selecting a color commits the value. A start swatch previews the selection (showSwatch, default true).

Form props

Standard form attributes are supported through inherited FormField props:

  • required — shows a red asterisk on the label. Pair with the native required attribute when validating with HTML forms.
  • disabled — prevents interaction and applies disabled styling to the field shell and input.
  • readonly — keeps the value visible and focusable but not editable; the picker menu does not open.

The input is read-only by default (picker only). Set editable to unlock typing. Typed text is parsed and committed on blur or Enter.

Use description for helper text below the field. When error is set, the description is hidden and errorMessage is shown instead.

Variants

Control the field shell appearance with the variant prop. Available variants: outline (default), filled, notched, stacked, and underlined.

Sizes

Control the field size with the size prop. Available sizes: 2xs, xs, sm, md (default), lg, xl, and 2xl.

Rounded

Use the rounded prop to control border radius on both the field shell and the nested picker. Overlay menus are unstyled, so the picker shell is the visible radius. Available values: none, xs, sm, md (default), lg, xl, 2xl, 3xl, 4xl, and full.

Output format

Use format to choose how the value is serialized: hex (default), hexa, rgb, rgba, hsl, or hsla. Alpha formats (hexa, rgba, hsla) show the alpha slider automatically. Set alpha to force the slider on or off regardless of format.

Swatches

Pass swatches to show preset colors below the sliders in the nested picker.

Editable

Set editable to unlock the input. Typed text is parsed as hex, rgb(a), or hsl(a) and committed on blur or Enter. Invalid input is discarded and the previous value is restored.

Set showFooter to add Cancel / Apply actions to the nested picker. The selection is a draft until Apply is pressed; Cancel discards it and closes. When unset, showFooter defaults to true for modal / drawer overlays (false for menu).

A custom footer slot replaces Cancel / Apply on the nested picker. Call apply() to commit the draft and close the overlay, or cancel() to discard and close.

ColorPicker

ColorPicker is the inline picker that ColorField opens in an overlay (auto by default: menu on desktop, bottom drawer on mobile). Use it directly when you need an always-visible picker without the FormField shell or menu behavior—for example, in a sidebar or a custom popover.

It supports the same value/onChange, format, alpha, swatches, and showFooter props as ColorField, plus standalone-only props like disabled, readOnly, rounded, and fill (fills the container width; default false). The same footer slot works on standalone ColorPicker: apply() commits (and closes an overlay), cancel() discards.

Picker tokens live on components.ColorPicker (rounded, size).

import { ColorPicker } from "@bridge-ui/vue/Components/ColorPicker";
import { ColorPicker } from "@bridge-ui/react/Components/ColorPicker";

Overlay

Use the overlay prop to choose the picker shell: auto (default), menu, modal, or drawer. auto uses menu on desktop and a bottom drawer on mobile. When unset, showFooter defaults to true for modal / drawer overlays (false for menu). When unset, fill defaults to true for drawer overlays (false for menu / modal). Apply commits and closes; Cancel discards and closes.

Validation

Set error and errorMessage to show invalid styling and an error message below the field. Use required to show a red asterisk on the label.

ColorPicker, TextField, Select

Accessibility

For the field to be accessible, the input must be linked to its label and helper or error text:

  • The label is associated with the input via htmlFor / id, using controlId (auto-generated when omitted).
  • description and errorMessage are linked through aria-describedby on the input.
  • When error is true, the input receives aria-invalid="true".
  • The start swatch is decorative (aria-hidden="true"). The picker menu opens on click or focus and closes on Escape.

Provide a stable controlId when rendering client-only so labels associate correctly on first paint.

Anatomy

ColorField composes FormField around a native <input> and opens a ColorPicker in an overlay (auto by default: menu on desktop, bottom drawer on mobile):

FormField (root)
├── Header — label, optional corner text, required indicator
├── Container — variant shell (outline, filled, …)
│   ├── Swatch — selected color (unless showSwatch is false)
│   ├── Input — serialized value (read-only unless editable)
│   ├── Clear — optional clear control
│   └── End adornment — palette icon (default) or custom endIcon
└── Footer — description (helper text) or error message

Menu (opened on click)
└── ColorPicker — saturation area, hue, optional alpha, swatches, optionally Cancel / Apply

API

Prop Type Default Description
default-value string | null — Initial value for uncontrolled usage (without v-model).
v-model string | null — Two-way binding for the selected color.
Prop Type Default Description
defaultValue string | null — Initial value for uncontrolled usage.
onChange (value: string | null) => void — Called when the color changes.
value string | null — Selected color. Use with onChange for controlled state.

ColorField-specific

Prop Type Default Description
alpha boolean — Shows the alpha slider. Unset: true for hexa / rgba / hsla.
classes ColorFieldClasses — Classes for field / input regions.
clearable boolean true Whether the value can be cleared.
customProps ColorFieldCustomProps — Extra props for internal parts (input, menu, modal, drawer, colorPicker, …).
editable boolean false Unlocks the input. Typed text is parsed on blur or Enter.
fill boolean — Fills the overlay width. Unset: true for drawer, false for menu / modal.
format ColorFormat "hex" Serialized output: hex, hexa, rgb, rgba, hsl, hsla.
overlay FieldOverlayMode "auto" Overlay shell: menu, modal, drawer, or auto.
placeholder string — Native attribute forwarded to the input.
showFooter boolean false (true for modal/drawer when unset) Shows Cancel / Apply on the nested picker.
showSwatch boolean true Shows the selected color at the start of the field.
slots ColorFieldSlots — Named slots (FormField slots + footer).
swatches string[] — Preset colors forwarded to the nested picker.

Events

Event Payload Description
@apply — Emitted when Apply is pressed (showFooter).
@cancel — Emitted when Cancel is pressed (showFooter).
@change string | null Emitted when the color changes.
@clear — Emitted when the value is cleared.
@close — Emitted when the menu closes.
@open — Emitted when the menu opens.
Prop Payload Description
onApply — Called when Apply is pressed (showFooter).
onCancel — Called when Cancel is pressed (showFooter).
onChange (value: string | null) Called when the color changes.
onClear — Called when the value is cleared.
onClose — Called when the menu closes.
onOpen — Called when the menu opens.

Inherited from FormField

Prop Type Default Description
classes ColorFieldClasses — Class overrides for field / input regions.
color FormFieldColor "primary" Color applied to the field control.
controlId string — Associates labels and helper text with the control. Auto-generated when omitted.
corner string — Secondary label text at the inline end of the header row.
customProps ColorFieldCustomProps — Props for each part, plus menu, modal, drawer (forwarded to the overlay shell) and colorPicker (forwarded to the nested ColorPicker).
description string — Helper text below the control (hidden when invalid).
disabled boolean false Whether the control is disabled.
end string — Inline-end text inside the field (suffix).
endIcon IconSource "palette" Icon at the inline end.
error boolean false Applies invalid styling and hides description.
errorIcon IconSource "alert" Icon shown when invalid and showErrorIcon is enabled.
errorMessage string — Error message below the control.
hideErrorMessage boolean false Does not reserve space for error messages.
label string — Primary label text above the control.
readonly boolean false Whether the control is read-only.
required boolean false Shows a red asterisk on the label.
rounded FormFieldRounded "md" Border radius of the field control and the nested picker.
showErrorIcon boolean true Shows an error icon when invalid.
size FormFieldSize "md" Typography and control sizing.
slots ColorFieldSlots — React slots. Vue: #label, #corner, default, #description, #errorMessage, #start, #end, #footer.
start string — Inline-start text inside the field (prefix).
startIcon IconSource — Icon at the inline start.
variant FormFieldVariant "outline" Visual variant of the field shell.