Lead:  Liav Nadler

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.

• Inside various containers, including 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 consists of a submit button (Save, Create, Update etc.) and additional actions, if needed.

• Inside containers, an additional Cancel button may appear.

The Input Area

• Where possible, field labels will appear above 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).

• For inline inputs usage and behavior, see Inline Inputs.

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 will appear below the form, separated by a horizontal line.

    • In workspaces:

      • If the form does not exceed the height of its container, the action area will appear 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.

    • Inside containers, the action area will appear at the bottom of the container.

• Buttons for main actions will be aligned to the right. If needed, buttons for secondary actions, such as clear or delete will be aligned to the left.

States

• Forms can have two states:

  • Idle / Saved - Applied when entering a form or after clicking the submit button. In this case:

    • The submit button is disabled.

    • Exiting the form will not save it.

  • Edited - Applied after making changes 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:

    • A success toast will appear (see Toasts).

    • If the form was triggered from a parent page, the user will be directed back to that page.

  • For forms inside containers, refer to the corresponding pattern documentation.

• Clicking the Cancel button, if exists, will close the corresponding component (if not pinned), without saving the data (a confirmation popup may appear).

Validations and errors

• For input-specific validations see Field Validation.

• A form cannot be submitted if one or more of its fields are in 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 becomes enabled.

  • In case of an input error, the submit button becomes disabled. Only after all errors have been resolved, it becomes enabled again.

  • After clicking the submit button:

    • it becomes disabled,

    • a toast message may appears, indicating that the form was submitted.

• This flow is similar where the form is in a dialog popup, but in this case, clicking the submit button closes the popup.

• In case the user tries to navigate away from a form after updating one or more fields or while there are errors, a message popup will appear, allowing the user to either keep editing or leave (see Common messages repository).

Best practices

Use for:

• Creating or updating entities (for example: users, roles, channels).

• Configuration (for example: services level indicators, storage retention periods).

General

• In general, form fields should be arranged in one column. Closely related fields (e.g., first name and last name) can appear side by side.

• Collections of related fields should be grouped into sections. For example, fields like 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

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

Code

<<a box containing the code - discuss with Femi>>