- Components
- Colors
- Color Field
Color Field
A color field allows users to edit a hex color or individual color channel value.
Installation
Install the following dependencies:
Copy and paste the following code into your project.
Update the import paths to match your project setup.
Usage
Use a ColorField to allow users to edit a hex color or individual color channel value.
Options
Label
A visual label can be provided for the ColorField using the label prop or a hidden label using aria-label prop.
Size
Use the size prop to control the size of the ColorField.
The default variant is "md".
Prefix and suffix
To add additional context for the ColorField, use the prefix and suffix props.
Description
A description can be supplied to ColorField via the description prop. The description is always visible unless the isInvalid prop is true and an error message is provided.
Contextual help
A ContextualHelp element may be placed next to the label to provide additional information or help about a ColorField.
Error message
An errorMessage can be supplied to ColorField, which will be displayed when the isInvalid prop is set to true.
Loading
Use the isLoading prop to control the loading state of the ColorField. Use the loaderPosition prop to control the position of the loader.
Disabled
Use the isDisabled prop to disable the ColorField.
ReadOnly
The isReadOnly boolean prop makes the ColorField's text content immutable. Unlike isDisabled, the ColorField remains focusable and the contents can still be copied.
Required
Use the isRequired prop to mark the ColorField as required. Use the necessityIndicator prop to control the visual style of the required state.
Uncontrolled
Use the value and onChange props to control the value of the input.
Controlled
Use the value and onChange props to control the value of the input.
Composition
If you need to customize things further, you can drop down to the composition level.
API Reference
Prop | Type | Default | Description |
---|---|---|---|
channel | 'hue' | 'saturation' | 'brightness' | 'lightness' | 'red' | 'green' | 'blue' | 'alpha' | - | The color channel that this field edits. If not provided, the color is edited as a hex value. |
colorSpace | 'rgb' | 'hsl' | 'hsb' | - | The color space that the color field operates in if a channel prop is provided. If no channel is provided, the color field always displays the color as an RGB hex value. |
isWheelDisabled | boolean | - | Enables or disables changing the value with scroll. |
value | T | - | The current value (controlled). |
defaultValue | T | - | The default value (uncontrolled). |
isDisabled | boolean | - | Whether the input is disabled. |
isReadOnly | boolean | - | Whether the input can be selected but not changed by the user. |
isRequired | boolean | - | Whether user input is required on the input before form submission. |
isInvalid | boolean | - | Whether the input value is invalid. |
validate | (value: Color | null) => ValidationError | true | null | undefined | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead. |
autoFocus | boolean | - | Whether the element should receive focus on render. |
name | string | - | The name of the input element, used when submitting an HTML form. |
validationBehavior | 'native' | 'aria' | 'native' | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
children | ReactNode | (values: ColorFieldRenderProps & {defaultChildren: ReactNode | undefined}) => ReactNode | - | The children of the component. A function may be provided to alter the children based on component state. |
className | string | - | The CSS className for the element. |
style | CSSProperties | (values: ColorFieldRenderProps & {defaultStyle: CSSProperties}) => CSSProperties | - | The inline style for the element. A function may be provided to compute the style based on component state. |
Event | Type | Description |
---|---|---|
onChange | (isSelected: boolean) => void | Handler that is called when the Switch's selection state changes. |
onFocus | (e: FocusEvent<Target>) => void | Handler that is called when the Switch receives focus. |
onBlur | (e: FocusEvent<Target>) => void | Handler that is called when the Switch loses focus. |
onFocusChange | (isFocused: boolean) => void | Handler that is called when the Switch's focus status changes. |
onKeyDown | (e: KeyboardEvent) => void | Handler that is called when a key is pressed. |
onKeyUp | (e: KeyboardEvent) => void | Handler that is called when a key is released. |
onCopy | ClipboardEventHandler<HTMLInputElement> | Handler that is called when the user copies text. |
onCut | ClipboardEventHandler<HTMLInputElement> | Handler that is called when the user cuts text. |
onPaste | ClipboardEventHandler<HTMLInputElement> | Handler that is called when the user pastes text. |
onCompositionStart | CompositionEventHandler<HTMLInputElement> | Handler that is called when a text composition system starts a new text composition session. |
onCompositionEnd | CompositionEventHandler<HTMLInputElement> | Handler that is called when a text composition system completes or cancels the current text composition session. |
onCompositionUpdate | CompositionEventHandler<HTMLInputElement> | Handler that is called when a new character is received in the current text composition session. |
onSelect | ReactEventHandler<HTMLInputElement> | Handler that is called when text in the input is selected. |
onBeforeInput | FormEventHandler<HTMLInputElement> | Handler that is called when the input value is about to be modified. |
onInput | FormEventHandler<HTMLInputElement> | Handler that is called when the input value is modified. |
Data attribute | Description |
---|---|
[data-disabled] | Whether the color field is disabled. |
[data-invalid] | Whether the color field is invalid. |
[data-channel="hex | hue | saturation | ..."] | The color channel that this field edits, or "hex" if no channel prop is set. |