Sulu Forms AJAX Validation

Frontend counterpart to the Sulu Forms Ajax Validation Bundle.

Installation

npm i @pawsitiwe/sulu-forms-ajax-validation

Usage

JavaScript

The JavaScript is required and is used for asynchronous live validation.

import { SuluAjaxForm } from '@pawsitiwe/sulu-forms-ajax-validation';

new SuluAjaxForm();

The constructor can accept two parameters:

1. form is the form element on which Sulu Ajax Form should be initialized. Default is document.querySelector('.ajax-form').
2. options is an object used to configure Sulu Ajax Forms. The default values are documented in the table below:

| Option | Typ | Default | Beschreibung | |------------------------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------| | classes | object | {  field: 'field',  fieldsWrapper: 'fields',  groupWrapper: 'check-radio-group',  errorContainer: 'error-container',  errorElement: 'error',  errorState: 'has-error',  submitting: 'submitting',  submitButton: 'submit',  apiErrorNotification: 'api-error',  confirmation: 'confirmation'} | Selectors used by Sulu Ajax Forms and states assigned to elements. | | disableOnSubmit | boolean | true | Disables the submit button during the submit request. | | scrollToFirstErrorOnSubmit | boolean | true | Smoothly scrolls to the first validation error after a failed submit. | | focusFirstErrorFieldOnSubmit | boolean | true | Focuses the first validation error field after a failed submit. | | animateConfirmation | boolean | true | Animates the confirmation message after a successful submit. | | additionalHeaders | object | {} | Additional header, like authorization for fetch request | | successRedirectUrl | string|null | null | Optional URL to redirect to after successful validation. JS option overrides form data attribute. | | allowCrossOriginRedirect | boolean | false | Allows redirects to different origins (e.g., thanks.mysite.com). Keep false for security unless needed. |

Form Events

successfullySubmitted

Fires after successful form submission. Validation passes and confirmation is shown (or redirect triggered).

form.addEventListener('successfullySubmitted', (event) => {
    const { valid, fields } = event.detail;
    console.log('Form submitted successfully');
});

submitInvalid

Fires after a failed form submission. Validation errors have been applied to the DOM.

form.addEventListener('submitInvalid', (event) => {
    const { response } = event.detail;
    // Custom handling: show toast, log analytics, etc.
    console.log('Errors:', response.fields);
});

Redirect Usage:

Via JS option (overrides data attribute):

new SuluAjaxForm(formElement, {
    successRedirectUrl: '/thank-you'
});

Via form data attribute (fallback if no JS option):

<form class="ajax-form" data-validation-url="/validate" data-success-redirect-url="/thank-you">
    ...
</form>

Cross-origin redirects:

For redirecting to a different origin (e.g., https://thanks.mysite.com), you must explicitly enable it:

new SuluAjaxForm(formElement, {
    successRedirectUrl: 'https://thanks.mysite.com/success',
    allowCrossOriginRedirect: true
});

Important: Cross-origin redirects have security implications:

• Session cookies will not be sent to the cross-origin thank-you page
• You must pass session data via URL parameters if needed (e.g., https://thanks.mysite.com/success?token=xyz)
• Same-origin redirects (default) maintain cookies automatically

When a successRedirectUrl is provided, the form redirects immediately after successful validation instead of showing the confirmation message.

Cross-Origin Requests

Session Handling

The library uses credentials: 'same-origin' for all AJAX validation and submission requests. This ensures session cookies are sent and received during the validation flow, maintaining your session state throughout the form interaction.

Same-origin validation endpoint (default):

// Validation endpoint: https://mysite.com/api/validate
// Session cookies are automatically maintained ✅
new SuluAjaxForm(formElement, {
    successRedirectUrl: '/thank-you'  // Same-origin redirect
});

Cross-origin redirects:

When redirecting to a different origin after successful validation, session cookies will not be transferred to the cross-origin page due to browser security policies.

new SuluAjaxForm(formElement, {
    successRedirectUrl: 'https://thanks.mysite.com/success',
    allowCrossOriginRedirect: true  // Must explicitly enable
});

Passing Session Data Cross-Origin

If you need to redirect to a cross-origin thank-you page with session context, pass data via URL parameters:

Backend approach (recommended):

Your validation endpoint can return session data:

{
    "valid": true,
    "sessionToken": "xyz789",
    "submissionId": "12345"
}

Frontend listens for the success event and builds the redirect URL:

const form = document.querySelector('.ajax-form');
new SuluAjaxForm(form, {
    allowCrossOriginRedirect: true
});

form.addEventListener('successfullySubmitted', (event) => {
    const { sessionToken, submissionId } = event.detail;
    const redirectUrl = `https://thanks.mysite.com/success?token=${sessionToken}&id=${submissionId}`;
    window.location.assign(redirectUrl);
});

Scss

@use "@pawsitiwe/sulu-forms-ajax-validation" as forms;

Usage

Mixins can either be included all at once (recommended) …

@include forms.all();

… or selectively (not recommended).

.example-form-class {
    .example-error-class {
        @include forms.api-error-notification();
    }
    .example-honeypot-field-class {
        @include forms.hide-honeypot-field();
    }
    // ...
}

Configuration

To configure the mixins, use the configure mixin. This must be included before using any other mixins.

@include forms.configure((...));

A full list of configuration options can be found at /src/styles/_config.scss.