Form Field
Form Field allows users to wrap input components to make them accessible and adds complementary labels and error messages.
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.
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.
Component API
FormField
Props
Name | Type | Description | Default |
---|---|---|---|
labelPosition |
| The position of the FormField label. |
|
label | ReactNode | The text of the FormField label. | |
hintText | ReactNode | The text of the message displayed below the input component. This is required if | |
hintId | string | The HTML | |
inputId | string | The HTML | |
error |
| The type of error associated with the FormField (if applicable). This is passed to the input component. | |
required | boolean | If true, style the FormField label to indicate that it is required. | false |
useFieldset | boolean | If true, render the FormField using a | false |
children | ReactNode | The input component wrapped by the FormField. | |
errorLabel | string | The label for the error message hint text if |
|
alertLabel | string | The label for the alert message hint text if |
|
theme |
| ||
grow | boolean | True if the component should grow to its container's width. False otherwise. |
Undocumented props are spread to the outermost element rendered by Form Field.
Specifications
Given | When | Then |
---|---|---|
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 'Error' story is rendered |
| |
given the 'Error' story is rendered |
| |
given the Required story is rendered |
| |
given the Required story is rendered |
|
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.
Can't Find What You Need?
Check out our FAQ section which may help you find the information you're looking for.
FAQ Section