Form Field

Usage Guidance

The Form Field is a wrapper component intended to be used with Canvas Kit input components when designing a form to ensure they meet accessibility standards. Inputs collect data from users within a form. It’s important to choose the right input to elicit a response in the format you want. For more information on best practices for designing forms, reference the Forms Pattern documentation.

When to Use

• Use the Form Field component as a wrapper for most inputs on a form. From a designer perspective, it is not a visible component but something to be aware of when working with developers on a form as the Canvas Kit Form Field should encapsulate input components on a form.
• Use form fields to ensure forms meet accessibility guidelines.

When to Use Something Else

• Consider using a Table when presenting and editing sets of repeating data with the same structure.
• Consider using a Popup or Toast component to display confirmation messages or validate user inputs in the context of a user action.

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.

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.

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

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

Error

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

Component API

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

Specifications

Given	When	Then
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 input should have a "required" attribute

Source: FormField.spec.ts

Content Guidelines

• Reference the Form Pattern Guidance for more information on designing forms and strategies to enable the best user expeience of form content.
• For content guidance regarding input types for forms, see Checkbox, Dropdown, Empty State, Errors and Alerts, Field Labels, and Radio Buttons in the Content Style Guide.