Vuelidate is a model-based validation for Vue.js that decouples JavaScript validation nicely from Vue templates. On the downside, it may lead to lengthy Vue expressions and repetitions.
The components in this package let you write concise Vuelidate validations for Vue Material input elements.
For example, an input field like this one ...
<md-field :class="{ 'md-invalid': $v.username.$error }">
<md-input type="text" v-model="$v.username.$model" />
<span class="md-error" v-if="!$v.username.maxLength">
Must not be longer than {{ $v.username.$params.maxLength.max }} chars
</span>
</md-field>
... becomes:
<md-vuelidated>
<md-input type="text" v-model="username" />
<md-vuelidated-msg constraint="maxLength" v-slot="{ max }">
Must not be longer than {{ max }} chars
</md-vuelidated-msg>
</md-vuelidated>
Here is a more extensive online example (source code) of how this package can be used.
There are more benefits than just concise markup:
- Works with
<md-field>
(any type of<input>
, and<textarea>
),<md-autocomplete>
,<md-chips>
and<md-datepicker>
- Suppresses validation messages for fields that have not been touched yet (similar to Angular Material)
- Supports Vuelidate data nesting, collections validation and accessing validator parameters
As a module:
$ npm install @undecaf/vue-material-vuelidate
or
$ yarn add @undecaf/vue-material-vuelidate
Included as <script>
:
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@undecaf/vue-material-vuelidate/dist/components.css">
<script src="https://cdn.jsdelivr.net/npm/@undecaf/vue-material-vuelidate/dist/components.min.js"></script>
Please note: this module needs the CSP to allow unsafe-eval
(same as for the full Vue build).
For your reassurance: nevertheless, no eval()
inside!
import MdVuelidated from '@undecaf/vue-material-vuelidate'
import '@undecaf/vue-material-vuelidate/dist/components.css'
...
// This must come after Vue.use(VueMaterial) and Vue.use(Vuelidate):
Vue.use(MdVuelidated)
This registers <md-vuelidated>
and <md-vuelidated-msg>
globally.
In order to validate an <md-field>
, <md-autocomplete>
, <md-chips>
or <md-datepicker>
field
(see here for providing validation messages):
- Replace that tag with
<md-vuelidated>
. - Pass the replaced tag name as property
field
(defaults tomd-field
). - Place
v-model
on an input element (<input>
or<textarea>
) or on<md-vuelidated>
. - Express constraints in the
validations
object of your component in the usual way.
The following examples assume that a suitable validations
object has been defined.
Validating text:
<md-vuelidated> <!-- becomes an <md-field> by default -->
<label>Enter your email address</label>
<md-input type="email" v-model.trim="mail" />
</md-vuelidated>
Validating a selection:
<md-vuelidated>
<label>Select at most two toppings</label>
<md-select v-model="toppings" multiple>
<md-option value="1">Pepperoni</md-option>
<md-option value="2">Mushrooms</md-option>
<md-option value="3">Onions</md-option>
</md-select>
</md-vuelidated>
Validating an autocomplete field:
<md-vuelidated field="md-autocomplete" :md-options="colors" v-model="color">
<label>Select a color</label>
</md-vuelidated>
Validating a chips field:
<md-vuelidated field="md-chips" md-placeholder="Enter keywords" v-model="keywords">
</md-vuelidated>
Validating a date:
<md-vuelidated field="md-datepicker" v-model="dateOfBirth">
<label>Your date of birth</label>
</md-vuelidated>
Just use the nested path as the v-model
, e.g.
<md-vuelidated>
<label>Homepage</label>
<md-input type="url" v-model.trim="www.home" />
</md-vuelidated>
v-for
can be placed on <md-vuelidated>
or on a parent element. In any case, <md-vuelidated>
requires a key
that is bound to the v-for
index.
Let's assume that comments
is an array with elements like { text: 'blah' }
or an object with
such members. Then an input field for each comment can be rendered and validated as follows:
<md-vuelidated v-for="(_, index) in comments" :key="index">
<label>Comment</label>
<textarea v-model="comments[index].text"></textarea>
</md-vuelidated>
If v-for
is on a parent element then <md-vuelidated>
needs a copy of the key
:
<div v-for="(_, i) in comments" :key="i">
...
<md-vuelidated :key="i">
<label>Comment</label>
<textarea v-model="comments[i].text"></textarea>
</md-vuelidated>
...
</div>
The v-for
index should be named index
. In nested v-for
blocks, indices must be named
index1
, index2
etc.
Validation messages can be specified in two ways both of which can be combined:
-
As the
messages
property of<md-vuelidated>
, bound to an object containing the message for each Vuelidate constraint, e.g.:messages="{ required: 'This field is required' }"
.These messages appear below the corresponding input field.
-
As
<md-vuelidated-msg>
elements, either enclosed in<md-vuelidated>
tags or detached. Propertyconstraint
must be set to the Vuelidate constraint name. For detached messages, the constraint name must be qualified with the model name, see the examples below.Enclosed messages appear below the corresponding input field.
If multiple validations fail at the same time then only the first one (in declaration order) displays a message.
Using the messages
property:
<md-vuelidated
:messages="{
required: 'Your mail address is required',
email: 'Not a valid mail address',
}">
<md-input type="email" v-model.trim="mail" />
</md-vuelidated>
As <md-vuelidated-msg>
tags:
<md-vuelidated>
<label>Enter your email address</label>
<md-input type="email" v-model.trim="mail" />
<md-vuelidated-msg constraint="required">Your mail address is required</md-vuelidated-msg>
<md-vuelidated-msg constraint="email">Not a valid mail address</md-vuelidated-msg>
</md-vuelidated>
Both methods can be combined.
Messages outside of <md-vuelidated>
blocks need their constraint
property to be qualified
with the model name (often the collection name):
<md-vuelidated v-for="(_, index) in comments" :key="index">
<label>Comment</label>
<textarea v-model="comments[index].text"></textarea>
</md-vuelidated>
<!-- Detached message, referring to collection 'comments' -->
<md-vuelidated-msg constraint="comments.maxLength">Too many comments!</md-vuelidated-msg>
The parameters of the constraint
validator are available as a v-slot
:
<md-vuelidated-msg constraint="comments.maxLength" v-slot="params">
You may not author more than {{ params.max }} comments
</md-vuelidated-msg>
Object destructuring lets us express this more elegantly:
<md-vuelidated-msg constraint="comments.maxLength" v-slot="{ max }">
You may not author more than {{ max }} comments
</md-vuelidated-msg>
Software: MIT
Documentation: CC-BY-SA 4.0