Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/fergaldoyle/vue-form
Form validation for Vue.js 2.2+
https://github.com/fergaldoyle/vue-form
async-validation form-validation html5-validation validation vue vuejs2
Last synced: 5 days ago
JSON representation
Form validation for Vue.js 2.2+
- Host: GitHub
- URL: https://github.com/fergaldoyle/vue-form
- Owner: fergaldoyle
- License: mit
- Created: 2015-10-19T22:48:06.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2019-12-13T20:53:21.000Z (about 5 years ago)
- Last Synced: 2025-01-18T21:38:55.229Z (12 days ago)
- Topics: async-validation, form-validation, html5-validation, validation, vue, vuejs2
- Language: JavaScript
- Homepage:
- Size: 316 KB
- Stars: 614
- Watchers: 23
- Forks: 90
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-vue-cn - **vue-form ★105**
README
# vue-form
[](https://travis-ci.org/fergaldoyle/vue-form)
Form validation for Vue.js 2.2+
### Install
Available through npm as `vue-form`.
``` js
import VueForm from 'vue-form';
// or var VueForm = require('vue-form') or window.VueForm if you are linking directly to the dist file
// install globally
Vue.use(VueForm);
Vue.use(VueForm, options);
// or use the mixin
...
mixins: [VueForm]
...
mixins: [new VueForm(options)]
...
```
### Usage
Once installed you have access to four components (`vue-form`, `validate`, `field`, `field-messages`) for managing form state, validating form fields and displaying validation messages.
Live examples
* Configured to work with Bootstrap styles: https://jsfiddle.net/fergal_doyle/zfqt4yhq/
* Matching passwords and password strength: https://jsfiddle.net/fergal_doyle/9rn5kLkw/
* Field error messages based on submitted state (labels tied to inputs with `auto-label`): https://jsfiddle.net/fergal_doyle/bqys2p5y/
Example
```html
Name *
Success!
Name is a required field
Email
Email is a required field
Email is not valid
Submit
{{ formstate }}
```
```js
Vue.use(VueForm);
new Vue({
el: '#app',
data: {
formstate: {},
model: {
name: '',
email: 'invalid-email'
}
},
methods: {
onSubmit: function () {
if(this.formstate.$invalid) {
// alert user and exit early
return;
}
// otherwise submit form
}
}
});
```
The output of `formstate` will be:
```js
{
"$dirty": false,
"$pristine": true,
"$valid": false,
"$invalid": true,
"$submitted": false,
"$touched": false,
"$untouched": true,
"$focused": false,
"$pending": false,
"$error": {
// fields with errors are copied into this object
},
"$submittedState": {
// each form sumbit, state is cloned into this object
},
"name": {
"$name": "name",
"$dirty": false,
"$pristine": true,
"$valid": false,
"$invalid": true,
"$touched": false,
"$untouched": true,
"$focused": false,
"$pending": false,
"$error": {
"required": true
}
},
"email": {
"$name": "email",
"$dirty": false,
"$pristine": true,
"$valid": false,
"$invalid": true,
"$touched": false,
"$untouched": true,
"$focused": false,
"$pending": false,
"$error": {
"email": true
}
}
}
```
### Displaying messages
Display validation errors or success messages with `field-messages`.
The `show` prop supports simple expressions which specifiy when messages should be displayed based on the current state of the field, e.g: `$dirty`, `$dirty && $touched`, `$dirty || $touched`, `$touched || $submitted`, `$focused && ($dirty || $submitted)`
```html
Error message A
Error message B
```
Or use scoped templates:
```html
Success
Name is a required field
Error message B
```
### Validators
```
type="email"
type="url"
type="number"
required
minlength
maxlength
pattern
min (for type="number")
max (for type="number")
```
You can use static validation attributes or bindings. If it is a binding, the input will be re-validated every binding update meaning you can have inputs which are conditionally required etc.
```html
```
#### Custom validators
You can register global and local custom validators.
Global custom validator
```js
var options = {
validators: {
'my-custom-validator': function (value, attrValue, vnode) {
// return true to set input as $valid, false to set as $invalid
return value === 'custom';
}
}
}
Vue.use(VueForm, options);
// or
// mixins: [new VueForm(options)]
```
```html
```
Local custom validator
```js
// ...
methods: {
customValidator: function (value) {
// return true to set input as $valid, false to set as $invalid
return value === 'custom';
}
},
// local custom validator can also be a data or computed property
computed: {
isEmailAvailable: function () {
// return true to set input as $valid, false to set as $invalid
}
}
// ...
```
```html
```
#### Async validators:
Async validators are custom validators which return a Promise. `resolve()` `true` or `false` to set field validity.
```js
// ...
methods: {
customValidator (value) {
return new Promise((resolve, reject) => {
setTimeout(() => {
resolve(value === 'ajax');
}, 100);
});
}
}
// ...
```
Async validator with debounce (example uses lodash debounce)
```js
methods: {
debounced: _.debounce(function (value, resolve, reject) {
fetch('https://httpbin.org/get').then(function(response){
resolve(response.isValid);
});
}, 500),
customValidator (value) {
return new Promise((resolve, reject) => {
this.debounced(value, resolve, reject);
});
}
}
```
### Reset state
```
resetState: function () {
this.formstate._reset();
// or
this.$refs.form.reset();
}
```
### State classes
As form and input validation states change, state classes are added and removed
Possible form classes:
```
vf-form-dirty, vf-form-pristine, vf-form-valid, vf-form-invalid, vf-form-submitted, vf-form-focused- vf-form-pending
```
Possible input classes:
```
vf-dirty, vf-pristine, vf-valid, vf-invalid, vf-focused, vf-pending
// also for every validation error, a class will be added, e.g.
vf-invalid-required, vf-invalid-minlength, vf-invalid-max, etc
```
Input wrappers (e.g. the tag the `validate` component renders) will also get state classes, but with the `field` prefix, e.g.
```
vf-field-dirty, vf-field-pristine, vf-field-valid, vf-field-invalid, vf-field-focused, vf-field-pending
```
### Custom components
When writing custom form field components, e.g. `` you should trigger the `focus` and `blur` events after user interaction either by triggering native dom events on the root node of your component, or emitting Vue events (`this.$emit('focus)`) so the `validate` component can detect and set the `$dirty` and `$touched` states on the field.
### Component props
#### vue-form
* `state` Object on which form state is set
* `tag` String, defaults to `form`
* `show-messages` String, applies to all child `field-messages`, show errors dependant on form field state e.g. `$touched`, `$dirty || $touched`, '$touched || $submitted'
#### validate
* `state` Optional way of passing in the form state. If omitted form state will be found in the $parent
* `custom` Object containing one or many custom validators. `{validatorName: validatorFunction}`
* `tag` String which specifies what element tag should be rendered by the `validate` component, defaults to `span`
* `auto-label`: Boolean, defaults to false. Automatically set `for` and `id` attributes of label and input elements found inside the `validate` component
* `debounce` Number, defaults to none, which specifies the delay (milliseconds) before validation takes place.
#### field-messages
* `state` Optional way of passing in the form state. If omitted form state will be found in the $parent
* `name` String which specifies the related field name
* `tag` String, defaults to `div`
* `show` String, show error dependant on form field state e.g. `$touched`, `$dirty || $touched`, '$touched || $submitted'
* `auto-label` Boolean, defaults to false. Automatically set the `for` attribute of labels found inside the `field-messages` component
#### field
* `tag` String, defaults to `div`
* `auto-label` Boolean, defaults to true. Automatically set `for` and `id` attributes of label and input elements found inside the `validate` component
### Config
Set config options when using `Vue.use(VueForm, options)`, or when using a mixin `mixins: [new VueForm(options)]` defaults:
```js
{
validators: {},
formComponent: 'vueForm',
formTag: 'form',
messagesComponent: 'fieldMessages',
messagesTag: 'div',
showMessages: '',
validateComponent: 'validate',
validateTag: 'div',
fieldComponent: 'field',
fieldTag: 'div',
formClasses: {
dirty: 'vf-form-dirty',
pristine: 'vf-form-pristine',
valid: 'vf-form-valid',
invalid: 'vf-form-invalid',
touched: 'vf-form-touched',
untouched: 'vf-form-untouched',
focused: 'vf-form-focused',
submitted: 'vf-form-submitted',
pending: 'vf-form-pending'
},
validateClasses: {
dirty: 'vf-field-dirty',
pristine: 'vf-field-pristine',
valid: 'vf-field-valid',
invalid: 'vf-field-invalid',
touched: 'vf-field-touched',
untouched: 'vf-field-untouched',
focused: 'vf-field-focused',
submitted: 'vf-field-submitted',
pending: 'vf-field-pending'
},
inputClasses: {
dirty: 'vf-dirty',
pristine: 'vf-pristine',
valid: 'vf-valid',
invalid: 'vf-invalid',
touched: 'vf-touched',
untouched: 'vf-untouched',
focused: 'vf-focused',
submitted: 'vf-submitted',
pending: 'vf-pending'
},
Promise: typeof Promise === 'function' ? Promise : null
}
```