🛡️
Vue-input-validator
What is this package all about?
By using this package, you can create input validators only with the help of a single directive without the need for additional settings; You can create a custom validator with the help of regex or functions, and it will automatically append to your textbox!
- Lightweight (4kb gzipped)
☁️ - Simple API
🎈 - Customizable
🧰 - Support for async & ajax validation
👊 - Easy to use
✔️ - Mobile-friendly
📱 - TypeScript support
🔒
Table of Contents
InstallationUsagePlugin optionsUser optionsAsynchronous validationHooksStylingSecurityCaveatsExamplesContribution
Installation
npm
npm i @mediv0/validator
yarn
yarn add @mediv0/validator
Usage
You can import and use the package like below:
import Vue from "vue;
import validator from @mediv0/validator;
Vue.use(validator, options);
Add these lines to your component:
<template>
<div id="App">
<input v-validator="validatorOptions" />
</div>
</template>
<script>
export default {
data()
{
return {
validatorOptions: { ... }
}
}
}
</script>
the v-validator directive will wrap your input in a span container and also adds the input-validator component to the span container. (See the picture below)
For more information about validator options, please check: Plugin options and User options
Plugin options
| Property name | default value | description | is optional |
|---|---|---|---|
| name | validator | changing the name of directive |
|
| success | #2DE68F | color when validation is successful |
|
| unchecked | #979797 | default color when rendering the validator |
|
| failed | #FF4343 | color when validation fails |
|
You can pass these options while initiating the plugin.
Vue.use(validator, {
name: "name", // rename v-validator directive to v-name
// color options can be css values like: rgb, rgba, hex, hls etc....
success: "green",
failed: "red",
unchecked: "gray"
});
User options
These options are reactive component-level properties and can be changed anytime in your app.
key: string - default: undefiend
If you have multiple validator instances on your page, you can use this option to give them unique names and access those validators by their name across your app.
hideLines: boolean - default: false
With this option, you can show or hide the lines below your input.
hideLabels: boolean - default: false
With this option, you can show or hide the labels below your input based on the entered input.
circleSize: number - default: 8
With this option, you can change the size of the circle of each label (use px-pixle to set height & width).
disable: boolean - default: false
With this option, you can enable or disable the validator functionality.
items: Array<{ label: string; test: Function | RegExp }>
This option will take an Array of Objects that contain your validation rules.
onSuccess: Callback() => boolean - default: null
This option will take a callback and run it when all of the validations pass.
The object that is passing to the items property should have two keys: label and test
- label is a string value that describes your test.
- test can be a regex or function depending on your needs. You can implement any test (validation) and there are no restrictions in this regard.
Using test with function
items: [
{
label: "my test"
test: (val) => {
if (val === "test") {
return true;
} else {
return false;
}
}
}
],
Asynchronous validation
The validator component also supports async tests. For example, if you need to validate your info from a server you can use async tests.
Remember that async tests must return boolean*
the below example will show you how to use async tests:
...
test: (val) => {
return new Promise((resolve, reject) => {
setTimeout(() => {
if (val === "reza") {
resolve(true);
} else {
reject(false);
}
}, 2000);
})
},
...
const options = {
items: [ ... ],
debounce: 500 // in milliseconds
}
the debounce works with both sync and async.
A list of all options is also available for you to check options example
onError
If you don't want to show labels or lines below your input or if you just want to validate your input on some events or special conditions, you can set onError options in your option object.
onError options:
| Option name | default value | description | possible values |
|---|---|---|---|
| msg | undefiend | The message that will be displayed when validation fails |
strings |
| color | default plugin color | This can be any color. If not specified, it will use the default color |
any color |
| highlight | false | show red border highlight around your input when validation fails |
true - false |
| direction | ltr | direction of your error message |
ltr - rtl |
🚨
when using onError:
- Options: disable, hideLables, hideLines, circleSize, onSuccess, debounce will not work anymore.
- isValid and showError hooks are disabled when using onError.
- onError will expose
validate hookthat you can use to validate your inputs.
This is useful when you don't want to show the default style of validator under your component and disable its real-time validation checking.
A list of all options is also available for you to check options example
IchecksProp for type checking.
import { IchecksProp } from "@mediv0/vue-input-validator";
...
validatorOptions: IchecksProp = { ... ]
...
Hooks
there are 3 hooks that will be exposed on Vue instance. These hooks are global and can be accessed across your app.
$validator.isValid(key): boolean
Checks if the validation is done or not - Only works when you haven't set onError in your options.
isValid takes an argument, the key of your option, and checks if that option is passed or not.
example
...
data() {
return {
options: {
key: "email",
...
}
}
},
methods: {
login() {
if(this.$validator.isValid("email")) {
this.sendRequest();
} else {
// access denied
}
}
}
...
$validator.showError(key?): void
Changes all test labels that have not been validated to red - Only works when you haven't set onError in your options because there are no labels when using onError.
If you don't pass the key to this function, every input that uses the v-validator directive will turn red. but if you pass the key to this function, only the specified key will turn red if their tests fail.
example
...
methods: {
submitForm() {
if(this.$validator.isValid()) {
this.sendRequest();
} else {
// every input that use v-validator with turn red
this.$validator.showError();
}
}
}
...
$validator.validate(...keys): Promise<boolean[]>
Use this function to validate your forms (inputs) or events - Only works when onError is set in your options object.
This function will return a promise of key-value pairs after all validations are done. Also if you want to chain multiple validations you can pass their keys as an argument and get the result of validations in return.
If validation fails, validate will show your error under bonded input.
usage:
data() {
return {
emailOptions: {
key: "email",
...
onError: {
msg: "email validation failed, try again",
}
},
phoneOption: {
key: "phone",
...
onError: {
msg: "please enter valid phone",
}
}
}
},
methods: {
async login() {
const result = await this.$validator.validate("email", "phone");
console.log(result);
/*
get the result of validations in a object
result = {
email: true,
phone: false
}
*/
}
}
Take note that if you chain multiple tests inside an option (take the email option in the example above). the v-validator will execute all of your tests and combine their result in one boolean value. Because of this if only one of your tests in that chain fails, the entire option validation will fail too.
email: {
items: [
{
label: "this will fail",
test: () => false
},
{
label: "second",
test() => true
}
]
}
methods: {
async login() {
await this.$validator.validate("email");
// email wil fail because first test in its chain will fail
}
}
Check Examples to get started with this package
Styling
You can control the basic styles with plugin options. However, if you want more customization, you can overwrite validator styles in your CSS. Check style.scss to get familiar with the structure.
Responsive
As we know validator directive will create a span container and inject your input & validator component into it. This span will have display: inline-block and width: 100% as its default styling for responsive purposes. Also, font-family and font-size are inherited from their parent. So if you want to control font size or font-family of validator component you can create a wrapper around your input and put your styles in it.
example
<div class="App">
<div class="container">
<input v-validator="options" />
</div>
</div>
<style>
.container {
width: 400px;
font-family: "Poppin";
}
</style>
Security
If you are using this package to validate password input, it's better to set hideLabels to true in your login page to prevent an attacker to see your rules or something like that.
Caveats
The validator component will be injected into the page after bonded element inserts, because of that, this.$validator functions won't work on created lifecycle hook.
You can access it in the mounted function like the example below to get the data on page load.
<template>
div v-if="isDataValid"> ... </div>
</template>
data() {
isDataValid: "..."
}
mounted() {
this.isDataValid = this.$validator.isValid();
}
Examples
Check example folder or codeandbox! for more examples.
Contribution
- [Fork the project]
- Create your feature branch (
git checkout -b new-feature-branch) - Commit your changes (
git commit -am 'add new feature') - Push to the branch (
git push origin new-feature-branch) - Submit a pull request!
Feel free to request new features!
License
Todo
- Vue 3
- more options
- caching system
- async tests
- validation chain
- buit in validations
- debounce option
12k Jan 4, 2023
1.7k Dec 21, 2022
1.2k Dec 21, 2022
948 Dec 31, 2022
31 Nov 25, 2022
3 Feb 24, 2022
314 Dec 26, 2022
25 Jul 20, 2022
314 Dec 26, 2022
65 Dec 29, 2022
8 Jul 25, 2022
2 Sep 2, 2022
16 Dec 15, 2022
976 Dec 30, 2022
4 Nov 30, 2021
5 Dec 15, 2022
16 Jun 10, 2022
3 May 18, 2022
4 May 3, 2022
14 Jan 3, 2023