Form Field

Form Field allows users to wrap input components to make them accessible and adds complementary labels and error messages.

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

User Guidance

Coming soon!

Examples

Basic Example

Form Field should be used in tandem with most Canvas Kit input components to ensure they meet accessibility standards.

Here's an example of Form Field being used with Text Input.

Custom Input id

Form Field will automatically generate an HTML id for its input element to link it to the correponding label. Alternatively, you may set the inputId prop of the Form Field to specify a custom id for the input element.

Grouping Inputs

Set the useFieldset prop of the Form Field to true to indicate that it includes multiple input components. In this case, the Form Field will use the method prescribed by the WAI and render itself using a fieldset and a legend.

useFieldset must be set to true when wrapping a Radio Group since Radio Groups contain multiple Radio Buttons.

Choose your pizza crust

Grow

Set the grow prop of the Form Field to true to configure it (including the wrapped input component) to expand to the width of its container.

Hint

Set the hintText prop of the Form Field to display a short message below the input component.

This address will be shown as a shipping address option for future orders.

Label Position

Set the labelPosition prop of the Form Field to designate the position of the label relative to the input component. labelPosition accepts the following values:

  • FormField.LabelPosition.Top (Default)
  • FormField.LabelPosition.Left

Required

Set the required prop of the 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 Form Field to indicate it has an error. error accepts the following values:

  • FormField.ErrorType.Alert
  • FormField.ErrorType.Error

The hintText and hintId props of the Form Field are required if error is defined. Set hintText to the error message you would like to display and hintId to the HTML id you would like to assign to that message (hintId is used to link the error message to its corresponding input element to meet accessibility standards).

Alert

Alert: Please enter a valid email.

Set the alertLabel prop of the Form Field to override the default "Alert" prefix of the hint. This is generally only used for translations.

Warning: Please enter a valid email.

Error

Error: Please enter a valid email.

Set the errorLabel prop of the Form Field to override the default "Error" prefix of the hint. This is generally only used for translations.

Issue: Please enter a valid email.

Props

Undocumented props are spread to the outermost element rendered by Form Field.

NameTypeDefaultDescription
labelPositionFormFieldLabelPosition | undefinedFormField.FormFieldLabelPosition.TopThe position of the FormField label.
labelReactNodeThe text of the FormField label.
hintTextReactNodeThe text of the message displayed below the input component. This is required if `error` is defined.
hintIdstring | undefinedThe HTML `id` of the message displayed below the input component. This is required for the `aria-describedby` accessibility attribute if `error` and `hintText` are defined.
inputIdstring | undefinedThe HTML `id` of the input component. If an `id` is not specified for the input, this will be used as it's `id`. This is referenced by the label's `htmlFor` attribute. This is required for accessiblity if `label` is defined.
errorErrorType | undefinedThe type of error associated with the FormField (if applicable). This is passed to the input component.
requiredboolean | undefinedfalseIf true, style the FormField label to indicate that it is required.
useFieldsetboolean | undefinedfalseIf true, render the FormField using a `fieldset` and a `legend` instead of a `div` and a `label`. This must be set to `true` if you're using a Radio Group inside of a FormField (for accessibility reasons).
errorLabelstring | undefined'Error'The label for the error message hint text if `hintText` and `error` are defined. This prop should only be used for translating the default string 'Error'.
alertLabelstring | undefined'Alert'The label for the alert message hint text if `hintText` and `error` are defined. This prop should only be used for translating the default string 'Alert'.
themeEmotionCanvasTheme | undefined
growboolean | undefinedTrue if the component should grow to its container's width. False otherwise.

Specifications

GivenWhenThen
given the Basic story is rendered
    • it should not have any axe errors
    given the Basic story is rendered
    • clicking on the label
    • it should focus the input
    given the 'Alert' story is rendered
      • it should not have any axe errors
      given the 'Alert' story is rendered
        • it should connect the input with the hint text
        given the 'Error' story is rendered
          • it should not have any axe errors
          given the 'Error' story is rendered
            • it should connect the input with the hint text
            given the Required story is rendered
              • it should not have any axe errors
              given the Required story is rendered
                • the asterisk should a title attribute set to "required"
                Source: FormField.spec.ts

                Can't Find What You Need?

                Check out our FAQ section which may help you find the information you're looking for.

                FAQ Section