Handling Forms

Now that you've learned how to use the ValidationProvider to validate your input fields, what about validating forms in its entirety?

For this you will be using another component called ValidationObserver, which like how its name suggests, observes the validation state of fields within it.

You can think of ValidationProvider components as individual fields, and the ValidationObserver as a form. As such the ValidationObserver acts as an aggregator for its child providers or any components that extend them.

In other words, the ValidationObserver exposes a combined validation state of all its fields. The validation state that's aggregated is the errors and the validation flags.

Basic Example

Assuming you have a basic form, and you want to disable the submit button until the form is valid. You can use the ValidationObserver invalid flag exposed on the slot props:

<template>
  <ValidationObserver v-slot="{ invalid }">
    <form @submit.prevent="onSubmit">
      <ValidationProvider name="E-mail" rules="required|email" v-slot="{ errors }">
        <input v-model="email" type="email">
        <span>{{ errors[0] }}</span>
      </ValidationProvider>

      <ValidationProvider name="First Name" rules="required|alpha" v-slot="{ errors }">
        <input v-model="firstName" type="text">
        <span>{{ errors[0] }}</span>
      </ValidationProvider>

      <ValidationProvider name="Last Name" rules="required|alpha" v-slot="{ errors }">
        <input v-model="lastName" type="text">
        <span>{{ errors[0] }}</span>
      </ValidationProvider>

      <button type="submit" :disabled="invalid">Submit</button>
    </form>
  </ValidationObserver>
</template>

<script>
export default {
  data: () => ({
    email: '',
    firstName: '',
    lastName: ''
  }),
  methods: {
    onSubmit () {
      alert('Form has been submitted!');
    }
  }
};
</script>

<style lang="stylus" scoped>
span {
  display: block;
}
</style>

All the validation flags exposed on the ValidationProvider are also available on the ValidationObserver slot props, so you can craft the UX you need for your forms.

Validate Before Submit

Validating forms before submitting is a must in form validation. The ValidationObserver offers a handleSubmit function that you can use to protect your form submissions. This handleSubmit function accepts a submit handler and will only execute the handler once the user submits a valid form.

<template>
  <ValidationObserver v-slot="{ handleSubmit }">
    <form @submit.prevent="handleSubmit(onSubmit)">
      <ValidationProvider name="E-mail" rules="required|email" v-slot="{ errors }">
        <input v-model="email" type="email">
        <span>{{ errors[0] }}</span>
      </ValidationProvider>

      <ValidationProvider name="First Name" rules="required|alpha" v-slot="{ errors }">
        <input v-model="firstName" type="text">
        <span>{{ errors[0] }}</span>
      </ValidationProvider>

      <ValidationProvider name="Last Name" rules="required|alpha" v-slot="{ errors }">
        <input v-model="lastName" type="text">
        <span>{{ errors[0] }}</span>
      </ValidationProvider>

      <button type="submit">Submit</button>
    </form>
  </ValidationObserver>
</template>

<script>
export default {
  data: () => ({
    firstName: '',
    lastName: '',
    email: ''
  }),
  methods: {
    onSubmit () {
      alert('Form has been submitted!');
    }
  }
};
</script>

<style lang="stylus" scoped>
span {
  display: block;
}
</style>

Resetting Forms

You may want to reset the form state after successful submission. This can be useful in re-usable forms and other situations. The ValidationObserver exposes a reset method that you can use for this purpose. The reset method reverts the validation states back to their initial state. For example: setting the touched and dirty flags to false and clearing all errors.

<template>
  <ValidationObserver v-slot="{ handleSubmit, reset }">
    <form @submit.prevent="handleSubmit(onSubmit)" @reset.prevent="reset">
      <ValidationProvider name="E-mail" rules="required|email" v-slot="{ errors }">
        <input v-model="email" type="email">
        <span>{{ errors[0] }}</span>
      </ValidationProvider>

      <ValidationProvider name="First Name" rules="required|alpha" v-slot="{ errors }">
        <input v-model="firstName" type="text">
        <span>{{ errors[0] }}</span>
      </ValidationProvider>

      <ValidationProvider name="Last Name" rules="required|alpha" v-slot="{ errors }">
        <input v-model="lastName" type="text">
        <span>{{ errors[0] }}</span>
      </ValidationProvider>

      <button type="submit">Submit</button>
      <button type="reset">Reset</button>
    </form>
  </ValidationObserver>
</template>

<script>
export default {
  data: () => ({
    firstName: '',
    lastName: '',
    email: ''
  }),
  methods: {
    onSubmit () {
      alert('Form has been submitted!');
    }
  }
};
</script>

<style lang="stylus" scoped>
span {
  display: block;
}
</style>

TIP

The ValidationObserver reset method does not reset the values of the child fields, this is up to you.

Programmatic Access with $refs

Typically, resetting forms happens programmatically once the submission succeeds, and not as a response to event handlers like in the previous example. In addition, you may want to arbitrarily call the validate or handleSubmit methods on the ValidationObserver in your script rather than the template. You can also use validateWithInfo which returns more detailed information about the validation like error messages and the fields involved in the validation.

That means you need access to the ValidationObserver in your script. To do that, use the ref attribute. Here is an example that handles validation before submit and then resetting using $refs.

<template>
  <ValidationObserver ref="form">
    <form @submit.prevent="onSubmit">
      <ValidationProvider name="E-mail" rules="required|email" v-slot="{ errors }">
        <input v-model="email" type="email">
        <span>{{ errors[0] }}</span>
      </ValidationProvider>

      <ValidationProvider name="First Name" rules="required|alpha" v-slot="{ errors }">
        <input v-model="firstName" type="text">
        <span>{{ errors[0] }}</span>
      </ValidationProvider>

      <ValidationProvider name="Last Name" rules="required|alpha" v-slot="{ errors }">
        <input v-model="lastName" type="text">
        <span>{{ errors[0] }}</span>
      </ValidationProvider>

      <button type="submit">Submit</button>
    </form>
  </ValidationObserver>
</template>

<script>
export default {
  data: () => ({
    firstName: '',
    lastName: '',
    email: ''
  }),
  methods: {
    onSubmit () {
      this.$refs.form.validate().then(success => {
        if (!success) {
          return;
        }

        alert('Form has been submitted!');

        // Resetting Values
        this.firstName = this.lastName = this.email = '';

        // Wait until the models are updated in the UI
        this.$nextTick(() => {
          this.$refs.form.reset();
        });
      });
    }
  }
};
</script>

<style lang="stylus" scoped>
span {
  display: block;
}
</style>

TIP

Using refs gives you full access to the ValidationObserver component API, but it is recommended that you only use the documented API as any of the internals are subject to change. See the ValidationObserver Public API.

TypeScript

When using $refs with TypeScript, you have to provide the typings for the ValidationObserver or ValidationProvider instances which can be done using InstanceType utility type. Use it like the following snippet:

import { ValidationObserver } from 'vee-validate';

export default class App extends Vue {
  $refs!: {
    observer: InstanceType<typeof ValidationObserver>;
  };

  mounted() {
    this.$refs.observer;
  }
}

Initial State Validation

The ValidationProvider doesn't validate initially, but you can use the immediate prop to validate your fields upon rendering:

<ValidationProvider rules="required" immediate v-slot="{ errors }">
  <!-- -->
</ValidationProvider>

This will validate the fields immediately when they are rendered.

This is an example of such a form:

<template>
  <ValidationObserver v-slot="{ handleSubmit }">
    <form @submit.prevent="handleSubmit(onSubmit)">
      <ValidationProvider name="E-mail" rules="required|email" immediate v-slot="{ errors }">
        <input v-model="email" type="email">
        <span>{{ errors[0] }}</span>
      </ValidationProvider>

      <ValidationProvider name="First Name" rules="required|alpha" immediate v-slot="{ errors }">
        <input v-model="firstName" type="text">
        <span>{{ errors[0] }}</span>
      </ValidationProvider>

      <ValidationProvider name="Last Name" rules="required|alpha" immediate v-slot="{ errors }">
        <input v-model="lastName" type="text">
        <span>{{ errors[0] }}</span>
      </ValidationProvider>

      <button type="submit">Submit</button>
    </form>
  </ValidationObserver>
</template>

<script>
export default {
  data: () => ({
    firstName: '',
    lastName: '',
    email: ''
  }),
  methods: {
    onSubmit () {
      alert('Form has been submitted!');
    }
  }
};
</script>

<style lang="stylus" scoped>
span {
  display: block;
}
</style>

Persisting Provider State

The ValidationObserver only observes the currently rendered ValidationProvider instances. If any ValidationProvider is hidden with v-if or removed with v-for it will automatically be excluded from the ValidationObserver state.

You might want the ValidationObserver to keep the state of unmounted providers. for example you could have a paged/multi-step form where the user can freely go to the next set of inputs without forcing the previous set to be valid, but you want to make sure all the pages/steps are valid before they submit the entire form.

In these cases you can use the Vue.js keep-alive built-in component. The ValidationObserver is able to detect cached ValidationProvider components and will keep their validation state reflected in its computation.

Here is an example that employs keep-alive to keep ValidationProvider state in its parent ValidationProvider:

<template>
<ValidationObserver ref="form">
  <form @submit.prevent="onSubmit">
    <fieldset>
      <legend >Step {{ currentStep }}</legend>
      <keep-alive>
        <ValidationProvider v-if="currentStep === 1" name="email" rules="required|email" v-slot="{ errors }">
          <input v-model="email" type="text" placeholder="Your email">
          <span>{{ errors[0] }}</span>
        </ValidationProvider>
      </keep-alive>

        <keep-alive>
          <ValidationProvider v-if="currentStep === 2" name="first name" rules="required" v-slot="{ errors }">
            <input v-model="fname" type="text" placeholder="Your first name">
            <span>{{ errors[0] }}</span>
          </ValidationProvider>
        </keep-alive>
        <keep-alive>
          <ValidationProvider v-if="currentStep === 2" name="last name" rules="required" v-slot="{ errors }">
            <input v-model="lname" type="text" placeholder="Your last name">
            <span>{{ errors[0] }}</span>
          </ValidationProvider>
        </keep-alive>

        <keep-alive>
          <ValidationProvider v-if="currentStep === 3" name="address" rules="required|min:5" v-slot="{ errors }">
            <textarea v-model="address" type="text" placeholder="Your address"></textarea>
            <span>{{ errors[0] }}</span>
          </ValidationProvider>
        </keep-alive>
    </fieldset>

    <button type="button" @click="goToStep(currentStep - 1)">Previous</button>
    <button type="button" @click="goToStep(currentStep + 1)">{{ currentStep === 3 ? 'Submit' : 'Next' }}</button>
  </form>
</ValidationObserver>
</template>

<script>
export default {
  data: () => ({
    currentStep: 1,
    address: '',
    fname: '',
    lname: '',
    email: ''
  }),
  methods: {
    goToStep (step) {
      if (step < 1) {
        return;
      }

      if (step > 3) {
        this.onSubmit();
        return;
      }

      this.currentStep = step;
    },
    onSubmit () {
      this.$refs.form.validate().then(success => {
        if (!success) {
          return;
        }

        alert('Success!');
      });
    }
  }
}
</script>

<style lang="stylus" scoped>
span {
  display: block;
}

button {
  margin-top: 20px;
}
</style>

Step 1

TIP

Even when fields are hidden/unmounted, as long as they wrapped with keep-alive their state will also be affected by validate and reset calls.

Nested Observers

There is no such thing as nested forms in HTML5 and for a good reason: It doesn't make a lot of sense to have two forms within each other. However, the ValidationObserver components can be nested and this changes how you must think about them. Nested/Child ValidationObserver components will now act as a <fieldset> rather than <form> tags.

This is only useful in very rare scenarios where you need access to individual fieldset states at the same time and it is recommended to avoid having such nested observers (but you can do that if you want).

This is an example that uses nested observers:

<template>
<ValidationObserver v-slot="{ handleSubmit }">
  <form @submit.prevent="handleSubmit(onSubmit)">
    <ValidationObserver v-if="currentStep === 1">
      <fieldset>
        <legend>Step 1</legend>
        <ValidationProvider name="email" rules="required|email" v-slot="{ errors }">
          <input v-model="email" type="text" placeholder="Your email">
          <span>{{ errors[0] }}</span>
        </ValidationProvider>
      </fieldset>
    </ValidationObserver>

    <ValidationObserver v-else-if="currentStep === 2">
      <fieldset>
        <legend>Step 2</legend>
        <ValidationProvider name="first name" rules="required" v-slot="{ errors }">
          <input v-model="fname" type="text" placeholder="Your first name">
          <span>{{ errors[0] }}</span>
        </ValidationProvider>

        <ValidationProvider name="last name" rules="required" v-slot="{ errors }">
          <input v-model="lname" type="text" placeholder="Your last name">
          <span>{{ errors[0] }}</span>
        </ValidationProvider>
      </fieldset>
    </ValidationObserver>

    <ValidationObserver v-else-if="currentStep === 3">
      <fieldset>
        <legend>Step 3</legend>
        <ValidationProvider name="address" rules="required|min:5" v-slot="{ errors }">
          <textarea v-model="address" type="text" placeholder="Your address"></textarea>
          <span>{{ errors[0] }}</span>
        </ValidationProvider>
      </fieldset>
    </ValidationObserver>

    <button type="submit">Next</button>
  </form>
</ValidationObserver>
</template>

<script>
export default {
  data: () => ({
    currentStep: 1,
    address: '',
    fname: '',
    lname: '',
    email: ''
  }),
  methods: {
    onSubmit () {
      if (this.currentStep === 3) {
        alert('Form submitted!');
        return;
      }

      this.currentStep++;
    }
  }
}
</script>

<style lang="stylus" scoped>
span {
  display: block;
}

button {
  margin-top: 20px;
}
</style>

Step 1

Here is the same example but without such nesting and only using one ValidationObserver:

<template>
<ValidationObserver v-slot="{ handleSubmit }">
  <form @submit.prevent="handleSubmit(onSubmit)">
    <fieldset v-if="currentStep === 1">
      <legend>Step 1</legend>
      <ValidationProvider name="email" rules="required|email" v-slot="{ errors }">
        <input v-model="email" type="text" placeholder="Your email">
        <span>{{ errors[0] }}</span>
      </ValidationProvider>
    </fieldset>

    <fieldset v-else-if="currentStep === 2">
      <legend>Step 2</legend>
      <ValidationProvider name="first name" rules="required" v-slot="{ errors }">
        <input v-model="fname" type="text" placeholder="Your first name">
        <span>{{ errors[0] }}</span>
      </ValidationProvider>

      <ValidationProvider name="last name" rules="required" v-slot="{ errors }">
        <input v-model="lname" type="text" placeholder="Your last name">
        <span>{{ errors[0] }}</span>
      </ValidationProvider>
    </fieldset>

    <fieldset v-else-if="currentStep === 3">
      <legend>Step 3</legend>
      <ValidationProvider name="address" rules="required|min:5" v-slot="{ errors }">
        <textarea v-model="address" type="text" placeholder="Your address"></textarea>
        <span>{{ errors[0] }}</span>
      </ValidationProvider>
    </fieldset>

    <button type="submit">Next</button>
  </form>
</ValidationObserver>
</template>

<script>
export default {
  data: () => ({
    currentStep: 1,
    address: '',
    fname: '',
    lname: '',
    email: ''
  }),
  methods: {
    onSubmit () {
      if (this.currentStep === 3) {
        alert('Form submitted!');
        return;
      }

      this.currentStep++;
    }
  }
}
</script>

<style lang="stylus" scoped>
span {
  display: block;
}

button {
  margin-top: 20px;
}
</style>

Step 1

It is simpler to think about non-nested observers than multiple observers. For the shown scenario it is unnecessary to know whether two observers are valid at the same time. This is because there is only one rendered ValidationObserver at any given time. Having such a situation should give you a hint about only needing one from the start.

Advanced Forms

Some forms have more complex requirements, like input masks or file validation. VeeValidate allows you to hook your complex inputs into the validation cycle. To do this see the advanced file-validation guide.

---

You should now have enough information on building your next form. The only thing remaining is to tackle localization.