Forms
Vuetify offers a simple built-in form validation system based on functions as rules, making it easy for developers to get set up quickly. If you prefer using a 3rd party validation plugin, we also provide examples for integrating both Vee-validateand vuelidate.
Usage
The v-form
component makes it easy to add validation to form inputs. All input components have a rules prop that can be used to specify conditions in which the input is either valid or invalid.
Whenever the value of an input is changed, each rule receives a new value and is re-evaluated. If a rule returns false
or a string
, validation has failed and the string
value is presented as an error message.
API
Component | Description |
---|---|
v-form | Primary Component |
Rules
Rules allow you to apply custom validation on all form components. These are validated sequentially, and components display a maximum of 1 error at a time; so make sure you order your rules accordingly.
The most basic of rules is a simple function that checks if an input has a value or not; i.e. it makes it a required input.
However, you can make rules as complicated as needed, even allowing for asynchronous input validation. In the example below, the input is checked against a fake API service that takes some time to respond. Wait for the submit
event promise to resolve and see the validation in action.
The submit event is a combination of a native SubmitEvent
with a promise, so it can be await
ed or used with .then()
to get the result of the validation.
This also demonstrates the validate-on prop, which tells the v-form
component when validation should happen. Here we set it to 'submit lazy'
so that we only call the API service when the button is clicked.
Validation state
By default, all inputs run their validation rules when mounted but do not display errors to the user.
When rules run is controlled with the validate-on prop which accepts a string containing input
, blur
, submit
, or lazy
.input
, blur
, and submit
set when a validation error can first be displayed to the user, while lazy
disables validation on mount (useful for async rules).lazy
can be combined with other options, and implies input
on its own.
validate-on= | "input" | "blur" | "submit" | "lazy" |
---|---|---|---|---|
On mount | ✅ | ✅ | ✅ | ❌ |
On input | ✅ | ❌ | ❌ | * |
On blur | ✅ | ✅ | ❌ | * |
On submit | ✅ | ✅ | ✅ | * |
* Uses the behavior of whatever it's combined with.
The form’s current validation status is accessed using v-model
or the submit event. It can be in one of three states:
true
: All inputs with validation rules have been successfully validated.false
: At least one input has failed validation either by interaction or manual validation.null
: At least one input has failed validation without interaction or has not been validated yet due tolazy
validation.
This allows you to either check for any validation failure with !valid
, or only errors that are displayed to the user with valid === false
.
Examples
Props
Disabled
You can easily disable all input components in a v-form
by setting the disabled prop.
Fast fail
When the fast-fail prop is set, validation will short-circuit after the first invalid input is found. This can be useful if some of your rules are computationally heavy and can take a long time. In this example, notice how when the submit button is clicked, the second input does not show validation errors even though it does not satisfy the rules.
Misc
Exposed properties
The v-form
component has a number of exposed properties that can be accessed by setting a ref on the component. A ref allows us to access internal methods on a component. You can find all of them on the API page, but some of the more commonly used ones are validate()
, reset()
, and resetValidation()
.
The difference between reset()
and resetValidation()
is that the former resets both input values and validation state, while the latter only resets validation state.
Vee-validate
vee-validate documentation can be found here.
Vuelidate
vuelidate documentation can be found here.