CynosureComponents / Controls
ColorField
A colour input that takes any CSS colour as text, or lets people pick one from a saturation area, a hue slider, an opacity slider and, where the browser allows, the screen itself.
When to useLink to "When to use"
- A colour setting: an accent, a highlight, a fill.
- Inspecting and editing CSS colours (Aperture), where people paste values in many syntaxes.
Use something else when: the choice is one of a few named colours: a SegmentedControl or RadioGroup of swatches.
UsageLink to "Usage"
import { ColorField } from "@arshad-shah/cynosure";
<ColorField label="Accent" value={accent} onChange={setAccent} />
<ColorField label="Overlay" alpha format="rgb" name="overlay" />The text accepts hex, rgb(), hsl(), oklch() and colour names, read on Enter or when leaving the field. Values come back in format.
Invalid textLink to "Invalid text"
Text that is not a colour is kept so it can be fixed, the field is marked invalid, and labels.invalid explains what is expected. Nothing changes until it is a colour.
OpacityLink to "Opacity"
With alpha, an opacity slider joins the picker and the value keeps opacity (#0000ff80, rgb(0 0 255 / 0.5)). Without it, opacity in typed text is dropped.
SwatchesLink to "Swatches"
swatches adds a group of colours to the picker: brand colours, presets, or recent colours you keep. Picking one sets the field, written in its format.
PropsLink to "Props"
| Prop | What it does | Type | Default |
|---|---|---|---|
labelRequired | The field's label. | ReactNode | |
labelHidden | Visually hide the label (it still names the control). Prefer visible labels. | boolean | |
description | Help text shown below the control and read with it. | ReactNode | |
error | Your own error; it replaces the field's own messages. | ReactNode | |
value | Any CSS colour; reported back in format. | string | |
defaultValue | The starting colour when uncontrolled, any CSS colour. Default "black". | string | "black" |
onChange | Called when the colour changes (typed, picked or chosen from a swatch), with the colour written in format. | ((value: string) => void) | |
format | How values are written: six-digit hex, rgb(51 102 255) or oklch(55% 0.21 264). | "hex" | "rgb" | "oklch" | |
alpha | Let people set opacity (adds an opacity slider and alpha to the value). | boolean | |
swatches | Colours offered in the picker: brand colours, presets, or recent colours you keep. | (string | ColorSwatch)[] | |
name | Name the colour is submitted under in a form, written in format. | string | |
required | Marks the field as required and makes its input required in a form. | boolean | |
disabled | Turns off the input and the picker; the colour is not submitted with a form. | boolean | |
size | Size of the field. Default "md". | Size | "md" |
labels | Replace the built-in English text: the picker's controls and the error for text that is not a colour. | Partial<ColorFieldLabels> | |
className | Added to the root element, for layout. | string | |
style | Layout only. | CSSProperties | |
layout | stack puts the label above the control and the description and error below it. split puts the label and description at the start and the control at the end of one row (a settings row); when the field is too narrow for both, the control moves under the text. Default "stack". | "stack" | "split" | "stack" |
width | Width of the control, so the controls of a column of fields line up: "sm", "md" and "lg" are the --cy-field-control-width-* tokens (never wider than the field), "full" is the whole field. Default: the control's own width (the whole field in the stacked layout for TextField and the other fields). | FieldWidth |
Generated from the type definitions in @arshad-shah/cynosure 0.5.0.
Behaviour and accessibilityLink to "Behaviour and accessibility"
| Input | Result |
|---|---|
| Typing, then Enter or leaving | Reads the colour |
| Swatch button | Opens the picker (a dialog popover) |
| Area: Left arrow / Right arrow | Saturation down / up (Shift: by ten) |
| Area: Up arrow / Down arrow | Brightness up / down |
| Hue and opacity sliders | Standard Slider keys |
| Escape | Closes the picker; focus returns to the swatch |
- Roles: the input is a labelled text field; the area is a
sliderwhose value text names both saturation and brightness; hue and opacity are Sliders. - Swatch: drawn over a checkerboard so opacity shows, with an outline that stays visible on any colour (at least 3:1 against the field).
- Eyedropper: shown only where the browser offers the EyeDropper API; cancelling it changes nothing.
- Forms: with
name, the formatted value is submitted; reset restores the default.
TouchLink to "Touch"
The swatch button keeps a 44px hit area on coarse pointers, and dragging on the area never scrolls the page.
ThemingLink to "Theming"
Tokens: --cy-color-field-swatch-size, --cy-color-field-area-height and --cy-color-field-picker-width. The field uses the TextField tokens.
RelatedLink to "Related"
These examples run Cynosure 0.5.0 (commit 50ce30b), the version on npm.