vue-form
Form validation for Vue.js 2.2+
Install
Available through npm as vue-form
.
;// or var VueForm = require('vue-form') or window.VueForm if you are linking directly to the dist file// install globallyVue;Vue;// or use the mixin...mixins: VueForm...mixins: 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
Name * Success! Name is a required field Email Email is a required field Email is not valid Submit {{ formstate }}
Vue; el: '#app' data: formstate: {} model: name: '' email: 'invalid-email' methods: { ifthisformstate$invalid // alert user and exit early return; // otherwise submit form } ;
The output of formstate
will be:
"$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)
Error message A Error message B
Or use scoped templates:
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.
<!-- static validators --> <!-- bound validators -->
Custom validators
You can register global and local custom validators.
Global custom validator
var options = validators: { // return true to set input as $valid, false to set as $invalid return value === 'custom'; } Vue;// or// mixins: [new VueForm(options)]
<!-- slot name inside field-messages would be: <div slot="my-custom-validator">...</div> -->
Local custom validator
// ...methods: { // 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 propertycomputed: { // return true to set input as $valid, false to set as $invalid }// ...
<!-- slot name inside field-messages would be: <div slot="customValidator">...</div> -->
Async validators:
Async validators are custom validators which return a Promise. resolve()
true
or false
to set field validity.
// ...methods: { return { ; }; }// ...
Async validator with debounce (example uses lodash debounce)
methods: debounced: _ { return { this; }; }
Reset state
<vue-form ref="form" :state="formstate">
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. <my-checkbox v-model="foo"></my-checkbox>
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 settag
String, defaults toform
show-messages
String, applies to all childfield-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 $parentcustom
Object containing one or many custom validators.{validatorName: validatorFunction}
tag
String which specifies what element tag should be rendered by thevalidate
component, defaults tospan
auto-label
: Boolean, defaults to false. Automatically setfor
andid
attributes of label and input elements found inside thevalidate
componentdebounce
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 $parentname
String which specifies the related field nametag
String, defaults todiv
show
String, show error dependant on form field state e.g.$touched
,$dirty || $touched
, '$touched || $submitted'auto-label
Boolean, defaults to false. Automatically set thefor
attribute of labels found inside thefield-messages
component
field
tag
String, defaults todiv
auto-label
Boolean, defaults to true. Automatically setfor
andid
attributes of label and input elements found inside thevalidate
component
Config
Set config options when using Vue.use(VueForm, options)
, or when using a mixin mixins: [new VueForm(options)]
defaults:
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