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 useField and 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.

Aside from useField and 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 useField and 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 yup or 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 useField and 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 useField and 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 great responsibility.

Composition Helpers

Aside from useField and 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:

• useFieldError Gives access to a single field’s first error message
• useFormErrors Gives access to the entire error bag of the form
• useIsFieldDirty If a field is dirty
• useIsFormDirty If the form is dirty (form contains at least one dirty field)
• useIsFieldTouched If a field is touched
• useIsFormTouched If the form is touched (form contains at least one touched field)
• useIsFieldValid If a field is valid
• useIsFormValid If all fields are validated and valid
• useValidateField Returns a function that validates a specific field
• useValidateForm Returns a function that validates the entire form
• useResetForm Resets the form to its initial state
• useSubmitForm Creates a submission function that validates and submits the form (even if no form element is involved)
• useIsSubmitting If the form is currently submitting
• useIsValidating If the form is currently validating by validate function
• useSubmitCount The number of times the user attempted to submit the form
• useFieldValue Returns a specific fields’ current value
• useFormValues Returns the current form field values

For more information about the functions, you can head over to the API reference and check them out.