Form Component

Purpose

Form Component is a component that wraps a form.

Mobile renderer notes

On mobile, forms use the active white-label skin for gutters, field spacing, padding, radius, and surface treatment. The hero skin renders a raised card by default, while the outlined spotlight skin uses a transparent, edge-aligned surface. An explicit backgroundColor: transparent suppresses the card shadow.

Mobile forms support a localized subtitle alongside the localized title. Both are kept to one line; typography and casing follow the active skin. Layout containers own the outer form gutter, preventing nested padding from being applied twice.

Example

component: form
name: myForm
props:
  initialValue:
    firstName: John
    lastName: Doe
  dirtyGuard:
    enabled: true
    title:
      en-US: "Unsaved Changes"
    message:
      en-US: "You have unsaved changes. Are you sure you want to leave this page?"
    onConfirm:
      - notification:
          message: "Ignored unsaved changes"
          variant: warning
    onCancel:
      - notification:
          message: "Please save the changes before leaving this page"
          variant: warning
  onSubmit:
    - notification:
        message: "Form submitted successfully!"
        variant: success
  validationSchema:
    firstName:
      required:
        message: First Name is required
      min:
        length: 2
        message: First Name should be more than 2 characters
    phoneNumbers:
      type: array
      min:
        length: 1
        message: At least one phone number is required
      itemSchema:
        type: string
        required:
          message: Phone number is required
    contacts:
      type: array
      min:
        length: 1
        message: At least one contact is required
      itemSchema:
        type: object
        schema:
          name:
            required:
              message: Name is required
          phone:
            required:
              message: Phone is required

children:
  - component: field
    name: firstName
    props:
      label: First Name
      type: text
      placeholder: Enter your first name
  - component: field
    name: lastName
    props:
      label: Last Name
      type: text
      placeholder: Enter your last name
  - component: button
    name: submit
    props:
      label: Submit
      onClick:
        - submitForm:

prefix

The prefix property is used to prefix the name of the fields.

component: form
name: myForm
props:
  prefix: user

All the fields inside the form will be prefixed with user.

Props

• initialValue (object): The initial value of the form. Default is {}.
• prefix (string): The prefix to be used for the fields inside the form. Default is ''.
• queries (array): The queries to be used to populate the form. Default is [].
• validationSchema (object): The validation schema to be used for the form. Default is {}.
• dirtyGuard (object): Configuration for unsaved changes warning dialog. Default is undefined.
• reloadHandler (string): Handler targeted by the reload action. Falls back to refreshHandler, then the form name.
• onLoad (function): Actions to be performed when the form is loaded. Default is [].
• onSubmit (function): Actions to be performed when the form is submitted. Default is [].
• onCancel (function): Actions to be performed when the form is canceled. Default is [].

initialValue

The initialValue property is used to set the initial value of the form.

component: form
name: myForm
props:
  initialValue:
    firstName: John
    lastName: Doe

initialValue from query

The initialValue property can be set from a query.

component: form
name: myForm
props:
  initialValues:
    fromQuery:
      name: getCountry
      path: country
  queries:
    - name: getCountry
      query:
        command: >-
          query($organizationId: Int!, $countryCode: String!) { 
            country(organizationId: $organizationId, countryCode: $countryCode) { 
              organizationId
              countryCode
              created
              createdBy
              customValues
              lastModified
              lastModifiedBy
              name 
            }
          }
        variables:
          organizationId: "{{number organizationId }}"
          countryCode: "{{string countryCode }}"

dirtyGuard

The dirtyGuard property prevents users from accidentally navigating away from a form with unsaved changes. When enabled, it displays a confirmation dialog if the user attempts to leave the page while the form contains unsaved modifications.

Properties

Property	Type	Description
enabled	boolean	Enables or disables the dirty guard feature
title	object	Localized dialog title (e.g., en-US: "Unsaved Changes")
message	object	Localized dialog message explaining the warning
confirmLabel	object	Localized confirm button text (e.g., en-US: "Leave")
cancelLabel	object	Localized cancel button text (e.g., en-US: "Stay")
onConfirm	array	Actions to execute when user confirms leaving (discards changes)
onCancel	array	Actions to execute when user cancels and stays on the page

component: form
name: myForm
props:
  dirtyGuard:
    enabled: true
    title:
      en-US: "Unsaved Changes"
    message:
      en-US: "You have unsaved changes. Are you sure you want to leave this page?"
    confirmLabel:
      en-US: "Leave"
    cancelLabel:
      en-US: "Stay"
    onConfirm:
      - notification:
          message: "Ignored unsaved changes"
          variant: warning
    onCancel:
      - notification:
          message: "Please save the changes before leaving this page"
          variant: warning

Behavior

• The dialog appears when the user attempts to navigate away from the page while the form is dirty (has unsaved changes)
• The title and message properties support localization by providing translations for different locales
• Use onConfirm to perform cleanup actions when the user chooses to discard changes
• Use onCancel to remind users to save their work or perform other actions when they choose to stay

On mobile, form initialValues templates can resolve {{ localStorage <key> }} and configuration values. Stored values are loaded into the configuration context before the form initializes.

Dirty state in action templates

Every named form exposes {{<formName>.dirty}} to action templates. The flag is true when current values differ meaningfully from the most recently loaded initialValues; null, undefined, and an empty string are treated as equivalent empty values. Programmatic setFields changes count as dirty, while framework normalization does not. The same corrected flag drives dirtyGuard.

- if: "{{myForm.dirty}}"
  then:
    - dialog:
        name: unsavedChanges
        component:
          component: Shared/UnsavedChangesDialog

Dirty state is available to actions, but not to component visibility or disabled templates.

Reloading initial values

Use - reload: myForm when server-side work makes a mounted form stale. Reload re-runs query-backed or templated initialValues, replaces the form values, updates its store entry, and resets the dirty baseline. It preserves the mounted component tree, so child state, scroll position, and focus remain intact. Any unsaved edits are discarded.

The target resolves in this order: reloadHandler, refreshHandler, then the form's name. refresh and reload remain independent even when they use the same handler name: refresh keeps current values, while reload replaces them.