# Facile Validator
[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[](https://github.com/upjs/facile-validator/actions/workflows/verify.yml)
[![License][license-src]][license-href]
Robust Frontend Form Validation, inspired by Laravel Validation, Built for Simplicity of Use 😋
Facile (French word for "easy", pronounced `fa·sil`) is an HTML form validator that is inspired by Laravel's validation style and is designed for simplicity of use.
**[DEMO](https://upjs.github.io/facile-validator/)**
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Validate on Field Change](#validate-on-field-change)
- [Implementation in Frameworks](#implementation-in-frameworks)
- [Handling Events](#handling-events)
- [Available Validation Rules](#available-validation-rules)
- [X-Prefixed Rules](#x-prefixed-rules)
- [Localization](#localization)
> Note: This package does not include any polyfills. If you want to use in old environments, add this package to your project's config transpiling list.
>
## Installation
```bash
npm i @upjs/facile-validator
# or
yarn add @upjs/facile-validator
```
## Usage
HTML:
```html
```
The rules for each field are separated with a pipe character (vertical line) `|`. In this example, we've assigned 4 rules for that `input`:
- bail
- required
- number
- between (with two arguments: 1 and 10)
JavaScript:
```javascript
import { Validator, enLang as en } from '@upjs/facile-validator';
// Select the container element that contains the fields
const form = document.querySelector('form');
// Create an instance of Validator for the container element
const v = new Validator(form, {
lang: en,
});
form.addEventListener('submit', (e) => {
e.preventDefault();
// Call validate method to start validation
v.validate();
});
// Handle error-free validation
v.on('validation:success', () => {
alert('Nice! The form was validated without any errors');
console.log(v.values());
});
// Handle failed validation
v.on('validation:failed', () => {
alert('Oops! There are some errors in the form.');
});
```
Now every input with `data-rules` attribute in the `form` will be validated.
### Validate on Field Change
_New in version 1.6_
By default, the validation starts when the `validate` method is called. If you want to validate a field as soon as it changes (e.g. when user starts typing) you can set the value of `onFieldChangeValidation` option to `true` in the validator's options:
```js
const v = new Validator(form, {
onFieldChangeValidation: true,
}
```
By doing this, the validation starts for the field that being changed after 500ms delay. However, you can change this delay by setting `onFieldChangeValidationDelay` in the options:
```js
const v = new Validator(form, {
onFieldChangeValidation: true,
onFieldChangeValidationDelay: 1000 // 1 Second
}
```
### Getting Field Values
Use `values()` method from the validator to get the values of all fields in the form:
```javascript
const values = v.values();
console.log(values);
// { field1: 'value1', field2: 'value2', ... }
```
### Implementation in Frameworks
- [React.js](/misc/code-examples/react.md)
- _Others soon..._
## Handling Events
When the validation starts, ends, succeeds or fails, there are easy ways to handle these events. We do this with the help of the **Hooks**.
A hook is simply a function that you define to be executed when a particular event occurs.
There are five type of events that can be handled with the hooks:
- [`validation:start`](#validationstart)
- [`validation:end`](#validationend)
- [`validation:success`](#validationsuccess)
- [`validation:failed`](#validationfailed)
- [`field:error`](#fielderror)
To attach a hook to these events, use `on` method:
```javascript
v.on(event_name, () => {
// This function will be executed when the respective event occurs.
});
```
You can also attach those hooks in the config object:
```javascript
const v = new Validator(form, {
// ...
on: {
'validation:success': () => {
alert('Success! Form validated with no errors');
},
'validation:failed': () => {
alert('failed.');
},
},
});
```
---
#### `validation:start`
As you might have guessed, this event will occur when the validation starts:
```javascript
v.on('validation:start', (form) => {
// This function will be executed when the validation starts
});
```
---
#### `validation:end`
This event will occur when the validation ends, no matter if it was successful or not:
```javascript
v.on('validation:end', (form, isSuccessful) => {
// This function will be executed when the validation ends
});
```
---
#### `validation:success`
This event will occur when the validation ends with no errors:
```javascript
v.on('validation:success', (form) => {
// Do something after successful validation e.g. send the form-data to the server
});
```
---
#### `validation:failed`
This event will occur when the validation ends while there are some errors in the form:
```javascript
v.on('validation:failed', (form) => {
// Notify the user to fix the form
});
```
---
#### `field:error`
When a particular field has errors, you can handle the errors with this event:
```javascript
v.on('field:error', (form, field, errors) => {
errors.forEach((error) => {
console.log(error.args);
console.log(error.message);
console.log(error.rule);
console.log(error.element);
});
});
```
This is a good place to display errors in your own format. By default, the validator automatically shows error messages below each input. However, you can disable this feature by setting `renderErrors` option to `false` in the config object:
```javascript
const v = new Validator(form, {
renderErrors: false,
});
```
## Available Validation Rules:
- [accepted](#accepted)
- [alpha](#alpha)
- [alpha-num](#alpha-num)
- [alpha-num-dash](#alpha-num-dash)
- [bail](#bail)
- [between](#between)
- [digits](#digits)
- [email](#email)
- [ends-with](#ends-with)
- [int](#int)
- [max](#max)
- [min](#min)
- [num-dash](#num-dash)
- [number](#number)
- [nullable](#nullable)
- [regex](#regex)
- [required](#required)
- [size](#size)
- [starts-with](#starts-with)
- [in](#in)
- ...
- [Your rule?](https://github.com/upjs/facile-validator/pulls)
---
### accepted
The field under validation (checkbox, radio) must be checked:
```html
```
---
### alpha
The field under validation must contain only alphabetic characters:
```html
```
Some valid inputs:
- Hello
- français
- سلام
---
### alpha-num
The field under validation must contain only alpha-numeric characters:
```html
```
Some valid inputs:
- abc123
- abc
- 123
---
### alpha-num-dash
The field under validation must contain only alpha-numeric characters, dashes, and underscores:
```html
```
Some valid inputs
- abc-123
- abc_123
- abc123
- abc
- 123
---
### bail
Stops running validation rules for the field after the first validation failure:
```html
```
_`required` rule will be processed and if it fails, other rules will not be processed._
---
### between
The field under validation must be a number between the given range:
```html
```
_The numbers lower than 1 and higher than 10 are not accepted._
---
### digits
The field under validation must be a number with the given length:
```html
```
_Only a number with the length of 10 is accepted (e.g. 1234567890)_
---
### email
The field under validation must be an email:
```html
```
---
### ends-with
The field under validation must end with the given substring:
```html
```
_Only the words that end with ies (technologies, parties, allies, ...) are accepted._
---
### int
The field under validation must be an integer (positive or negative):
```html
```
_You can also use `integer` rule._
---
### max
This rule is used for multiple purposes.
In the combination with the `number` rule, the field under validation must be a number less than or equal to the given number:
```html
```
_Only a number less than or equal to 50 are accepted._
If `max` is used without `number` rule, the field under validation is considered as a `string` and then the field under validation must be a string with a maximum length of the given number:
```html
```
_Only strings with the length of 5 or less are accepted._
---
### min
This rule is used for multiple purposes.
In the combination with the `number` rule, the field under validation must be a number greater than or equal to the given number:
```html
```
_Only a number greater than or equal to 50 will be accepted._
If `min` rule is used without `number` rule, the field under validation is considered as a string and then The field under validation must be a string with a minimum length of the given number.
```html
```
_Only strings with the length of 5 or higher will be accepted._
---
### nullable
The field under validation can be empty:
```html
```
`min` rule will not be processed unless the field is filled. Note that the rules order is important. In this example, if `nullable` rule comes after `min` rule, the validator first processes `min` rule and then `nullable` rule.
---
### num-dash
The field under validation must contain only numeric characters, dashes, and underscores:
```html
```
_1000, 123-456, 123_456 are some valid inputs for this rule._
---
### number
The field under validation must be a number:
```html
```
---
### regex
_New in version 1.1_
The field under validation must match the given regular expression:
```html
```
To handle the regex rule in a more convenient way, see [#x-prefixed-rules](#x-prefixed-rules).
---
### required
The field under validation must not be empty:
```html
```
---
### size
This rule is used for multiple purposes.
In the combination with the `number` rule, the field under validation must be a number equal to the given number:
```html
```
_Only 1000 is accepted._
If used without `number` rule, the field under validation is considered as a string and then the field under validation must be a string with the exact length of the given argument:
```html
```
_Only the strings with the length of 5 are accepted._
---
### starts-with
The field under validation must start with the given substring:
```html
```
_Only the words that start with app (apple, application, append, ...) are accepted._
---
### in
The field under validation must be in the list of the given arguments:
```html
```
_Only red or green or blue are valid inputs._
`in` rule can also be used with a `
