{"id":19873695,"url":"https://github.com/mediv0/vue-input-validator","last_synced_at":"2025-05-02T10:30:34.345Z","repository":{"id":52624405,"uuid":"340655756","full_name":"mediv0/vue-input-validator","owner":"mediv0","description":"🛡️ Highly extensible \u0026 customizable input validator for Vue 2","archived":false,"fork":false,"pushed_at":"2021-04-22T23:35:35.000Z","size":320,"stargazers_count":16,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-07T00:51:16.032Z","etag":null,"topics":["input-validation","javascript","regexp","validation","validator","vuejs"],"latest_commit_sha":null,"homepage":"https://nphgg.csb.app/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mediv0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-02-20T13:01:19.000Z","updated_at":"2024-11-02T14:41:42.000Z","dependencies_parsed_at":"2022-09-15T00:30:59.043Z","dependency_job_id":null,"html_url":"https://github.com/mediv0/vue-input-validator","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mediv0%2Fvue-input-validator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mediv0%2Fvue-input-validator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mediv0%2Fvue-input-validator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mediv0%2Fvue-input-validator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mediv0","download_url":"https://codeload.github.com/mediv0/vue-input-validator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252023117,"owners_count":21682134,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["input-validation","javascript","regexp","validation","validator","vuejs"],"created_at":"2024-11-12T16:19:37.261Z","updated_at":"2025-05-02T10:30:33.993Z","avatar_url":"https://github.com/mediv0.png","language":"TypeScript","funding_links":[],"categories":["Components \u0026 Libraries","UI Utilities [🔝](#readme)"],"sub_categories":["UI Utilities"],"readme":"# 🛡️ Vue-input-validator\n\n[demo!](https://nphgg.csb.app/m)\n\n[![Build](https://img.shields.io/circleci/build/github/mediv0/vue-input-validator/master)](https://img.shields.io/circleci/build/github/mediv0/vue-input-validator/master) [![codecov](https://codecov.io/gh/mediv0/vue-input-validator/branch/master/graph/badge.svg)](https://app.codecov.io/gh/mediv0/vue-input-validator) [![CodeFactor](https://www.codefactor.io/repository/github/mediv0/vue-input-validator/badge)](https://www.codefactor.io/repository/github/mediv0/vue-input-validator) [![license](https://img.shields.io/github/license/mediv0/vue-input-validator)](https://img.shields.io/github/license/mediv0/vue-input-validator) [![Maintainability](https://api.codeclimate.com/v1/badges/e541b825abb249aee993/maintainability)](https://codeclimate.com/github/mediv0/vue-input-validator/maintainability)\n\n## What is this package all about?\nBy 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!\n\n\u003cp align=\"left\"\u003e\n  \u003cimg width=\"500px\" src=\"https://i.imgur.com/j5fBZEj.gif\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"left\"\u003e\n  \u003cimg width=\"500px\" src=\"https://i.imgur.com/TGMuQov.gif\"\u003e\n\u003c/p\u003e\n\n- Lightweight (4kb gzipped) ☁️\n- Simple API 🎈\n- Customizable 🧰\n- Support for async \u0026 ajax validation 👊\n- Easy to use ✔️\n- Mobile-friendly 📱\n- TypeScript support 🔒\n\n\u003cbr /\u003e\n\n### Table of Contents\n\n-   [`Installation`](#installation)\n-   [`Usage`](#usage)\n-   [`Plugin options`](#plugin-options)\n-   [`User options`](#user-options)\n-   [`Asynchronous validation`](#Asynchronous-validation)\n-   [`Hooks`](#hooks)\n-   [`Styling`](#styling)\n-   [`Security`](#security)\n-   [`Caveats`](#caveats)\n-   [`Examples`](#examples)\n-   [`Contribution`](#contribution)\n\n\u003cbr /\u003e\n\n\n### Installation\n\nnpm\n```bash\nnpm i @mediv0/validator\n```\n\nyarn\n```bash\nyarn add @mediv0/validator\n```\n\n\u003cbr /\u003e\n\n\n### Usage\n\nYou can import and use the package like below:\n```javascript index.js\nimport Vue from \"vue;\nimport validator from @mediv0/validator;\n\nVue.use(validator, options);\n\n```\n\nAdd these lines to your component:\n```javascript\n\u003ctemplate\u003e\n    \u003cdiv id=\"App\"\u003e\n        \u003cinput v-validator=\"validatorOptions\" /\u003e\n    \u003c/div\u003e\n\u003c/template\u003e\n\n\u003cscript\u003e\nexport default {\n    data()\n    {\n        return {\n              validatorOptions: { ... } \n        }\n    }\n\n}\n\u003c/script\u003e\n\n```\nthe 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)\n\n![input validator component](https://i.imgur.com/WTqtTkW.jpg \"input validator component\")\n\nFor more information about validator options, please check:  [Plugin options](#plugin-options) and [User options](#User-options)\n\n\u003cbr /\u003e\n\n\n### Plugin options\n\n| Property name | default value |  description                                  | is optional   |\n| ------------- |:-------------:| :---------------------------------------------| :------------:|\n| name          | validator     | `changing the name of directive`               |      ✅      |       \n| success       | #2DE68F       | `color when validation is successful`         |      ✅      |       \n| unchecked     | #979797       | `default color when rendering the validator`  |      ✅      |       \n| failed        | #FF4343       | `color when validation fails`                 |      ✅      |        \n\n\n\n\nYou can pass these options while initiating the plugin.\n\n```javascript\n\nVue.use(validator, {\n    name: \"name\",    // rename v-validator directive to v-name\n    \n    // color options can be css values like: rgb, rgba, hex, hls etc....\n    success: \"green\",\n    failed: \"red\", \n    unchecked: \"gray\"\n});\n\n```\n\n\u003cbr /\u003e\n\n\n### User options\nThese options are reactive component-level properties and can be changed anytime in your app.\n\n\u003cbr /\u003e\n\n#### **`key: string  -  default: undefiend`**\nIf 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.\n\n#### **`hideLines: boolean  -  default: false`**\nWith this option, you can show or hide the lines below your input.\n\n#### **`hideLabels: boolean  -  default: false`**\nWith this option, you can show or hide the labels below your input based on the entered input.\n\n#### **`circleSize: number  -  default: 8`**\nWith this option, you can change the size of the circle of each label (use px-pixle to set height \u0026 width).\n\n#### **`disable: boolean  -  default: false`**\nWith this option, you can enable or disable the validator functionality.\n\n#### **`items:  Array\u003c{ label: string; test: Function | RegExp }\u003e`**\nThis option will take an Array of Objects that contain your validation rules.\n\n#### **`onSuccess:  Callback() =\u003e boolean  -  default: null`**\nThis option will take a callback and run it when all of the validations pass.\n\n\u003cbr /\u003e\n\nThe object that is passing to the items property should have two keys: `label` and `test`\n- **label** is a string value that describes your test.\n- **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.\n\n**`Using test with function`**\n🚨 If you want to pass the test property to the function, take note that this function must return a boolean type, also this function will take the current value of bonded input as its parameter.\n\n```javascript\nitems: [\n      {\n        label: \"my test\"\n        test: (val) =\u003e {\n              if (val === \"test\") {\n                  return true;     \n              } else {\n                  return false;\n              }\n          }\n      }\n],\n```\n\n\u003cbr /\u003e\n\n### Asynchronous validation\nThe validator component also supports async tests. For example, if you need to validate your info from a server you can use async tests.\n\n**Remember that async tests must return boolean***\n\nthe below example will show you how to use async tests:\n```javascript\n...\ntest: (val) =\u003e {\n    return new Promise((resolve, reject) =\u003e {\n        setTimeout(() =\u003e {\n            if (val === \"reza\") {\n                resolve(true);\n            } else {\n                reject(false);\n            }\n        }, 2000);\n    })\n},\n...\n```\n\n⚠️ You might notice that the async validation is activated every time user hits the keyboard, this would cause a performance issue if we are making an ajax request. To fix this issue you can use the denounce option. For example, we can set the debounce option to half a second (500 milliseconds), so that the validation is postponed until the user stops typing for half a second.\n\n```javascript\nconst options = {\n  items: [ ... ],\n  debounce: 500 // in milliseconds\n}\n```\nthe debounce works with both sync and async.\n\n\u003cbr /\u003e\n\nA list of all options is also available for you to check [options example](https://github.com/mediv0/vue-input-validator/blob/master/public/validatorOptions.ts)\n\n\u003cbr /\u003e\n\n### onError\nIf 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.\n\nonError options:\n\n| Option name   | default value          |  description                                                                    | possible values     |\n| ------------- |:----------------------:| :-------------------------------------------------------------------------------| :------------------:|\n| msg           | undefiend              | `The message that will be displayed when validation fails`                      |      strings        |       \n| color         | default plugin color   | `This can be any color. If not specified, it will use the default color`     |      any color      |       \n| highlight     | false                  | `show red border highlight around your input when validation fails`             |      true - false   |       \n| direction     | ltr                    | `direction of your error message`                                               |      ltr - rtl      |   \n\n## 🚨 when using onError:\n- **Options: disable, hideLables, hideLines, circleSize, onSuccess, debounce will not work anymore.**\n- **isValid and showError hooks are disabled when using onError.**\n- **onError will expose [`validate hook`](#$validator.isValid(key):-boolean) that you can use to validate your inputs.**\n\nThis is useful when you don't want to show the default style of validator under your component and disable its real-time validation checking.\n\nA list of all options is also available for you to check [options example](https://github.com/mediv0/vue-input-validator/blob/master/example/validatorOptions.ts)\n\n\n\u003cbr /\u003e\n\n\n⚠️ For typescript users, you can change your Object type to `IchecksProp` for type checking.\n```javascript\nimport { IchecksProp } from \"@mediv0/vue-input-validator\";\n\n...\n\nvalidatorOptions: IchecksProp = { ... ]\n\n...\n```\n\n\u003cbr /\u003e\n\n### Hooks\nthere are 3 hooks that will be exposed on Vue instance. These hooks are global and can be accessed across your app.\n\n#### `$validator.isValid(key): boolean`\nChecks if the validation is done or not - `Only works when you haven't set onError in your options.`\n\n\nisValid takes an argument, the key of your option, and checks if that option is passed or not.\n\n**example**\n```javascript\n...\n  data() {\n      return {\n          options: {\n              key: \"email\",\n              ...\n          }\n      }\n  },\n  methods: {\n      login() {\n          if(this.$validator.isValid(\"email\")) {\n              this.sendRequest();\n          } else {\n              // access denied \n          }\n      }\n  }\n...\n```\n\n\n#### `$validator.showError(key?): void`\nChanges 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.`\n\n\nIf 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.\n\n**example**\n```javascript\n...\n  methods: {\n      submitForm() {\n          if(this.$validator.isValid()) {\n              this.sendRequest();\n          } else {\n              // every input that use v-validator with turn red\n               this.$validator.showError(); \n          }\n      }\n  }\n...\n```\n\n\n#### `$validator.validate(...keys): Promise\u003cboolean[]\u003e`\nUse this function to validate your forms (inputs) or events - `Only works when onError is set in your options object.`\n\nThis 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.\n\n\n**If validation fails, validate will show your error under bonded input.**\n\nusage: \n```javascript\ndata() {\n    return {\n        emailOptions: {\n            key: \"email\",\n            ...\n            onError: {\n                msg: \"email validation failed, try again\",\n            }\n        },\n        phoneOption: {\n            key: \"phone\",\n            ...\n            onError: {\n                msg: \"please enter valid phone\",\n            }\n        }\n    }\n},\n\nmethods: {\n    async login() {\n        const result = await this.$validator.validate(\"email\", \"phone\");\n        console.log(result);\n\n        /*\n            \n            get the result of validations in a object\n            result = {\n                email: true,\n                phone: false\n            }\n\n        */\n    }\n}\n```\n\nTake 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.\n\n```javascript\n    email: {\n        items: [\n            {\n                label: \"this will fail\",\n                test: () =\u003e false\n            },\n            {\n                label: \"second\",\n                test() =\u003e true\n            }\n        ]\n    }\n\n    methods: {\n        async login() {\n            await this.$validator.validate(\"email\");\n            // email wil fail because first test in its chain will fail\n        }\n    }\n\n```\n\n\n#### Check [`Examples`](#examples) to get started with this package\n\n\n\u003cbr /\u003e\n\n### Styling\nYou 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](https://github.com/mediv0/vue-input-validator/blob/master/src/component/style.scss) to get familiar with the structure.\n\n\n### Responsive\nAs we know validator directive will create a span container and inject your input \u0026 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.\n\n**example**\n\n```html\n\u003cdiv class=\"App\"\u003e\n  \u003cdiv class=\"container\"\u003e\n    \u003cinput v-validator=\"options\" /\u003e\n  \u003c/div\u003e\n\u003c/div\u003e\n\n\u003cstyle\u003e\n  .container {\n    width: 400px;\n    font-family: \"Poppin\";\n  }\n\u003c/style\u003e\n\n```\n\n\u003cbr /\u003e\n\n### Security\nIf 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.\n\n\u003cbr /\u003e\n\n### Caveats\nThe 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.\n\nYou can access it in the mounted function like the example below to get the data on page load.\n```javascript\n\u003ctemplate\u003e\n    div v-if=\"isDataValid\"\u003e ... \u003c/div\u003e\n\u003c/template\u003e\n\ndata() {\n    isDataValid: \"...\"\n}\n\nmounted() {\n    this.isDataValid = this.$validator.isValid();\n}\n\n```\n\n\u003cbr /\u003e\n\n### Examples\nCheck [example folder](https://github.com/mediv0/vue-input-validator/tree/master/example)  or  [codeandbox!](https://codesandbox.io/s/vue-inuput-validator-nphgg?file=/src/App.vue) for more examples.\n\n\n### Contribution\n\n1.  [Fork the project]\n2.  Create your feature branch (`git checkout -b new-feature-branch`)\n3.  Commit your changes (`git commit -am 'add new feature'`)\n4.  Push to the branch (`git push origin new-feature-branch`)\n5.  [Submit a pull request!](https://github.com/mediv0/vue-input-validator/pulls)\n\n**Feel free to request new features!**\n\n### License\n\n[MIT](http://opensource.org/licenses/MIT)\n\n### Todo\n\n-   [ ] Vue 3\n-   [x] more options\n-   [ ] caching system \n-   [x] async tests\n-   [x] validation chain\n-   [ ] buit in validations\n-   [x] debounce option\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmediv0%2Fvue-input-validator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmediv0%2Fvue-input-validator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmediv0%2Fvue-input-validator/lists"}