@upjs/facile-validator
v1.21.0TypeScript
Easy HTML form validator written in TypeScript with tree-shaking
0/weekUpdated 7 months agoMITUnpacked: 135.8 KB
Published by Ali Nazari
npm install @upjs/facile-validatorFacile Validator
[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![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.
Table of Contents
- Installation
- Usage
- Validate on Field Change
- Implementation in Frameworks
- Handling Events
- Available Validation Rules
- X-Prefixed Rules
- 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
attribute in the form will be validated.
$3
_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
in the options:`js
const v = new Validator(form, {
onFieldChangeValidation: true,
onFieldChangeValidationDelay: 1000 // 1 Second
}
`
$3
Use
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', ... }
`$3
- React.js
- _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:
-
-
-
- To attach a hook to these events, use
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.');
},
},
});
`---
####
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
});
`---
####
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
});
`---
####
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
});
`---
####
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
});
`---
####
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
option to false in the config object:`javascript
const v = new Validator(form, {
renderErrors: false,
});
`
Available Validation Rules:
- accepted
- alpha
- alpha-num
- alpha-num-dash
- bail
- between
- digits
- email
- ends-with
- int
- max
- min
- num-dash
- number
- nullable
- regex
- required
- size
- starts-with
- in
- ...
- Your rule?
---
$3
The field under validation (checkbox, radio) must be checked:
html
`---
$3
The field under validation must contain only alphabetic characters:
html
`Some valid inputs:
- Hello
- français
- سلام
---
$3
The field under validation must contain only alpha-numeric characters:
html
`Some valid inputs:
- abc123
- abc
- 123
---
$3
The field under validation must contain only alpha-numeric characters, dashes, and underscores:
html
`Some valid inputs
- abc-123
- abc_123
- abc123
- abc
- 123
---
$3
Stops running validation rules for the field after the first validation failure:
html
`_
rule will be processed and if it fails, other rules will not be processed._---
$3
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._
---
$3
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)_
---
$3
The field under validation must be an email:
html
`---
$3
The field under validation must end with the given substring:
html
`_Only the words that end with ies (technologies, parties, allies, ...) are accepted._
---
$3
The field under validation must be an integer (positive or negative):
html
`_You can also use
rule._---
$3
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
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._
---
$3
This rule is used for multiple purposes.
In the combination with the
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
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._
---
$3
The field under validation can be empty:
html
` 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.---
$3
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._
---
$3
The field under validation must be a number:
html
`---
$3
_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.
---
$3
The field under validation must not be empty:
html
`---
$3
This rule is used for multiple purposes.
In the combination with the
rule, the field under validation must be a number equal to the given number:`html
`_Only 1000 is accepted._
If used without
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._
---
$3
The field under validation must start with the given substring:
html
`_Only the words that start with app (apple, application, append, ...) are accepted._
---
$3
The field under validation must be in the list of the given arguments:
html
`_Only red or green or blue are valid inputs._
rule can also be used with a