<iframe src="https://www.googletagmanager.com/ns.html?id=GTM-5HGSQD2L" height="0" width="0" style="display:none;visibility:hidden" title="GTM"></iframe>

Form

Standardized layout for the form elements.
styleKeys: fieldset

Use Form...

The React components for Form provide accessibility support automatically.

Standard Form

Use StandardForm to provide a standardized layout and spacing for a series of FormInputGroup components and their labels.

The preview has been updated.

Form Field

FormField is a utility component whose purpose is to associate an input with its label and helper/error components and include the appropriate html attributes required for accessibility.

It does not provide any styling.

Form Input Group

Use FormInputGroup to provide a standard layout for an input (e.g., Text Input, Text Area, or Dropdown), an optional piece of helper text, and an optional error message.

The preview has been updated.

Tight

Use skin="tight" on StandardForm to reduce vertical space between each FormInputGroup.

The preview has been updated.

Floating Label

Use InputWithFloatingLabel to create a label inside the form element that is positioned at the top (in case of Dropdown and Listbox) or is placed at the position of the placeholder (in case of Combobox, Search Input, Text Input, TextArea) which shifts to the top once the user starts entering text.

When using InputWithFloatingLabel, use FloatingLabel instead of FormLabel, which has the same accessibility benefits.

The preview has been updated.

You can refer to individual pages to see how floating labels can be used with each one of them.

Horizontal layout

  • Use variant="horizontal" on StandardForm to render the label next to the input rather than above it.
  • First, render a GridContainer inside of the StandardForm, and render a separate Row for each field.
  • In the React API, take advantage of the component property on Row. Normally, Row just renders a div. Instead, use the component prop to tell Row to render a FormField rather than a plain div. The result is a component that is both a Row and a FormField.
  • Next, inside each Row, render one column element for the label, and another for the FormInputGroup. Pick column widths as appropriate for the content, but do not set explicit column values on extra-small screens. Doing so lets the form assume a vertical arrangement on extra-small screens instead.

The preview has been updated.

Grouping fields

Use Fieldset to group several related form fields together within a single form. Provide a caption that describes the grouping with FieldSetLegend.

If Fieldset can't be used, use a surrounding element with role="group" and an appropriate aria-labelledby or aria-label.

The preview has been updated.

Accessibility

Labels

  • Any input field (i.e., Text Input, Search Input, Text Area, Combobox, Listbox or Dropdown) needs an accessible label; the React API FormLabel component inside a FormField will provide this. Alternatively, you can use a FloatingLabel as shown in the examples above. If you are not using FormLabel or FloatingLabel you need to add a label, preferably a <label> tag, with a for attribute whose value is the id of the input. (If a <label> tag is not possible, the input either needs a aria-labelledby attribute, or an aria-label attribute with a localized value.)

Required and optional fields

  • To indicate required fields:
    • Add the attribute aria-required="true" to the input, to signal to assistive technologies that the field is required.
    • Add an asterisk "*" inside the FormLabel.
  • To indicate optional fields:
    • Use FormLabelOptional to wrap the "(optional)" text inside the FormLabel.

The preview has been updated.

Inputs

  • If the input is collecting the user's personal data such as mailing address or credit card, it must have an appropriate value for the autocomplete property, based on the list of 53 Input Purposes for User Interface Components. (This allows the browser to autofill these fields with saved data.)
  • For inputs with buttons beside them or inset inside them, if the button is simply an icon and has no visible text, it will need to provide assistive devices with information on what the button does:
    • If the button has nearby text that explains what it does, the button should have an aria-labelledby attribute whose value is the id of the element that describes it.
    • Otherwise, the button should have an inner span that is visually hidden, and whose contents are localized text explaining what the button does (e.g. "Search").

Errors and helper text

The preview has been updated.

  • When an input field has helper text and/or an error message, that text needs to be associated with the input; the React API FormField component along with FormHelper and/or FormError will provide this. If you are not using FormField: the input should have an aria-describedby attribute whose value is a space-separated list of the ids of the message(s).
  • When an input field has an error, the input should have aria-describedby and aria-errormessage attributes whose value is the id of the error message; the React API FormField and FormError will provide this. The error message should not be a label tag with a for attribute pointing to the input. For the React API, FormError the error icon is automatically added. However, in the Vanilla API, users must manually include an error icon alongside the error message.
  • When a form input field has a visible error message, the input should have aria-invalid="true" to indicate that its current value is invalid. It should also have both an aria-describedby attribute and an aria-errormessage attribute, both of whose values are the id of the error message.
  • If you are dynamically adding an error message after initial page load, then the content area where the error will appear will need to already have role="status" aria-live="polite" on it. These attributes inform assistive technologies that they need to notify the user when any content inside that area changes, and thus the browser will announce the error message when it appears.

Errors best practices

  • Place FormError below an input, inside a FormInputGroup.
  • When an error message occurs, preserve as much user input as possible, so that the user can modify the information, rather than have to re-enter it from scratch.
  • Error messages need instructions on what the user needs to do to correct the error. For instance, it's not enough to say that the user's password choice wasn't valid; instead, the error message might say "Passwords must be at least 8 characters."
  • It is a best practice, but not an absolute requirement, to move focus to the error message or to the first field with an error.

Do

Use FormError for errors with individual Text Inputs, Dropdowns, and Combobox with Seach Input

Dont

Use FormError for errors with Radio Buttons. Use an Alert Box instead, at the top of the Radio Buttons.

Props

FormInputGroup
This component is implemented using the <div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
See core props for additional props that can be applied to this component.
FormLabelOptional
This component is implemented using the <span /> as the root element. You can utilize the native attributes supported by <span /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
See core props for additional props that can be applied to this component.
FormError
This component is implemented using the <p /> as the root element. You can utilize the native attributes supported by <p /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
See core props for additional props that can be applied to this component.
FormField
This component is implemented using the <div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
See core props for additional props that can be applied to this component.
FormHelper
This component is implemented using the <p /> as the root element. You can utilize the native attributes supported by <p /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
See core props for additional props that can be applied to this component.
FormLabel
This component is implemented using the <label /> as the root element. You can utilize the native attributes supported by <label /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
See core props for additional props that can be applied to this component.
proptyperequireddescriptiondefault
skin"standard" | "line" | nullfalse
⚠️ Deprecated - This is deprecated without a replacement.
standard
StandardForm
This component is implemented using the <form /> as the root element. You can utilize the native attributes supported by <form /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
See core props for additional props that can be applied to this component.
proptyperequireddescriptiondefault
variant"horizontal" | "vertical" | nullfalse
⚠️ Deprecated - This is deprecated without a replacement.
vertical
skin"standard" | "tight" | nullfalse
⚠️ Deprecated - This is deprecated without a replacement.
standard

Related