Composition API Review
Here the difference between the components API and the composition API ends, both APIs work the same for the global validators and
i18n support. This page will quickly review what you learned about the composition API and offer some tips.
vee-validate is built from the ground up with the composition API through a collection of functions, mainly the
useForm functions. Internally the
<Form /> and
<Field /> components actually use the composition functions under the hood.
Meaning you can create your own custom input and form components and they will be treated the same as
<Form /> and
<Field /> components. You can mix them together and use a
Form component with any other custom component that uses
useField and vice versa.
useForm, vee-validate offers simpler utility composable functions that you can use to build very specific and specialized components that contribute to your form experience, they are mentioned later on in this page.
When to use composition API
Before you go through the details of
useForm, you first need to understand when you should be using the composition functions over the components.
vee-validate does not deal with arbitrary values, meaning you should not (while you could) use the composition API as means to force vee-validate to validate some objects/data. To validate arbitrary values, you can use other libraries or validation tools, like
validator.js which you are likely to use anyways.
To re-iterate, vee-validate is all about forms and inputs. Not values, so if you need a piece of data validated, you need to express it as a form field.
Now that we covered what vee-validate is about, when should you use the composition API over the declarative components?
The declarative components cover tons of use-cases and they are extremely easy to use, for most forms you should use them. They are especially useful if you are working with native HTML input elements, or generally do not have heavy UI customization.
When your input's complexities grow, you might then consider using
useForm. While they require more labor to integrate into your inputs, they give you access to the same logical parts of vee-validate's validation at a much lower level. They are great if you are building your own UI library/framework with form controls.
It's up to you what to do with what
useForm give you, for example
useField doesn't handle input events automatically, you will need to do that.
To summarize, the validation composition API is a great power with a great responsibility.
useForm, these are a collection of simple functions that you can use to opt-in specific parts of vee-validate features like form state and various actions you can perform on fields and forms.
Here are a few examples of what you can build with these functions:
- A custom submission progress component
- A custom error message component.
- A form validity indicators
- reset buttons or submit buttons
Here is a list of the functions available that you can use:
useFieldErrorGives access to a single field's first error message
useFormErrorsGives access to the entire error bag of the form
useIsFieldDirtyIf a field is dirty
useIsFormDirtyIf the form is dirty (form contains at least one dirty field)
useIsFieldTouchedIf a field is touched
useIsFormTouchedIf the form is touched (form contains at least one touched field)
useIsFieldValidIf a field is valid
useIsFormValidIf all fields are validated and valid
useValidateFieldReturns a function that validates a specific field
useValidateFormReturns a function that validates the entire form
useResetFormResets the form to its initial state
useSubmitFormCreates a submission function that validates and submits the form (even if no
formelement is involved)
useIsSubmittingIf the form is currently submitting
useSubmitCountThe number of times the user attempted to submit the form
useFieldValueReturns a specific fields' current value
useFormValuesReturns the current form field values
For more information about the functions, you can head over to the API reference and check them out.