Skip to main content

Form

The Form component is a container that manages form fields, handles validation, and coordinates form submission. It provides cross-shadow-DOM field registration and comprehensive form state management.

Overview​

Form provides a complete form management solution with:

  • Automatic field registration across Shadow DOM boundaries
  • Built-in validation support
  • Form submission handling
  • Field value collection
  • Reset functionality
  • Validation state tracking

Basic Usage​

{
  uuid: "my-form",
  name: "registration_form",
  component_type: "form",
  childrenIds: ["name-input", "email-input", "submit-button"],
  input: {
    validateOnBlur: { type: "boolean", value: true },
    preventInvalidSubmission: { type: "boolean", value: true }
  },
  event: {
    onSubmitSuccess: `
      console.log('Form submitted:', EventData.values);
      $formSubmitted = true;
    `,
    onSubmitError: `
      console.error('Form error:', EventData.error);
      $formError = EventData.error;
    `
  }
}

Component Inputs​

PropertyTypeDefaultDescription
disabledbooleanfalseDisable all form fields
validateOnChangebooleanfalseValidate fields on change
validateOnBlurbooleantrueValidate fields on blur
preventInvalidSubmissionbooleantruePrevent submission if invalid
resetOnSuccessbooleanfalseReset form after successful submission
actionstring-Form action URL
methodstring'POST'HTTP method: 'GET', 'POST', etc.

Events​

onSubmitSuccess​

Triggered: When form submits successfully

EventData:

{
  formData: FormData   // Native FormData object
  values: object       // Field values as object
}

Example:

event: {
  onSubmitSuccess: `
    const values = EventData.values;
    $submittedData = values;
    $formSubmitted = true;

    const response = await fetch('/api/register', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(values)
    });

    if (response.ok) {
      $successMessage = 'Registration complete!';
    }
  `
}

onSubmitError​

Triggered: When form submission fails

EventData:

{
  error: any  // Error details
}

onValidationChange​

Triggered: When form validation state changes

EventData:

{
  validationResult: object  // Validation details
}

onFieldChange​

Triggered: When any field value changes

EventData:

{
  field: object  // Changed field info
}

onReset​

Triggered: When form is reset

Form Methods​

The Form component exposes several methods:

  • getFieldsValue() - Get all form field values
  • setFieldsValue(values) - Set form field values programmatically
  • validate() - Validate all form fields
  • submit(customData?) - Submit the form programmatically
  • reset() - Reset the form to initial state
  • getFormState() - Get current form state summary

Common Patterns​

Registration Form​

{
  uuid: "registration-form",
  component_type: "form",
  childrenIds: ["name-field", "email-field", "password-field", "submit-btn"],
  input: {
    validateOnBlur: { type: "boolean", value: true },
    preventInvalidSubmission: { type: "boolean", value: true }
  },
  event: {
    onSubmitSuccess: `
      const values = EventData.values;
      $isSubmitting = true;

      try {
        const response = await RegisterUser(values);
        $registrationSuccess = true;
        navigateTo('dashboard');
      } catch (error) {
        $registrationError = error.message;
      } finally {
        $isSubmitting = false;
      }
    `
  }
}

See Also​