Description

A form is a collection of input fields which allows users to enter data to be stored, and then retrieved and updated as needed.

Forms may appear:

• in the main workspace.

• inside various containers, including Dialog popups, Popovers, Wizards, Filter panes, Details panes and Cards.

In the main workspace	Inside a Dialog popup

Usage & Behavior

Structure

A form consists of two areas:

• the input area, which may contain any set of input fields, including Text fields, Drop-down menus, Checkboxes, Radio buttons etc.

• the action area, which consists of:

  • A submit button, such as Save, Create, or Edit.

  • an additional Cancel button, when shown inside a container.

  • additional actions, if needed.

The Input Area

For the usage and behavior of inline inputs, see Inline Inputs.

• Where possible, field labels will appear above the input field.

• Where relevant, a red mandatory indicator (*) will be shown 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).

The Action Area

• The action area will always be visible.

• Primary action buttons, such as Save or Cancel, will be aligned to the right. Secondary actions, if exist, will be shown as a toolbar, aligned to the left.

• Where the form takes up the entire workspace, the action area will appear at the top of the page. (See Examples below).

• In all other cases, the action area will appear below the form.

  • In widgets within the workspace, the action area will be separated by a horizontal line.

    • If the form does not exceed 2/3 of the height of the container, the action area will appear at a 2/3 height.

    • If the form exceeds 2/3 of the height of the container, the action area will stick to the bottom of the container, allowing users to scroll the form above it, if needed.

  • Inside dialog popups and other containers, the action area will appear at the bottom of the container (see Examples below).

States

• Forms can have two states:

  • Idle / Saved. Applies when entering a form or after clicking the Submit button. In this case, the Submit button is disabled.

  • Edited. Applies after making changes to the form but before clicking the Submit button. In this case:

    • the Submit button is enabled.

    • attempting to leave the form will trigger a confirmation message. See Validation and errors below.

Interaction

• Clicking the submit button:

  • sends the data for further processing. (For error handling see Validations and errors below).

  • In workspaces, if the form was submitted successfully (for example, an entity was created or updated):

    • A success Toast will appear.

    • If the form was triggered from a parent page, the user will be redirected back 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 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 data.

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.

  • If there is an input error, the submit button will be disabled again. Only after all errors have been resolved is it enabled again.

  • After clicking the submit button, it becomes disabled again.

• In case the user tries to navigate away from a form after updating one or more fields (“dirty state”) or while there are errors on the form:

  • a message popup will appear (see Common messages repository).

  • the user will choose to either keep editing the form or leave and discard changes.

In case of unsaved changed	In case of errors in the form

Best practices

Use for:

• Creating or updating entities, such as users, roles, and channels.

• Configuration, such as services level indicators or storage retention periods.

General

• 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 under a Contact Information section.

Examples

Accessibility compliance

Unless otherwise specified, see our general compliance information in Fundamentals - Accessibility.