formalise

Form and input validation built around browser APIs. Zero dependencies, 1.7kb bundle

npm i formalise --save

• Examples
• Usage
• How it works
• Browser support
• Config

Usage

If a bundler is being used, formalise can be imported using the ES2015 syntax. There is also a conventional bundle.

// ES2015 module
import formalise from 'formalise';

formalise.addForm({
    form: document.querySelector('[data-formalise-example]'),
});

This will add the form element [data-formalise-example] to use formalise validation.

How it works

formalise itself doesn't do the heavy lifting in terms of form validation, rather hooking into native browser APIs whilst adding a few quality of life features.

Once .addForm is called, the following occurs:

• novalidate attribute is added to the form
• The class is-pristine is added to all inputs

Depending one the config, when either the input or form is validated the following occurs:

• The class is-pristine is replaced with is-dirty if it's the first time checking the status of an input
• The input is checked to see if it's valid using HTMLInputElement.validity.valid
• The class is-valid or is-invalid is added to the input depending on it's validity status
• If inputParentSelector config value is provided, the parent element is found and the class is-valid or is-invalid is added to the element.

The above classes can be hooked into and used to style valid, invalid inputs.

Browser / polyfill support

To help aid in any issues, formalise does come included with a small subset of polyfills that can be used. These are opt-in and will require including seperately over the main bundle.

• Validity State
• Object.assign
• Array.find

import 'formalise/dist/polyfill.validityState.js';
import 'formalise/dist/polyfill.objectAssign.js';
import 'formalise/dist/polyfill.arrayFind.js';

polyfill.io can also help with Object.assign, Array.find if required

<script src="//cdn.polyfill.io/v2/polyfill.js?features=Array.prototype.find,Object.assign"></script>

Config

formalise.addForm({
    form: null,
    validateOn: {
        blur: true
    },
    submitFormWhenValid: false,
    onInputBlur: function() {},
    onFormSubmit: function() {},
    inputParentSelector: null,
    focusOnFirstInvalidInput: true
});

form

Type: HTMLFormElement Default: null

The form to hook validation into, this is required.

validateOn

Type: Object

validateOn.blur

Type: Object Default: true

Controls whether a single input should be validated when the input loses focus.

submitFormWhenValid

Type: Boolean Default: false

Sets whether the form should be submitted once valid. The 'onFormSubmit' handler is called before form is submitted.

By default, the form will need to be submitted manually inside the provided 'onFormSubmit'. If no submit handler is provided and the form is valid, by default it will submit the form.

onInputBlur

Type: Function Default: function(inputElement, isInputValid, inputValidityStatus) {}

Handler for when an input loses focus and the 'blur' event is fired. Passed into it is the input element the event was fired on, a boolean for if the input is valid and the complete validity status object of the input.

onFormSubmit

Type: Function Default: function(formIsValid, inputList) {}

Handler for when the form submit event is fired. Passed into it is a boolean for if the form is valid and an array of all inputs in the form.

inputParentSelector

Type: String Default: null Example .input-parent

A selector for a parent of the input can be provided that adds the same validation state classes (such as is-valid, is-invalid) to a parent element of the input. If provided, the DOM will be traversed upwards and stop when it matches an element with the provided selector.

This can help for handling UI around inputs, such as validation states.

focusOnFirstInvalidInput

Type: Boolean Default: true

Whether or not to focus on the first invalid input in the form when the form is invalid.