Form Actions

Actions for managing form state and validation.

validate_form

Validates a form and returns validation results.

Syntax

json

{
  "type": "validate_form",
  "formId": "myForm"
}

Properties

Property	Type	Required	Description
`formId`	string	Yes	Form identifier to validate
`onValid`	array	-	Actions if validation passes
`onInvalid`	array	-	Actions if validation fails

Examples

Basic validation:

json

{
  "type": "Button",
  "text": "Submit",
  "events": {
    "on_click": [
      {
        "type": "validate_form",
        "formId": "contactForm",
        "onValid": [
          { "type": "call_api", "api": "submitContact" }
        ],
        "onInvalid": [
          { "type": "show_toast", "message": "Please fix the errors", "level": "warning" }
        ]
      }
    ]
  }
}

With form definition:

json

{
  "type": "Form",
  "id": "userForm",
  "children": [
    {
      "type": "Field",
      "fieldType": "text",
      "name": "email",
      "label": "Email",
      "required": true,
      "validation": [
        { "type": "email", "message": "Enter a valid email" }
      ]
    },
    {
      "type": "Field",
      "fieldType": "password",
      "name": "password",
      "label": "Password",
      "required": true,
      "validation": [
        { "type": "minLength", "value": 8, "message": "At least 8 characters" }
      ]
    },
    {
      "type": "Button",
      "text": "Register",
      "events": {
        "on_click": [
          {
            "type": "validate_form",
            "formId": "userForm",
            "onValid": [
              { "type": "call_api", "api": "register", "params": { "data": "{{form.userForm}}" } }
            ]
          }
        ]
      }
    }
  ]
}

Validation before navigation:

json

{
  "type": "validate_form",
  "formId": "settingsForm",
  "onValid": [
    { "type": "call_api", "api": "saveSettings" },
    { "type": "navigate", "route": "/dashboard" }
  ],
  "onInvalid": [
    { "type": "show_toast", "message": "Please complete all required fields", "level": "warning" }
  ]
}

reset_form

Resets a form to its initial state.

Syntax

json

{
  "type": "reset_form",
  "formId": "myForm"
}

Properties

Property	Type	Required	Description
`formId`	string	Yes	Form identifier to reset
`values`	object	-	Optional values to reset to

Examples

Basic reset:

json

{
  "type": "Button",
  "text": "Clear",
  "variant": "ghost",
  "events": {
    "on_click": [
      { "type": "reset_form", "formId": "searchForm" }
    ]
  }
}

Reset to specific values:

json

{
  "type": "reset_form",
  "formId": "filterForm",
  "values": {
    "status": "all",
    "dateRange": "last7days",
    "category": ""
  }
}

Reset after successful submit:

json

{
  "type": "call_api",
  "api": "createItem",
  "params": { "data": "{{form.newItemForm}}" },
  "on_success": [
    { "type": "show_toast", "message": "Item created!", "level": "success" },
    { "type": "reset_form", "formId": "newItemForm" }
  ]
}

Reset on dialog close:

json

{
  "type": "Button",
  "text": "Cancel",
  "events": {
    "on_click": [
      { "type": "reset_form", "formId": "editForm" },
      { "type": "close_dialog", "id": "editDialog" }
    ]
  }
}

Form Data Access

Form data is accessible via the form namespace:

json

{
  "type": "call_api",
  "api": "submitForm",
  "params": {
    "formData": "{{form.myForm}}",
    "email": "{{form.myForm.email}}",
    "name": "{{form.myForm.name}}"
  }
}

Form State Variables

Variable	Type	Description
`form.<id>`	object	Complete form data
`form.<id>.<field>`	any	Specific field value
`form.<id>.$valid`	boolean	Form validity state
`form.<id>.$dirty`	boolean	Has form been modified
`form.<id>.$errors`	object	Field error messages

Examples

Conditional submit button:

json

{
  "type": "Button",
  "text": "Submit",
  "disabled": "{{!form.myForm.$valid}}",
  "events": {
    "on_click": [
      { "type": "call_api", "api": "submit" }
    ]
  }
}

Show unsaved changes warning:

json

{
  "type": "Conditional",
  "conditions": [
    {
      "when": "{{form.settingsForm.$dirty}}",
      "render": {
        "type": "Alert",
        "variant": "warning",
        "title": "Unsaved Changes",
        "message": "You have unsaved changes"
      }
    }
  ]
}

Display validation errors:

json

{
  "type": "Conditional",
  "conditions": [
    {
      "when": "{{form.myForm.$errors.email}}",
      "render": {
        "type": "Text",
        "text": "{{form.myForm.$errors.email}}",
        "className": "text-red-500 text-sm"
      }
    }
  ]
}

Common Patterns

Submit and Reset Pattern

json

{
  "type": "Flex",
  "gap": "md",
  "children": [
    {
      "type": "Button",
      "text": "Reset",
      "variant": "ghost",
      "events": {
        "on_click": [
          { "type": "reset_form", "formId": "myForm" }
        ]
      }
    },
    {
      "type": "Button",
      "text": "Submit",
      "events": {
        "on_click": [
          {
            "type": "validate_form",
            "formId": "myForm",
            "onValid": [
              { "type": "set_loading", "key": "submitting", "value": true },
              {
                "type": "call_api",
                "api": "submit",
                "params": { "data": "{{form.myForm}}" },
                "on_success": [
                  { "type": "show_toast", "message": "Submitted!", "level": "success" },
                  { "type": "reset_form", "formId": "myForm" }
                ],
                "onComplete": [
                  { "type": "set_loading", "key": "submitting", "value": false }
                ]
              }
            ]
          }
        ]
      }
    }
  ]
}

Multi-Step Form Validation

json

{
  "type": "Button",
  "text": "Next",
  "events": {
    "on_click": [
      {
        "type": "validate_form",
        "formId": "step{{state.currentStep}}Form",
        "onValid": [
          { "type": "update_state", "path": "currentStep", "value": "{{state.currentStep + 1}}" }
        ],
        "onInvalid": [
          { "type": "show_toast", "message": "Please complete this step", "level": "warning" }
        ]
      }
    ]
  }
}

Confirm Before Reset

json

{
  "type": "Button",
  "text": "Clear All",
  "variant": "ghost",
  "events": {
    "on_click": [
      {
        "type": "show_dialog",
        "id": "confirmReset",
        "title": "Clear Form",
        "message": "Are you sure you want to clear all fields?",
        "buttons": [
          {
            "label": "Cancel",
            "variant": "ghost",
            "action": [{ "type": "close_dialog", "id": "confirmReset" }]
          },
          {
            "label": "Clear",
            "variant": "destructive",
            "action": [
              { "type": "reset_form", "formId": "myForm" },
              { "type": "close_dialog", "id": "confirmReset" }
            ]
          }
        ]
      }
    ]
  }
}

Best Practices

Always validate before submit - Prevent invalid API calls
Show clear error messages - Help users fix issues
Reset forms appropriately - Clear after success, preserve on error
Disable submit while invalid - Use disabled="{{!form.id.$valid}}"
Track dirty state - Warn about unsaved changes