Form is a group of related inputs that allows users to provide data or configure options.
Overview
Use forms when user input is required to complete some action. Forms direct users to provide and submit relevant information, such as changing personal settings. Forms can be simple or complex, and may be presented as dedicated pages, side panels, or dialogs depending on the use case and the situation.
Anatomy
- Title (optional) - Text that describes the purpose of the form.
- Description (optional) - Provides additional context about the form or the information that needs to be input.
- Form inputs - Input components for users to provide required information or make necessary choices. Common form components include: checkbox, date picker, radio group, select and text field.
- Fieldset - Groups related fields together in a logical set to create hierarchy that helps users understand and complete related inputs. See Fieldset.
- Actions - Buttons that allow users to submit the form or cancel their inputs.
Demo
Open the component in Figma.
When to use
Almost all fields should be wrapped in a form to provide structure, hierarchy, and appropriate higher-level errors.
When not to use
If you need only one input, you could use it without wrapping it in the form component.
Similar components
Behaviors
Form validation
Errors
Form errors are displayed when inputs are invalid. These errors should be highly visible and persistent until resolved.
Within a form, there can be three types of errors:
Input error
Each input field in a form has its own error state that prevents a user from moving forward or completing a form.
Form-level error
Alert the user to form-level errors that prevent the form from being submitted. For example, a technical issue like a server error or permissions issue that prevent the form from being submitted.
Fieldset-level error
Although rarely required, if your form uses fieldsets, then a field-set level error can appear above the fieldset in a callout. This alerts the user to an error that affects inputs within the fieldset, for example, if the user doesn't have permissions to make the changes or there is a server issue.
Validation styles
Forms can be validated in one of two ways. Odyssey recommends client-side validation, but you can choose server-side depending on the product use case.
Client-side validation
Client-side validation displays errors in real-time. This validation style is recommended because it offers a better user experience. For example, if a user enters an invalid email format, you can display an error message immediately after the input has lost its active or focus state. This gives the user the opportunity to finish filling out the field before an error message is shown.
Server-side validation
Server-side validation occurs after the user submits their input fields using a button. The form is sent to the server and If there are any errors, the feedback is sent back to the client with the errors.
Accessibility
Odyssey components are designed and built to meet accessibility requirements out of the box. So, designers and engineers can focus on any accessibility concerns unique to their problem areas.
Our components meet WCAG 2.2 AA criteria and WAI-ARIA guidelines to provide a usable and accessible experience to everyone.
Content guidelines
Title (optional)
- The title helps users understand what information to enter in the form.
- Every form should have a title.
- There are some accessibility-approved exceptions. If the form is the only component on a page, the page title can explain the form and a repetitive form label isn’t necessary.
- The title is always visible.
- The title should be short and clear — ideally one to five words and never longer than one line of text.
- Titles should typically be nouns. For example, User information not Enter user information.
- Use sentence-style capitalization for all titles, except for product names and proper nouns.
- Don’t use colons after titles.
Description (optional)
- Provide guidance or instructions to help the user correctly complete a form.
- To clarify how the information the user enters will be used.
- A description should be limited to a single line, though multiple lines can be allowed sparingly if there isn’t a concise way to explain the form.
- Write in sentence case (capitalize the first word and proper nouns only).
- Write the text as full sentences with punctuation.
- If the description repeats the title, don’t include it.
Inputs
Inputs should follow a logical, predictable order—for example, always ask for first name first, and last name second.
See the appropriate component’s content guidelines for specific content guidance.
Form input labels
Effective labeling helps users understand what information to enter in an input.
Best practices for labels
- Although they may be formatted differently, all input components need labels.
- Labels should clearly state the required input.
- Be succinct. Use one to three words only.
- Do not use colons after label names.
- Write in sentence case (capitalize the first word and proper nouns only).
Optional inputs
When you have both optional and required fields within a form it is important to distinguish one from the other. In WIC, most of our fields are required settings. To keep the interface as clean as possible, only optional fields need to be labeled.
Add optional after the input’s label.
Don’t use an asterisk to indicate optional. The asterisk then just needs explanatory text near the field and is less accessible.
Placeholder text
Odyssey doesn’t support placeholder text due to usability and accessibility issues. Use hint text for any input that needs an explanation of the format or type of data that needs to be entered.
Note: Search fields are the only inputs with a prop to show default placeholder text. It is generally Search....
Hint text (optional)
- Hint text provides guidance or instructions to help the user correctly complete a field.
- For example, the location of information the user needs to enter in the field. Or, shows examples of the correct data format. Or, clarifies how the information the user enters will be used.
- If there’s not enough room to include both instructions and an example, then only include the example.
- Hint text should be limited to a single line, though multiple lines can be allowed sparingly if there isn’t a concise way to explain the field.
- Write in sentence case (capitalize the first word and proper nouns only).
- Write the text as full sentences with punctuation.
- Don’t add hint text only to maintain layout continuity with other inputs that include hint text.
- If the hint text repeats the label, don’t include it.
Actions
Allow users to submit the form or cancel their inputs.
Buttons
- State the action that the buttons perform when clicked.
- Avoid multiple action buttons and avoid a reset button. This will reduce confusion about how to submit the form.
See Button
Errors
Forms have three levels of errors.
- Input: Individual inputs display inline errors as needed. See each component for guidance on errors.
- Form-level error: When there are multiple input errors in the form, a form-level error appears at the top of the form in a callout. The callout persists until all input errors are resolved.
- Fieldset-level error: A group error appears above the fieldset in a callout. This allows multiple errors in a section to be highlighted closer to the affected inputs.
See
Content accessibility
All fields are required to have an accessible label visible. (Search fields are an exception to this and use placeholder text and an ARIA-label.)
Additional references
- Kathryn Whitenton (May 1, 2016) Website Forms Usability: Top 10 Recommendations - Nielsen Norman Group
- Matteo Penzo (July 12, 2006) Label Placement in Forms - UXmatters
- Edward Scott (September 17, 2018) Avoid Multi-Column Forms - Baymard Institute