Features
-
π¦ Just 4.4 KB gzipped - π©π»βπ» Rules are declarative
-
β¨ Any number of rules for each field -
β Flexible error handling and their display -
π Has possibility to validate multi-step forms -
βοΈ Configurable check queue -
π Easy to create and reuse your own rules -
β‘οΈ Based on LIVR(Language Independent Validation Rules) -
π Don't need Jquery.
Setup
Install the package
npm install formurai
yarn add formurai
JS
import Formurai from 'formurai';
// define rules
const rules = {
'login-email': ['required', 'email'],
};
// define errors for user, its optional
const errors = {
'login-email': {
REQUIRED: 'Email required',
WRONG_EMAIL: 'Email must be valid',
}
};
const form = document.querySelector('#login');
const validator = new Formurai(form);
validator.init(rules, errors);
As a key for the rules, you need to pass the name of the field to be validated. The field name must be unique within this form
HTML
<form id="login">
<section class="formurai-container">
<input name="login-email" type="email">
<span class="formurai-message"></span>
</section>
<button type="submit">Submit</button>
</form>
If you need to show errors in the interface, add the formurai-container class to the element to which you want to assign the error or success class (optional step).
To display an error, inside the container, define an element with the class formurai-message, errors that you pass during initialization will be displayed here (optional step).
CSS
.formurai-message {
display: none;
}
.formurai-error .formurai-message {
display: none;
}
.formurai-error input {
border: 1px solid red;
}
.formurai-success input {
border: 1px solid green;
}
When the form is submitted, or the checkForm method is called, the wrapper(.formurai-container) is assigned an error or success class.
Usage
Basic usage, you need to pass the form and rules.
/**
* @param {HTMLFormElement} form
* @param {Object} options
* @type {Formurai}
*/
const validator = new Formurai(form, options);
validator.init(rules);
Options
Option | Type | Default value | Description |
---|---|---|---|
errorClass | string | 'formurai-error' | The class that will be added to the field with an error |
successClass | string | 'formurai-success' | The class that will be added to the field with an success |
wrapperClass | string | 'formurai-container' | The wrapper class to which the error or success class will be added |
errorMessageClass | string | 'formurai-message' | The class of the element into which the error will be displayed must be inside the wrapperClass |
withWrapper | boolean | true | If you do not need to show error messages and it will be enough for you to add an error or success class to the field, set false |
autoTrim | boolean | true | Removes spaces before and after validated values |
vibrate | boolean | true | If an error occurs while submitting the form, a vibration is triggered. Support devices |
notSubmit | boolean | false | If you don't need to reload the page, after submitting the form, set true |
multiStep | boolean | false | If you need to validate a form with many steps, and each step needs to be validated separately. See multi-step example |
Methods
const validator = new Formurai(form);
init(rules, messages?, initialState?)
Initializes validator, error object and initialState, optional parameters, initialState work only in multi-step forms.
validator.init(rules)
destroy()
Destroys the validator and all associated event listeners (custom to). Also delete all added rules.
validator.destroy()
changeState(state)
Change current state in multi step form. The value must be a key with the rules for the current step
const rules = {
'step-1': {...stepRules},
'step-2': {...stepRules},
}
validator.changeState('step-2')
checkForm()
Manually run a form validation like
const nextStepButton = document.querySelector('.next-step');
nextStepButton.addEventListener('click', () => {
validator.checkForm();
if (validator.isFormValid) {
// go to the next step
}
})
addRule(rule)
Accepts object or array of objects with custom rules. Rules need to be added after initialization
const rules = {
password: 'strong_password'
}
const customRule = {
name: 'strong_password',
rules: [{length_between: [15, 20]}],
error: 'WEAK_PASSWORD'
}
validator.init(rules)
validator.addRule(customRule)
formData
Returns an object with data from the form
validator.formData // {name: 'Leonardo', email: '[email protected]'}
errors
Returns an object with error codes
validator.errors // {name: "REQUIRED", email: "WRONG_EMAIL"}
isFormValid
Returns the current state of form validation
validator.isFormValid // true | false
Events
validator.on(evt, callback);
formValid
This listener is triggered when the form is fully valid, useful if you need to send it in ajax, without reloading the page.
const sendForm = async () => {
await fetch('https://example.com', {
method: 'POST',
body: validator.formData // contain all form data
})
console.log('Your form has been submitted successfully')
}
validator.on('formValid', sendForm);
Rules
All rules are based on LIVR (Language Independent Validation Rules). So all the rules that you find here you can use in this validator
Most common rules
Rule | Example | Error |
---|---|---|
eq | name: {'eq': 'Snow'} | 'NOT_ALLOWED_VALUE' |
one_of | name: {'one_of': ['Snow', 'Tirion']} | 'NOT_ALLOWED_VALUE' |
login: 'email' | 'WRONG_EMAIL' | |
integer | age: 'integer' | 'NOT_INTEGER' |
min_length | login: { min_length: 2 } | 'TOO_SHORT' |
max_length | name: { max_length: 10 } | 'TOO_LONG' |
length_between | code: { length_between: [2, 10] | 'TOO_LONG' or 'TOO_SHORT' |
number_between | age: { 'number_between': [18, 95] } | 'TOO_HIGH' or 'TOO_LOW' or 'NOT_NUMBER' |
like | price: { like: ['^\w+?$', 'i'] } | 'WRONG_FORMAT' |
Examples
Roadmap
- Add a getter with a list of error messages
- Add a scroll method to error input
- Add a showError method to show errors from backend
- Implement 'formInvalid' and 'changeState' events
- Π‘over the code with tests