This blog post was written under the Pusher Guest Writer program.

VeeValidate is a validation library for Vue, that simplifies validation task in Vue projects. So far, the library supports Vue 2 and is quite popular among Vue developers, with more than 2k stars on Github.

Vue’s reactivity makes forms interestingly simple to work with. Reactivity and composition are two out of three characteristics of building forms. The third is declarative validation, which unfortunately (depending on how you see it), is not a feature in Vue’s core library. This is actually intentional because that’s how the Vue library is kept simple and small.

There’s nothing wrong with writing your validation logic with just JavaScript, but VeeValidate makes it a lot simpler as we will see.

When you’re done reading this piece, you should be able to validate all the basic HTML form controls, render errors with messages and visual cues, create custom validation rules, and more. All our examples will be on Codepen, so you can always head right into the demo and see things for yourself.

Setup

First thing we want to do is create an environment where we can start testing things out. I already created a Codepen starter with Vue installed. You can fork this starter if you intend to follow along.

If the following image is what you see on the pen’s result, then we are good to move on:

The starter has Bootstrap added, so we don’t have to write heavy CSS for basic layout and styles.

Next thing to do is install the VeeValidation library. In your real Vue application, you might have to install with npm:

npm install vee-validate --save

Or even yarn:

yarn add vee-validate

But, because we are using Codepen, CDN import is enough. It’s already included in the previous pen for you.

Form Value Binding

Before diving right into validations, let’s take a refresher on what we are validating — forms. Vue forms are simple to work with because of the library’s two way binding (reactivity) characteristics. Let’s see how to create some basic form controls in Vue and bind model data to them.

Text Boxes

    <form>
      <div class="form-group">
        <label for="formName">Full Name:</label>
        <input type="text" name="name" class="form-control" id="formName" v-model="model.name"> 
        {{model.name}}
      </div>
    </form>

A basic form with bootstrap-styled controls. The text box has a v-model attribute which is a Vue directive. It’s used to bind values from a model to the view. The model.name value in the v-model attribute and the model.name value in the {{}} interpolation are synced. Hence, changes made on the text box will reflect on the interpolated text. This won’t work now though, because, we’re yet to add this model and the name property to our Vue instance:

    new Vue({
      el: '#app',
      data: function() {
        return {
          title: 'Vue Vee Validation',
          // model.name bound to
          // a form text control
          model: {
            name: ''
          }
        }
      }
    })

Text Areas
Binding to text areas is as simple as binding text boxes:

    ...
    <div class="form-group">
      <label for="formBio">Bio:</label>
      <textarea name="bio" id="formBio" class="form-control" rows="3" v-model="model.bio"></textarea>
    </div>
    ...

You can add the model property on the model to keep the values in sync:

    model: {
      name: '',
      // Bio
      bio: ''
    }

Select Boxes
Select boxes are characterized with options where the user has to choose one or more (where applicable) values. Let’s first have a look at a single selection example:

    <div class="form-group">
      <label for="formGender">Gender:</label>
      <select v-model="model.gender" class="form-control">
        <option>Female</option>
        <option>Male</option>
      </select>
    </div>

The v-model directive is added to the select element, not the option elements. But whatever option is selected is set as the value of the model.

Of course, we can’t forget to add the select’s data to our control:

    model: {
      name: '',
      bio: '',
      // Gender
      gender: ''
    }

The multiple choice variation is almost the same as single select, with the values processed as an array of options rather than as a single value:

    <div class="form-group">
      <label for="formGender">Frameworks:</label>
      <select v-model="model.frameworks" class="form-control" multiple>
        <option>Vue</option>
        <option>Aurelia</option>
        <option>Preact</option>
        <option>Inferno</option>
      </select>
    </div>

Then you can specify the model property as an array:

    model: {
      // Frameworks
      frameworks: []
    }

Check Boxes
You can use check boxes to collect single or multiple values. An example of collecting single values could be when asking users whether they want to be subscribed to a newsletter:

     <div class="form-group">
      <label>
        <input type="checkbox" v-model="model.subscribe"> Subscribe me, please!
        {{model.subscribe}}
      </label>
    </div>


    model: {
      name: '',
      bio: '',
      gender: '',
      frameworks: [],
      // Subscribe
      subscribe: false
    }

Just omit the value attribute on the check box and the values are treated as a boolean.

The most common use case for check boxes is collecting multiple values:

    <div class="form-group">
        <label>Languages</label>
        <div class="checkbox">
          <label>
            <input type="checkbox" value="English" v-model="model.languages"> English
          </label>
          <label>
            <input type="checkbox" value="French" v-model="model.languages"> French
          </label>
          <label>
            <input type="checkbox" value="Ibo"v-model="model.languages"> Ibo
          </label>
          <label>
            <input type="checkbox" value="Hausa" v-model="model.languages"> Hausa
          </label>
          <label>
            <input type="checkbox" value="Yoruba" v-model="model.languages"> Yoruba
          </label>
        </div>
        {{model.languages}}
      </div>


    model: {
      // Languages
      languages: []
    }

Radio Buttons
The last control to have a look at are radio buttons:

    <div class="form-group">
      <label>Happy</label>
      <div class="checkbox">
        <label>
          <input type="radio" value="Yes" v-model="model.happy"> Yes
        </label>
        <label>
          <input type="radio" value="No" v-model="model.happy"> No
        </label>
      </div>
      {{model.happy}}
    </div>


    model: {
      // Languages
      happy: ''
    }

As radios are normally used for selecting single values from a couple of options, clicking ‘Yes’ or ‘No’ radio toggles happy model property with the values of the radio button.

Handling Form Submissions
Form controls that the data entered in them are not collected are as good as useless. We need to retrieve these values and process them. Vue has a submit event that can be attached to the form element while passing it a method to serve as the event handler:

    <form v-on:submit.prevent="onSubmit">
      ...
      <div class="form-group">
        <button class="btn btn-success">Submit</button>
      </div>
    </form>

The prevent modifier just calls preventDefault() which disables the page from refreshing.

You can create the onSubmit handler method in the Vue instance:

    // Fork: Basic Form Controls
    new Vue({
      el: '#app',
      data: function() {
        return {
          // ...
        }
      },
      // Vue methods
      methods: {
        // Form handler
        onSubmit: function() {
          // Log entire model to console
          console.log(this.model)
        }
      }
    })

So far so good. The following image shows what we have been working:

Form Validation with VeeValidate

Now to the real meat — validation. We will use VeeValidate for all our form validation needs including error tracking and reporting. It’s a Vue plugin, hence we need to configure Vue to be aware of its existence:

    Vue.use(VeeValidate);
    new Vue({
      // ...
    })

The use method enables the VeeValidate Vue plugin. We can now start using the plugin’s APIs and directives in our Vue app.

Rules
Validation rules are instructions that must be adhered to for form values to be acceptable. Abiding by these rules makes form values valid. Rule strings are values passed to the v-validate directive to validate a given form control. For example:

    <div class="form-group">
      <label for="formName">Full Name:</label>
      <input type="text" name="name" class="form-control" id="formName" v-model="model.name" v-validate="'required'" /> 
    </div>

The required string passed to v-validate tells us that this input’s value must be provided for the input to attain a valid state. Note that the required string value is wrapped in single quotes, notwithstanding the double quotes that follow the directive.

It’s very common to want to apply two rules. An email field could be required, and must also be a valid email:

    <div class="form-group">
      <label for="formEmail">Email:</label>
      <input type="text" name="name" class="form-control" id="formEmail" v-model="model.email" v-validate="'required|email'"> 
    </div>

The pipe (|) character is used to separate multiple rules added to the same form control.

Another good example is specifying maximum values that can be entered in our Bio text area control:

    <div class="form-group">
      <label for="formBio">Bio:</label>
      <textarea name="bio" id="formBio" class="form-control" rows="3" v-model="model.bio" v-validate="'required|max:50'"></textarea>
    </div>

Some rules take arguments, like max. Where the argument is the length of characters that we don’t want to exceed. In this case, 50.

required, email, etc are examples of in-built rules. You can create custom rules to fit your context better if none of the existing rules do. We will discuss that further down.

Error Messages
Yes, we just added validation. But what good is it, if all we do is keep quiet when a form control is invalid? Of course, we need to let the user know what they did wrong. Communication is key.

VeeValidate allows us to report messages by checking if an error does exist in the validate form:

    <div class="form-group">
      <label for="formName">Full Name:</label>
      <input type="text" name="name" class="form-control" id="formName" v-model="model.name" v-validate="'required'"> 
      <span v-show="errors.has('name')" class="text-danger">{{ errors.first('name') }}</span>
    </div>
  • The name attribute must be specified. It serves as an identifier for VeeValidate to refer to. You can use data-vv-name if for some reason, you can’t use name attribute in your template.
  • errors.has returns a boolean. true if the control is dirty (meaning a value has been entered) but the control is still invalid. It takes the name of the control as argument which is the same name that was passed as value to name or data-vv-name.
  • We use the v-show attribute to show an error message if errors.has returns true.
  • errors.first fetches the first error message associated with the form control

Error Visual Cues
The image above shows the error message which is the expected behavior. There is something a bit confusing, though. Why would we have a green border on the field which implies that all is well when there is an error? For a better user experience, when such errors occur, we should also make the controls show that:

    <div class="form-group">
      <label for="formEmail">Email:</label>
      <input 
        type="email" 
        name="email"  
        id="formEmail" 
        v-model="model.email" 
        v-validate="'required|email'" 
        v-bind:class="{'form-control': true, 'error': errors.has('email') }"> 
      ...
    </div>

We still achieve this using the errors.has method when combined with the class binding feature. First we set the form-control class to always true, and then the error class only when errors.has returns true.

Basic CSS to add the visual cue is shown below:

    .form-control.error {
      border-color: #E84444;
      box-shadow: inset 0 1px 1px rgba(0,0,0,.075), 0 0 8px rgba(232,68,68,.6);
    }

Disable Form Submits for Unvalidated Fields
When fields have errors in a form, you might want to disable access to submitting the containing form. This can be done by disabling clicks on the submit button:

    <button class="btn btn-success" :disabled="errors.any()" >Submit</button>

Custom Validation

The in-built rules might not serve all your needs, hence you might want something more flexible so as to include your custom rules and messages. VeeValidate allows you to write custom validation rules and messages in different ways but the most common pattern is an object with getMessage and valid methods:

    created: function() {
      VeeValidate.Validator.extend('verify_coupon', {
        // Custom validation message
        getMessage: (field) => `The ${field} is not a valid coupon.`,
        // Custom validation rule
        validate: (value) => new Promise(resolve => {
          const validCoupons = ['SUMMER2017', 'WINTER2017', 'FALL2017'];
          resolve({
              valid: value && (validCoupons.indexOf(value.toUpperCase()) > -1)
            });
        })
      });
    },
    //...
  • The created lifecycle method runs when our component is ready. Therefore, it makes a good candidate for registering custom validation rules and messages.
  • Validator.extend method is used to create custom validation rules and messages by passing the name of the validation rule (rule string) and an object as argument.
  • The second argument, which is the object, defines a getMessage method which returns a string. This string is what serves as the error message when the field is invalid.
  • The validate method in the object returns a boolean, an object or a promise. If it returns an object, the valid property must be present with a boolean value. This boolean value is what is checked to see if the form is valid or not.

More Validation Examples

Let’s revisit the form controls we have in our demo and validate them all. At least with a required rule.

Select Box

    <div class="form-group">
      <label for="formGender">Gender:</label>
      <select v-model="model.gender" name="gender" v-validate="'required'" :class="{'form-control': true, 'error': errors.has('gender')}">
        <option>Female</option>
        <option>Male</option>
      </select>
      <span v-show="errors.has('gender')" class="text-danger">{{ errors.first('gender') }}</span>
    </div>

    <div class="form-group">
      <label for="formGender">Frameworks:</label>
      <select v-model="model.frameworks" name="frameworks" v-validate="'required'" :class="{'form-control': true, 'error': errors.has('frameworks')}" multiple>
        <option>Vue</option>
        <option>Aurelia</option>
        <option>Preact</option>
        <option>Inferno</option>
      </select>
      <span v-show="errors.has('frameworks')" class="text-danger">{{ errors.first('frameworks') }}</span>
    </div>

Check Boxes

    <div class="form-group">
      <label>
        <input type="checkbox" name="subscribe" v-validate="'required'"> Subscribe me, please!
        {{model.subscribe}}
      </label>
      <span v-show="errors.has('subscribe')" class="text-danger">{{ errors.first('subscribe') }}</span>
    </div>

Note that the v-model directive was removed. This is because, false is a value and the validation rule will assume the form is populated with it. Hence, the form is valid

Radios

    <div class="form-group">
      <label>Happy</label>
      <div class="checkbox">
        <label>
          <input type="radio" name="subscribe" v-validate="'required'" value="Yes" v-model="model.happy"> Yes
        </label>
        <label>
          <input type="radio" name="happy" v-validate="'required'" value="No" v-model="model.happy"> No
        </label>
      </div>
      {{model.happy}}
                <span v-show="errors.has('happy')" class="text-danger">{{ errors.first('happy') }}</span>
    </div>

DEMO

Conclusion

We’ve covered almost all the aspects of form validation you might need while creating your own forms in Vue, such as rules, messages, and visual vues. You should now be able to imagine the lines of code you would have to write if you had to build a custom implementation for your validation logic. VeeVaidate makes validation simple via it’s APIs and directives.

About Chris Nwamba

Chris is a JavaScript preacher. He also strives to make something out of other languages. Tech Writer. Dev Evangelist. Speaker.