Form Validation¶

A helper utility for easy front-end form validation, both inline (onBlur events) and on form submit.

Installation¶

This class is pre-installed and loaded asynchronously with Genesis out of the box.

Add import {HTMLFormValidator} from 'extensions/form-validation'; to your file.

Example Usage¶

.mvt¶

<form id="my-form" class="js-form-validator" action="post" action="/login.html">
    <div class="g-form-list__item">
        <label for="username-field">Username</label>
        <input id="username-field" type="text" name="username" placeholder="Username" required>
    </div>
    <div class="g-form-list__item">
        <label for="password-field">Password</label>
        <input id="password-field" type="password" name="password" required>
    </div>
    <div class="g-form-list__item">
        <button type="submit">Submit</button>
    </div>
</form>

.js¶

Initialize the HTMLFormValidator object:

Preferred asynchronous initialization:

(async () => {
    const form = document.getElementById('my-form');

    if (!form) {
        return;
    }

    const {HTMLFormValidator} = await import('extensions/form-validation');

    new HTMLFormValidator({
        beforeSubmit: (htmlFormValidator, event) => {
            console.log('class instance', htmlFormValidator);
            console.log('event instance', event);
        },
        fieldContainer: '.g-form-list__item',
        formElement: form,
        onValidate: (htmlFormValidator, event) => {
            console.log('class instance', htmlFormValidator);
            console.log('event instance', event);
        }
    });
})();

Alternatively:

import {HTMLFormValidator} from 'extensions/form-validation';

new HTMLFormValidator({
    beforeSubmit: (htmlFormValidator, event) => {
        console.log('class instance', htmlFormValidator);
        console.log('event instance', event);
    },
    fieldContainer: '.g-form-list__item',
    formElement: '#my-form',
    onValidate: (htmlFormValidator, event) => {
        console.log('class instance', htmlFormValidator);
        console.log('event instance', event);
    }
});

Options¶

The HTMLFormValidator class can take an object for the first parameter to override any of the default configuration settings.

The following table defines the available options:

Name	Type	Description	Default Value
beforeSubmit	Function Null	Reference to a function to be called after form validation and before form submission. The function receives the class object as the first parameter and the event object as the second parameter.	`null`
errorClass	String	Class to apply to error message elements.	`'g-form-field__error'`
errorHideClass	String	Class to hide error message elements.	`'u-hidden'`
errorInsertPosition	String	Position to insert error messages relative to the field container element. Value must be one of the following: `'beforebegin'` `'afterbegin'` `'beforeend'` `'afterend'` See insertAdjacentElement documentation for more details on positioning.	`'beforeend'`
errorMessages	Object	Override any or all of the form field error messages per tag name and type.	See Error Messages mapping table below for default values.
fieldContainer	String	The container element for form fields. If default, targets the field parent element.	`''`
fieldContainerErrorClass	String	Class to apply to form fields container element on validation errors.	`'has-error'`
formElement	HTMLElement String	The form element being validated, must be a DOM element. This is a required option.
labelRequiredSelector	String	Selector to indicate label has required form field.	`'.is-required'`
onValidate	Function Null	Reference to a function to be called during form validation, MUST return a Boolean value. The function receives the class object as the first parameter and the event object as the second parameter.	`null`
scrollToFirstError	Boolean	Scroll to first error after form validation runs.	`true`
scrollToOptions	Object	See scrollIntoViewOptions documentation for available options.	`{behavior: 'smooth', block: 'center'}`

Error Messages¶

The table below contains the mapping of the default error messages object for the form field tags and types.

Key	Value
DEFAULT	Please enter a value
INPUT_CHECKBOX	Please check the checkbox
INPUT_DATE	Please enter a valid date
INPUT_EMAIL	Please enter a valid email
INPUT_FILE	Please select a valid file
INPUT_NUMBER	Please enter a valid number
INPUT_PASSWORD	Please enter a valid password
INPUT_RADIO	Please select an option
INPUT_RANGE	Please select a range
INPUT_SEARCH	Please enter a value
INPUT_TEL	Please enter a valid telephone number
INPUT_TEXT	Please enter a value
INPUT_URL	Please enter a valid URL
SELECT	Please select an option
TEXTAREA	Please enter a value

Data Attributes¶

The following data attributes can be used to modify the behavior of the validation functionality.

Disable Blur¶

Place the data-error-disable-blur data attribute on a required form field element to disable the inline validation that occurs onBlur. This is useful for fields that you do not want to display an error message if a user focuses and blurs the field.

<input id="disable-blur-error" type="text" name="my_field" data-error-disable-blur required>

Custom Error Message¶

Place the data-error-message data attribute on a required form field element to display a specific error message for the field.

<input id="disable-blur-error" type="text" name="my_field" data-error-message="Custom error message!" required>

Miva Customer Fields Forms¶

Place the data-form-toggle-fields data attribute on a form element to support native Miva toggle details functionality. This will utilize Miva's ToggleDetails object settings for the secondary customer fields (Ship To or Bill To) to add inline validation if the fields are shown and remove the inline validation if the fields are hidden.

<form action="https://www.example.com" class="js-form-validator" data-form-toggle-fields>
    <!-- Form content here -->
</form>

HTMLFormsValidator¶

HTMLFormsValidator: Example Usage¶

import {HTMLFormsValidator} from 'extensions/form-validation';

new HTMLFormsValidator('.js-forms-to-be-validated');

// OR more advanced...

new HTMLFormsValidator('.js-forms-to-be-validated', {
    beforeSubmit: (htmlFormValidator, event) => {
        console.log('class instance', htmlFormValidator);
        console.log('event instance', event);
    },
    fieldContainer: '.g-form-list__item',
    onValidate: (htmlFormValidator, event) => {
        console.log('class instance', htmlFormValidator);
        console.log('event instance', event);
    }
});

HTMLFormsValidator: Options¶

The HTMLFormsValidator class can takes two parameters, a form-selector-string and then an object to override any of the default configuration settings. The following table defines the available options:

This class basically selects all of the matching formSelector form-elements, and then performs a new HTMLFormValidator({...{formElement}, ...this.options}); for each of the forms that were found with the options that are passed in.

Name	Type	Description	Default Value
formSelector	String	Selector to indicate label has required form field.	`'.js-form-validator'`
options	Object	See HTMLFormValidator's options for the available options.	`{}`