Color Input

Color Input lets a user specify a color by entering a hexadecimal value into a text field.

GitHubStorybook
yarn add @workday/canvas-kit-react
Sources
GitHubStorybook
Install
yarn add @workday/canvas-kit-react

Color Input Anatomy

Image of a Color Input in its default state.

  1. Label: Title of the input. Label position could be set to the top or left of the Color Input.
  2. 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.
  3. 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.

Color Input Props

Undocumented props are spread to the underlying <input type="text"> element.

NameTypeDefaultDescription
valuestring | undefined''The value of the ColorInput.
showCheckboolean | undefinedfalseIf true, show a checkmark in the swatch tile when a custom hex color is entered in the ColorInput.
placeholderstring | undefinedFFFFFFThe placeholder text of the ColorInput.
errorErrorType | undefinedThe type of error associated with the ColorInput (if applicable).
disabledboolean | undefinedfalseIf true, set the ColorInput to the disabled state.
onChange((event: ChangeEvent<HTMLInputElement>) => void) | undefinedThe function called when the ColorInput state changes.
onValidColorChange((color: string) => void) | undefinedThe function called when a valid hex value is entered in the ColorInput. The `color` argument passed to the callback function is prefixed with a hash and expanded if necessary (e.g., `03F` is converted to `#0033FF`).
themeEmotionCanvasTheme | undefined
widthstring | number | undefinedThe width of the TextInput.
growboolean | undefinedTrue if the component should grow to its container's width. False otherwise.
refReact.Ref<any>Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If `as` is set to an element, it will be that element. If `as` is a component, the reference will be to that component (or element if the component uses `React.forwardRef`).
as"symbol" | "object" | "small" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "button" | ... 156 more ... | React.ComponentType<any>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 `React.forwardRef` and spread extra props to a root element.

Color Input Specifications

GivenWhenThen
given the 'Basic' story is rendered
    • it should not have any axe errors
    given the 'Basic' story is rendered
    • clicked
    • it should be focused
    given the 'Basic' story is rendered
    • provided a 6 digit hex value
    • it should reflect the hex value
    given the 'Basic' story is rendered
    • provided a 3 digit hex
    • it should reflect the hex value
    given the 'Basic' story is rendered
    • provided a hex with a hash
    • it should strip the hash from the hex value
    given the 'Basic' story is rendered
    • provided a hex with more than 6 characters
    • it should truncate the value to a length of 6
    given the 'Alert' story is rendered
      • it should not have any axe errors
      given the 'Alert' story is rendered
      • clicked
      • it should be focused
      given the 'Alert' story is rendered
      • provided a 6 digit hex value
      • it should reflect the hex value
      given the 'Alert' story is rendered
      • provided a 3 digit hex
      • it should reflect the hex value
      given the 'Alert' story is rendered
      • provided a hex with a hash
      • it should strip the hash from the hex value
      given the 'Alert' story is rendered
      • provided a hex with more than 6 characters
      • it should truncate the value to a length of 6
      given the 'Error' story is rendered
        • it should not have any axe errors
        given the 'Error' story is rendered
        • clicked
        • it should be focused
        given the 'Error' story is rendered
        • provided a 6 digit hex value
        • it should reflect the hex value
        given the 'Error' story is rendered
        • provided a 3 digit hex
        • it should reflect the hex value
        given the 'Error' story is rendered
        • provided a hex with a hash
        • it should strip the hash from the hex value
        given the 'Error' story is rendered
        • provided a hex with more than 6 characters
        • it should truncate the value to a length of 6
        given the 'Checked' story is rendered
          • it should not have any axe errors
          given the 'Checked' story is rendered
          • clicked
          • it should be focused
          given the 'Checked' story is rendered
          • provided a 6 digit hex value
          • it should reflect the hex value
          given the 'Checked' story is rendered
          • provided a 3 digit hex
          • it should reflect the hex value
          given the 'Checked' story is rendered
          • provided a hex with a hash
          • it should strip the hash from the hex value
          given the 'Checked' story is rendered
          • provided a hex with more than 6 characters
          • it should truncate the value to a length of 6
          given the 'Grow' story is rendered
            • it should not have any axe errors
            given the 'Grow' story is rendered
            • clicked
            • it should be focused
            given the 'Grow' story is rendered
            • provided a 6 digit hex value
            • it should reflect the hex value
            given the 'Grow' story is rendered
            • provided a 3 digit hex
            • it should reflect the hex value
            given the 'Grow' story is rendered
            • provided a hex with a hash
            • it should strip the hash from the hex value
            given the 'Grow' story is rendered
            • provided a hex with more than 6 characters
            • it should truncate the value to a length of 6
            given the `Disabled` story is rendered
              • it should not have any axe errors
              given the `Disabled` story is rendered
                • it should be disabled
                Source: ColorPicker.spec.ts

                Color Preview Anatomy

                Image of a Color Preview in a changed state.

                1. Label: Title of the input. Label position could be set to the top or left of the Color Preview.
                2. Active Color Swatch: Square container that shows what the color looks like.
                3. 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

                Color Preview Props

                Undocumented props are spread to the underlying <input type="text"> element.

                NameTypeDefaultDescription
                value*stringThe value of the ColorPreview.
                idstring | undefinedThe HTML `id` of the underlying text input element.
                errorErrorType | undefinedThe type of error associated with the TextInput (if applicable).
                widthstring | number | undefinedThe width of the TextInput.
                themeEmotionCanvasTheme | undefined
                growboolean | undefinedTrue if the component should grow to its container's width. False otherwise.
                refReact.Ref<any>Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If `as` is set to an element, it will be that element. If `as` is a component, the reference will be to that component (or element if the component uses `React.forwardRef`).
                as"symbol" | "object" | "small" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "button" | ... 156 more ... | React.ComponentType<any>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 `React.forwardRef` and spread extra props to a root element.

                Color Preview Specifications

                GivenWhenThen
                given the 'Basic' story is rendered
                  • it should not have any axe errors
                  Source: ColorPicker.spec.ts

                  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