Use Form...
- To provide a standardized layout for one or more input elements (e.g., Text Input, Dropdown, Checkbox).
The React components for Form provide accessibility support automatically.
Standard Form
skin prop is deprecated in SWAN v3.8
Skin styling is no longer used, remove prop from uses.
Use StandardForm to provide a standardized layout and spacing for a series of FormInputGroup components and their labels.
ShareForm 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.
Tight
Use skin="tight" on StandardForm to reduce vertical space between each FormInputGroup.
Horizontal layout
- Use
variant="horizontal"onStandardFormto render the label next to the input rather than above it. - First, render a
GridContainerinside of theStandardForm, and render a separateRowfor each field. - In the React API, take advantage of the component property on
Row. Normally,Rowjust renders a div. Instead, use the component prop to tellRowto render aFormFieldrather than a plaindiv. The result is a component that is both aRowand aFormField. - Next, inside each
Row, render one column element for the label, and another for theFormInputGroup. 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.
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.
Accessibility
Labels
- Any input field (e.g., Text Input, Text Area, or Dropdown) needs an accessible label; the React API
FormLabelcomponent inside aFormFieldwill provide this. If you are not usingFormLabel, you need to add a label, preferably a<label>tag, with aforattribute whose value is theidof the input. (If a<label>tag is not possible, the input either needs aaria-labelledbyattribute, or anaria-labelattribute 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.
- Add the attribute
- To indicate optional fields:
- Use
FormLabelOptionalto wrap the "(optional)" text inside theFormLabel.
- Use
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-labelledbyattribute whose value is theidof the element that describes it. - Otherwise, the button should have an inner
spanthat is visually hidden, and whose contents are localized text explaining what the button does (e.g. "Search").
- If the button has nearby text that explains what it does, the button should have an
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
FormFieldcomponent along withFormHelperand/orFormErrorwill provide this. If you are not usingFormField: the input should have anaria-describedbyattribute whose value is a space-separated list of theids of the message(s). - When an input field has an error, the input should have
aria-describedbyandaria-errormessageattributes whose value is theidof the error message; the React APIFormFieldandFormErrorwill provide this. The error message should not be alabeltag with aforattribute pointing to the input. - 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 anaria-describedbyattribute and anaria-errormessageattribute, both of whose values are theidof 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.