| Table of Contents |
|---|
Description
A form is a collection of input fields which allows , allowing users to enter data to be stored, and then retrieved and updated as neededstore, retrieve, and update data.
Forms may appear :either in the main workspace
...
or within other containers,
...
such as Dialog popups, Popovers,Wizards,Filter panes, Details panes and Cards.
Usage & Behavior
Structure
A form consists of two areas:
the input Input area, which may contain containing any set of input fields , including Text fields, Drop-down menus, Checkboxes, Radio buttons etc.
the action Action area, which consists of:
A a submit button, such as Save, Create, or Edit.
an additional a Cancel button, when shown inside a container.
additional actions, if where needed.
The Input Area
For
...
specific form elements, browse the Components section in LUX.
Where possible, field labels will appear above the input field.
Where relevant, a red mandatory indicator (*) will be shown next to the right of the label.
Where a majority of fields are mandatory, a message will appear above the form indicating that all fields are mandatory unless otherwise specified.
Where relevant, a help icon will appear next to the label (aligned to the right side of the field, if possible).
...
The action area will always be visible.
Primary action buttons, such as Save or Cancel, Action buttons will be aligned to the right. Secondary actions, if exist, will be shown on a toolbar, aligned to the left.
Where the form takes up the entire workspace, the action area will appear appears at the top bottom of the page. (See Examples below).In all other main workspace, it will be separated by a horizontal line.
Placement and positioning
In most cases, the action area will appear below the form.
- In widgets within
Within the main workspace,
the action area will be separated by a horizontal line.Ifwhere the form does not exceed the height of
itsthe container,
the action area will appear
belowbeneath the last form field.
If
Within the main workspace where the form
exceedsreaches the
heightbottom of
itsthe container, and within Popups and other modals:
the action area will stick to the bottom of the container
, allowing users to scroll.
the form above
it.Inside other will have a scrollbar.
In some cases, where a form uses the entire workspace and is shown across multiple containers, the action area
...
may appear at the
...
top of the
...
...
workspace.
Main workspace - less than two thirds height | Main workspace - more than two thirds height | Popup | Entire workspace - form across multiple containers |
|---|---|---|---|
 |  |  |  |
States
Forms
...
have two possible states:
State | Usage |
|---|---|
Idle / Saved |
...
Applies when first entering a form or after |
...
saving it. In this case, the |
...
submit button is disabled. |
Edited |
...
Applies after |
...
changes are made to |
...
a form, but before |
...
saving or submitting. In this case:
|
...
|
The Cancel button is always enabled in all states.
Interaction
The submit button
Clicking the submit button : sends the data for further processing. (For error handling see Validations and errors below).
In
workspacesthe main workspace, if the form was submitted successfully
(for example, an entity was created or updated):Aa success Toast will appear.
If the form was triggered from a parent page, the user will automatically be
redirected backreturn to that page.
For forms inside containers, refer to the corresponding pattern documentation. For example
,:
clicking the submit button in a Dialog popup, will close closes it.
Clicking the Cancel button, if exists, will:
trigger a confirmation message, if the form is in the edited state, and then
close the container (unless pinned) without saving the dataclicking the Apply button on a Filter pane applies the filter and disables the button.
The Cancel button
Clicking Cancel on a form with unsaved changes may trigger a warning message, where necessary.
In the main workspace clicking Cancel will return to user to the parent page, without saving the data.
For forms inside containers, refer to the corresponding pattern documentation. For example:
clicking Cancel may close the Filter pane, depending on the pin state.
Validations and errors
...
For input-specific validations see Field validation.
A form cannot be submitted if one or more of its fields are in an error state. Here is a typical flow:
...
When entering a form, the submit button is disabled. (The Cancel button, if exists, is always enabled).
...
On updating any field, the submit button is enabled.
...
Validation triggers
There are two types of validation which may affect a form:
Type | Trigger events | Examples | Notes |
|---|---|---|---|
Client-side validation |
|
| Client-side issues are either resolved immediately (for example, on deleting an invalid character) or when the field loses focus. |
Server-side validation |
| When logical problems are detected, e.g. trying to create an object with a name that already exists. | In some cases, a Dialog popup may appear with additional instructions required to complete the action. When validation takes more than a few seconds, a Progress indicator will appear in a modal.  |
Presentation of errors and warnings
Errors and warnings are shown:
against individual form fields - see Field validation for more information.
as a message in the action area - see details below.
While the form contains an error, the submit button will be disabled
...
After clicking the submit button, it becomes disabled again.
...
.
...
A dedicated message will appear to the left of the action area. It will include:
a status icon. If both errors and warnings are present, an error icon will be used.
descriptive text including a link, and showing the total number of errors and warnings.
Error message | Warning message |
|---|---|
 Short form, where necessary:  |  Short form, where necessary:  |
Clicking the link opens a Popover, containing additional information. The popover includes:
general introductory text describing the number of issues and how to resolve them.
a list of issues, with errors appearing before warnings. Each issue will show:
an error or warning status icon.
a description of the issue and how to resolve it.
a Resolve or Review link, where relevant. Clicking the link closes the popover and sets the focus on the corresponding form field. The form may auto-scroll where necessary.
Examples
 |  |
Leaving an incomplete form
When the user navigates away from a form in the Edited state (after updating one or more fields
...
), or while there are errors on the form:
a
message
(seeMessage popup will appear. See Common messages repository
)for appropriate message text.
the user will choose to either keep editing the form or leave and discard changes.
In case of unsaved changed | In case of form errors |
|---|
 |
 |
Best practices
Use for:
Creating or updating entities, such as users, roles, and channels.
Configuration, such as services service-level indicators or storage retention periods.
...
Form fields should be arranged in one column. Closely related fields (e.g. First name and Last name) may appear side by side.
Collections of related fields should be grouped into sections. For example, fields such as Email and Phone may be found grouped under a Contact Information section.
Examples in different containers
Main workspace | Widget | Wizard | Details pane |
|---|---|---|---|
 |  |
 |
 |
Accessibility compliance
Unless otherwise specified, see our general compliance information in Fundamentals - Accessibility.
...