Color Input
Color Input lets a user specify a color by entering a hexadecimal value into a text field.
Color Input Anatomy
- Label: Title of the input. Label position could be set to the top or left of the Color Input.
- Active Color Swatch: Square container that shows what the color looks like. Checkmark is optional and could be set on when a valid hex value is entered in the text input.
- Text Input: Placeholder text of the Color Input is “#FFFFFF”. Placeholder text is replaced when the user enters a different hex value.
Color Input Usage Guidance
- Color Input lets a user apply a specific color to an element.
- The user should enter a value in hexadecimal format (6 digits).
When to Use
- Use Color Input to apply a custom color to an element such as text or background color using hexadecimal numbers. This is commonly used for theming.
Color Input Examples
Basic Example
Color Input should be used in tandem with Form Field to meet accessibility standards.
Disabled
Set the disabled
prop of the Color Input to prevent users from interacting with it.
Checked
Set the showCheck
prop of the Color Input to display a check icon in the swatch.
Ref Forwarding
Color Input supports ref forwarding. It will
forward ref
to its underlying <input type="text">
element.
Valid Color Change Callback
Set the onValidColorChange
prop of the Color Input to set a callback for when a valid hex color is
provided.
The color passed to the callback will be prefixed with a hash and expanded if necessary. For
example, 03F
would be converted to #0033FF
.
Last valid color:
Grow
Set the grow
prop of the wrapping Form Field to true
to configure the Color Input to expand to
the width of its container.
The grow
prop may also be applied directly to the Color Input if Form Field is not being used.
Label Position
Set the labelPosition
prop of the wrapping Form Field to designate the position of the label
relative to the Color Input. labelPosition
accepts the following values:
FormField.LabelPosition.Top
(Default)FormField.LabelPosition.Left
Required
Set the required
prop of the wrapping Form Field to true
to indicate that the field is required.
Labels for required fields are suffixed by a red asterisk.
Error States
Set the error
prop of the wrapping Form Field to FormField.ErrorType.Alert
or
FormField.ErrorType.Error
to set the Color Input to the Alert or Error state, respectively. You
will also need to set the hintId
and hintText
props on the Form Field to meet accessibility
standards.
Alert
Alert: Please select a background color.
Error
Error: Please select a background color.
Component API
ColorInput
Props
Props extend from input. Changing the as
prop will change the element interface.
Name | Type | Description | Default |
---|---|---|---|
value | string | The value of the ColorInput. | '' |
showCheck | boolean | If true, show a checkmark in the swatch tile when a custom hex color is entered in the ColorInput. | false |
placeholder | string | The placeholder text of the ColorInput. | 'FFFFFF' |
error |
| The type of error associated with the ColorInput (if applicable). | |
disabled | boolean | If true, set the ColorInput to the disabled state. | false |
onChange | (event: <>) => void | The function called when the ColorInput state changes. | |
onValidColorChange | (color: string) => void | The function called when a valid hex value is entered in the ColorInput. The | |
theme |
| ||
width | number | string | The width of the TextInput. | |
grow | boolean | True if the component should grow to its container's width. False otherwise. | |
children | React.ReactNode | ||
as | React.ElementType | Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care. | input |
ref | React.Ref | Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If |
Specifications
Given | When | Then |
---|---|---|
given the 'Basic' story is rendered |
| |
given the 'Basic' story is rendered |
|
|
given the 'Basic' story is rendered |
|
|
given the 'Basic' story is rendered |
|
|
given the 'Basic' story is rendered |
|
|
given the 'Basic' story is rendered |
|
|
given the 'Alert' story is rendered |
| |
given the 'Alert' story is rendered |
|
|
given the 'Alert' story is rendered |
|
|
given the 'Alert' story is rendered |
|
|
given the 'Alert' story is rendered |
|
|
given the 'Alert' story is rendered |
|
|
given the 'Error' story is rendered |
| |
given the 'Error' story is rendered |
|
|
given the 'Error' story is rendered |
|
|
given the 'Error' story is rendered |
|
|
given the 'Error' story is rendered |
|
|
given the 'Error' story is rendered |
|
|
given the 'Checked' story is rendered |
| |
given the 'Checked' story is rendered |
|
|
given the 'Checked' story is rendered |
|
|
given the 'Checked' story is rendered |
|
|
given the 'Checked' story is rendered |
|
|
given the 'Checked' story is rendered |
|
|
given the 'Grow' story is rendered |
| |
given the 'Grow' story is rendered |
|
|
given the 'Grow' story is rendered |
|
|
given the 'Grow' story is rendered |
|
|
given the 'Grow' story is rendered |
|
|
given the 'Grow' story is rendered |
|
|
given the `Disabled` story is rendered |
| |
given the `Disabled` story is rendered |
|
Color Preview Anatomy
- Label: Title of the input. Label position could be set to the top or left of the Color Preview.
- Active Color Swatch: Square container that shows what the color looks like.
- Value: 6 digit hexadecimal that corresponds to the active color swatch.
Color Preview Usage Guidance
- Color Preview is the read-only version of a Color Input
- It lets a user see what the color looks like in addition to displaying the hex value.
When to Use
- When the color value of an element needs to be displayed, but should not be editable.
Color Preview Examples
Basic Example
Ref Forwarding
Color Preview supports ref forwarding. It will
forward ref
to its underlying <input type="text">
element.
Width of Color Preview:
Label Position
If Form Field is being used, set its labelPosition
prop to designate the position of the label
relative to the Color Preview. labelPosition
accepts the following values:
FormField.LabelPosition.Top
(Default)FormField.LabelPosition.Left
Component API
ColorPreview
Props
Props extend from input. Changing the as
prop will change the element interface.
Name | Type | Description | Default |
---|---|---|---|
value | string | The value of the ColorPreview. | |
id | string | The HTML | |
error |
| The type of error associated with the TextInput (if applicable). | |
width | number | string | The width of the TextInput. | |
theme |
| ||
grow | boolean | True if the component should grow to its container's width. False otherwise. | |
children | React.ReactNode | ||
as | React.ElementType | Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care. | input |
ref | React.Ref | Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If |
Specifications
Given | When | Then |
---|---|---|
given the 'Basic' story is rendered |
|
Accessibility Guidelines
- Color Input and Color Preview must have visual labels that clearly indicate the purpose of the input.
- When possible, error and alert states should provide information on how to fix issues or provide hints on how to fix formatting.
- Do not use color alone to differentiate between errors and alerts. Although color is a great visual indicator for users without disabilities, “Error” or “Alert” text should always be used to distinguish errors and alerts on a page. Use icons as supplementary visual indicators for different message states.
Can't Find What You Need?
Check out our FAQ section which may help you find the information you're looking for.
FAQ Section