Lead: Liav Nadler
Issues to cover
Form-level elements
Status tags
Messages
Action buttons
Distances between buttons (if more than 2)
Guidance
Form instructions
Field help
Ask Femi about web SDK form guidance
Autosave
Description
A form is a collection of input fields, allowing users to enter data that is then sent for further processing.
Forms may appear in workspaces, dialog popups, popovers, wizards, filter panes, details panes and cards.
Usage & Behavior
Structure
A form consists of two areas: the input area and the action area.
The input area may contain any set of input fields, including text fields, dropdown menus, checkboxes, radio buttons etc.
The action area usually consists of at least two buttons: a submit button (Save, or Create, or Update etc.) and Cancel.
The Input Area
Field labels will appear on top of the input field (for example, above a text field or a set of radio buttons).
Where relevant, a red mandatory indicator (*) will show next to the label.
Where relevant, a help icon will appear next to the label (aligned to the right side of the field, if possible).
A collection of related fields can be grouped into a section. For example, fields like Email and Phone can be found under a section called Contact Information.
Two or more fields may be dependent. In this case:
Any dependent field will appear below the original (independent) field.
selecting a value for a dependent field will be possible only if there is a value in the original (independent) field.
The Action Area
The action area will always be visible:
In case the form takes up the entire workspace, the action area will appear at the top of the page (see examples below).
In any other case, the action area it will appear below the form:
In dialog popups, popovers, wizards, filter panes, details panes and cards, the action area will appear at the bottom of the container.
In workspaces:
If the form does not exceed the height of its container, the action area will appear directly below the last field of the form.
If the form exceeds the height of its container, the action area will stick to the bottom of the container, allowing users to scroll the form above it. Add example
Primary buttons will be aligned to the right. Additional buttons, such as Clear or Reset will be aligned to the left.
 |
States
Forms can have 3 states:
Idle - this is the default state when entering a form. In this case, exiting the form will not save it.
Dirty state - the state of a form after making changes but before clicking the Save button. In this case, exiting the form will trigger an error message (see below).
Saved - the state of a form after clicking the Save button.
Interaction
Clicking the submit button (Save / Create / Update etc.) switches the form to the saved state, and sends the data for further processing.
In case of creating or updating an entity, the user may be automatically directed to the original page (e.g., list of entities).
In case of a dialog popup or a popover, clicking the submit button will also close the popup / popover.
In case of a wizard:
Clicking a Next / Previous button may also direct the user to the next / previous page.
Clicking the Done button may also close the wizard.
Clicking the Cancel button will close the dialog popup / popover, or automatically direct the user to the original page.
Validations and errors
There are two types of validations related to forms: input validation and form validation.
Input Validation
This type includes all validations related to specific inputs, such as text fields, text areas, sets of checkboxes, etc. (see Field Validation).
The most common input-level errors are:
Invalid input, including invalid characters, invalid format and out-of-range data.
Missing mandatory input, where a required field was left blank.
Field validations for invalid characters or invalid format occurs while typing (“onkeydown”).
Field validations for out of range data or missing mandatory input occurs when a field looses focus (“onblur”).
When invalid input or missing mandatory input was detected, the field changes its status to error.
In some cases, the entered value is valid, but may call for a special attention (for example: a very large value). In this case, the field will change its status to warning, but will not prevent the form from being submitted.
Form Validation
A form cannot be saved or submitted if one or more of its fields are in error state. Here is a typical flow:
When entering a form, the Save button is disabled.
On updating a field, the Save button becomes enabled.
In case of an input error the Save button becomes disabled (an additional form-level indication may appear). Only after the error was resolved, the Save button is enabled again.
After clicking the Save button:
it becomes disabled again,
a toast message may appear, indicating that the form was saved.
This flow is also relevant when the form is in a dialog popup. In this case, the Cancel button is always enabled.
Saving “dirty data” in local storage
In case a single Save button applies to multiple areas (tabs, master items in a master-detail layout, etc.), updated values will be saved in a local storage even before clicking the Save button.
In this case, if the user updated a value in the first area, navigated to another area and went back to the first area, all updated values will remain intact.
Edge case: navigating to another area of the form while some fields has errors
In case the user tries to navigate to another area of the form, while the current area has errors, a message popup will appear, allowing him to either continue, while loosing all the updated data, or cancel.
Edge case: exiting an updated form
In case the user tries to navigate away from a form after updating one or more fields, a message popup will appear, allowing her to either save and exit, exit without saving, or cancel.
Best practices
Use for:
Creating or updating entities (e.g., users, roles, channels).
Configuration pages (e.g., services level indicators, storage retention periods).
Don’t use:
When?
General
In case of large number of fields, group related fields together, providing a clear title to each group.
Make sure there is a natural tab order between fields.
Make sure that label texts are not selectable.
Examples
 Update screen |  |
Accessibility compliance
Unless otherwise specified, see our general compliance information in Fundamentals - Accessibility
text highlight when using a keyboard + using arrows when in edit mode (left, up or home to set the insertion point at the beginning; right, down or end to set it at the end).
Design
Zeplin link | Screen thumbnail |
|---|---|
<<Short Zeplin link. You | <<Screen with 200 width>> |
Code
<<a box containing the code - discuss with Femi>>