1 | # [vueform](https://vueform.optick.io)
|
2 |
|
3 | > Form validation for [Vue.js](https://vuejs.org/) powered by HTML5
|
4 |
|
5 | ## Features
|
6 |
|
7 | * Easy: integrates with Vue.js to provide a reactive interface for working with
|
8 | validity state.
|
9 | * Lightweight: uses the HTML5 validation API whenever possible.
|
10 | * Flexible: allows you to set the validity state within your own custom
|
11 | validators.
|
12 | * Convenient: adds a configurable `.wasSubmitted` class to your forms when they
|
13 | are submitted and `.wasFocused` class to your fields when they are focused so
|
14 | that you're able to have more control when styling invalid fields with the
|
15 | `:invalid` psuedo-class.
|
16 |
|
17 | ## Instructions
|
18 |
|
19 | 1. Install `vueform`:
|
20 |
|
21 | ```
|
22 | npm install vueform --save
|
23 | ```
|
24 |
|
25 | 2. Tell Vue.js to use vueform and then create a new form in your component data
|
26 | hook:
|
27 |
|
28 | ```js
|
29 | import Vue from 'vue'
|
30 | import VueForm from 'vueform'
|
31 |
|
32 | Vue.use(VueForm)
|
33 |
|
34 | //...
|
35 | data() {
|
36 | return {
|
37 | contactForm: new VueForm()
|
38 | }
|
39 | }
|
40 | //...
|
41 | ```
|
42 |
|
43 | 3. Pass the form object to vueform with the `v-form` directive:
|
44 |
|
45 | ```html
|
46 | <form v-form="contactForm">
|
47 | <!-- ... -->
|
48 | </form>
|
49 | ```
|
50 |
|
51 | 4. Add a form field to the form. Make sure it has an `id` property so that
|
52 | it can be identified:
|
53 |
|
54 | ```html
|
55 | <label for="name">Name:</label>
|
56 | <input type="text" id="name" v-model="contactData.name" required>
|
57 | ```
|
58 |
|
59 | > **Note:** When you're grouping radio buttons or checkboxes by the same name
|
60 | property and you want to validate that the group has a value (i.e. one
|
61 | of the elements is checked), simply pass the name of the group to the
|
62 | VueForm instance in the `required` array:
|
63 |
|
64 | ```js
|
65 | const reasons = { name: 'reasons', required: () => isReasonsRequired }
|
66 | patientForm: new VueForm({ required: ['sex', reasons] })
|
67 | ```
|
68 |
|
69 | 5. By default, your form will be set to `noValidate` which tells the browser to
|
70 | *slow it's roll* and gives you more control over the validation process. This
|
71 | means the browser won't show validation error messages. You can either
|
72 | display your own validation error messages, for example:
|
73 |
|
74 | ```html
|
75 | <div v-if="contactForm.$wasSubmitted" class="colorRed">
|
76 | <div v-if="contactForm.name.valueMissing">
|
77 | Name is required.
|
78 | </div>
|
79 | <div v-if="contactForm.name.patternMismatch">
|
80 | Please use only letters, spaces, dashes, and apostrophes.
|
81 | </div>
|
82 | </div>
|
83 | ```
|
84 |
|
85 | Or disable `noValidate` so that the browser displays validation error
|
86 | messages, by passing the `noValidate: false` option when creating your form,
|
87 | for example:
|
88 |
|
89 | ```js
|
90 | contactForm: new VueForm({ noValidate: false })
|
91 | ```
|
92 |
|
93 | ## API
|
94 |
|
95 | VueForm constructor options (with default values):
|
96 |
|
97 | ```js
|
98 | {
|
99 | wasFocusedClass: `wasFocused`
|
100 | wasSubmittedClass: `wasSubmitted`
|
101 | noValidate: true,
|
102 | $required: []
|
103 | }
|
104 | ```
|
105 |
|
106 | VueForm properties:
|
107 |
|
108 | | Property | Type | Description |
|
109 | |------------------|---------|------------------------------------------|
|
110 | | `$wasSubmitted` | boolean | True if the form was submitted. |
|
111 | | `$isInvalid` | boolean | True if the form is invalid. |
|
112 | | `$isValid` | boolean | True if the form is valid. |
|
113 | | `$invalidFields` | array | A collection of names of invalid fields. |
|
114 | | `$requiredFields`| array | A collection of names of required fields (those that aren't individually required, but require a value for the overall named group, i.e. checkboxes and radio buttons). |
|
115 |
|
116 | VueForm methods:
|
117 |
|
118 | | Method | Parameters | Description |
|
119 | |----------------------|------------|---------------------------------------|
|
120 | | `$setCustomValidity` | `field`: string, `invalid`: boolean or string | A convenience wrapper for element.setCustomValidity(). Useful when updating the validity of a field based on a custom validator. |
|