https://github.com/tawashley/formalise
Quick and easy form and input validation bolstered by browser APIs
https://github.com/tawashley/formalise
error-handling form form-validation input input-validation javascript
Last synced: about 2 months ago
JSON representation
Quick and easy form and input validation bolstered by browser APIs
- Host: GitHub
- URL: https://github.com/tawashley/formalise
- Owner: tawashley
- Created: 2018-06-03T19:05:25.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2023-01-04T05:30:25.000Z (over 3 years ago)
- Last Synced: 2025-10-19T11:35:43.369Z (6 months ago)
- Topics: error-handling, form, form-validation, input, input-validation, javascript
- Language: JavaScript
- Homepage:
- Size: 2.25 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# formalise
[](https://travis-ci.org/tawashley/formalise)
Form and input validation built around browser APIs. **Zero dependencies, 1.7kb bundle**
```
npm i formalise --save
```
* [Examples](https://tawashley.github.io/formalise/)
* [Usage](#usage)
* [How it works](#how-it-works)
* [Browser support](#browser--polyfill-support)
* [Config](#config)
## Usage
If a bundler is being used, formalise can be imported using the ES2015 syntax. There is also a conventional bundle.
```js
// 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](https://github.com/tawashley/formalise/blob/master/src/polyfill.validityState.js)
* [Object.assign](https://github.com/tawashley/formalise/blob/master/src/polyfill.objectAssign.js)
* [Array.find](https://github.com/tawashley/formalise/blob/master/src/polyfill.arrayFind.js)
```js
import 'formalise/dist/polyfill.validityState.js';
import 'formalise/dist/polyfill.objectAssign.js';
import 'formalise/dist/polyfill.arrayFind.js';
```
[polyfill.io](polyfill.io) can also help with Object.assign, Array.find if required
```html
```
## Config
```js
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.