Forms

Structure

Always use labels

All form fields should have descriptive labels that are:

• Maximum three words long (consider help text if you’re struggling with the limit)
• Written in sentence case (except for feature or entity names)
• Without a colon at the end

We don’t use placeholders as replacements for labels as they lead to numerous accessibility issues, strain short-term memory and cause mistakes when filling forms (according to Nielsen Norman Group research).

Group fields into sections

Form fields that are closely related should be visually grouped together. When creating a section for connected fields, provide a short heading to describe the group (for example: Billing information, Notification settings, User permissions). We utilise semantic HTML to group (fieldset) and provide section titles (legend). If it’s necessary, you can also add a short description in a paragraph underneath the heading.

Mark required vs. optional fields

We always provide explicit guidance on which fields are required to ensure users complete forms successfully. Form elements are marked depending on the composition of each form:

• if the majority of fields are required, only mark optional fields with the (optional) label
• if the majority of fields are optional, only mark the required fields with the (required) label

Always mark required fields with both required and aria-required attributes. Avoid an excessive number of optional form fields. If there’s a case when it’s not avoidable, consider grouping optional fields under the same form section.

Use appropriate form fields

Tailor form fields to the type of input that’s expected. HTML natively supports numerous, semantic input types that guide users in providing the desired values and provide additional functionality, such as password masking. When working with free form text:

• Use input type="text" for several words
• Use textarea for several sentences

Provide help

When form fields aren’t self-explanatory or are less familiar to users, we provide contextual help to prevent errors in configuration. The way we provide help depends on the context of information shared:

Layout

1. Label: explains the purpose of a field.
2. Tooltip or Popover (optional): provides non-essential guidance about a field.
3. Validation message: appears when the input has error or success state.
4. Optional or required suffix: indicates if a field is required or optional.
5. Placeholder (optional): provides an example of what should be input into the field.
6. Helper Text (optional): provides a short explanation of the data required in the field.
7. Helper Text (optional): provides an example of data that should be inputted.
8. Actions: used to submit or cancel a form.

Element alignment

To ensure readability and the ease of scanning forms:

• Content flows from top to bottom and is left-aligned
• Labels are placed above the inputs (in rare cases, they might be located to the left of the input—this behaviour will be specified at a component level)
• The button container is aligned to the right
• The primary button is positioned to the right of its container
• In multi-column forms, elements are baseline aligned

Single and multi-column forms

We recommend single-column forms for the majority of use cases. When working with a single-column form layout, consider setting a minimum and maximum width for the form element to ensure it’s responsive to viewport changes and form elements aren’t excessively wide but adapt to the inserted data.

While multi-column forms make the flow of forms hard to follow and can lead to user confusion (according to Nielsen Norman Group research), there are limited use cases when they can be helpful. Consider a multi-column form layout when a form has many related fields commonly grouped.

 

When using multi-column forms, make sure that:

• Enough screen space is available
• Related fields are grouped horizontally (e.g. name and surname)
• There is a maximum of 3 columns
• Columns are stacked on smaller screen sizes

Field sizing

When sizing form fields, consider the following:

• The amount of expected user input
• Sizing of the other fields in a form

If a user has to provide a double-digit number, there’s no need to use input that spans most of the screen. However, we discourage having forms with inputs of many inconsistent sizes. Balance these two approaches to create a uniform experience.

Placement

Where you place a form depends on its length and the context of the action a user intends to perform:

Disabling and hiding form elements

By default, we don’t hide form elements that users don’t have access to due to roles and permissions. Instead, we use the disabled HTML attribute to show that the element exists, but the user doesn’t have permissions to edit. In those cases, we also provide contextual messages to communicate why a field isn’t editable.

If the disabled form field already has been filled, we use the readonly HTML attribute instead. In most cases, a form will be either fully editable or not editable at all depending on user permissions.

Unfilled forms (adding)

Submit buttons should be enabled by default when filling out a form for the first time. Submit buttons with a disabled attribute introduce numerous negative impacts for accessibility and user experience, such as:

• Creating obstacles for people using screen readers or keyboards to navigate forms.
• Reducing readability as disabled component variants often have insufficient contrast.
• Fostering confusion by creating an impression that something is off without an explanation.

Filled forms (editing)

There might be limited, specific use cases when adding a disabled attribute is warranted. One of them is disabling a button when editing an already filled form until changes are made to either of the form fields.

Another one is temporarily disabling a button when submitting takes a noticeable amount of time and we want to prevent double submission of the form. In those cases, the change of state should be appropriately visualised and communicated through micro copy.

Progressive disclosure of form fields

Progressive disclosure is an interaction design strategy for reducing cognitive load when faced with complex interfaces. In the context of forms, we recommend hiding elements that are available only when the user makes a specific selection (most commonly using Radio or Checkbox components).

For example, a user can turn on automatic retries for a process. An additional setting for this option is to specify the interval between retries. The extra option should only be displayed when a user enables automatic retries, as portrayed below:

 

Validation and error messaging

Clear and timely messaging is critical in guiding users through resolving issues while filling forms. We always provide concise information about what happened and what the steps should be followed for positive resolution.

Validation states

There are two types of validation states for form fields:

• Error: When content is invalid and needs to be corrected, this state is always accompanied by a reason for the invalid input and steps to resolve it.
• Success: When content is valid. Messaging doesn’t usually accompany this state unless client-side validation is used to live-check the input (e.g. checking if a provided URL is valid).

Server-side validation

Server-side validation is the primary way of validating forms in Octopus. The entire form should be validated on submission. When a form fails validation:

• Display a summary of errors referencing invalid form fields and scroll to the summary to ensure it’s in the viewport
• Use inline validation states on erroneous fields
• If an error cannot be tied to a particular field, use a top form level message (same approach as when amount of errors exceeds 3)
• Mark invalid form fields with aria-invalid=true to ensure invalid fields are properly announced by assistive technology
• Tie inline messaging for invalid fields by providing an id in aria-describedby attribute

Client-side validation

Traditionally, client-side validation occurs in real time (as users interact with form fields). Currently, we use this type of validation only in Channels area (when designing package version rules: see “Design rule” action and enter invalid Sample Versions), and we encourage using server-side validation instead.

If client-side validation is the most suitable solution, ensure consistency between front-end and back-end implementation of the validation rules.

Another way of defining client-side validation is using the right component with the right attributes to enforce correct data input (for example, using input type="number" with min and max values when expecting numeric values within a certain range). The use cases for each component can be found in their documentation.

Accessibility

• Allow tabbing through form fields in logical order. This benefits visually impaired users who might be using assistive technologies.
• Auto focus into the first field by default. This ensures people can quickly orient themselves and tab through the form elements.
• Never turn off the submission button, even if all form fields haven’t been filled out yet. Use validation and error messaging to guide people in providing expected data.

See WCAG Form Tutorial for specific, in-depth instructions about creating accessible forms.