---
layout: ../../layouts/PageLayout.astro
title: Composition Helpers
description: Various composable functions to compose validation logic into your components
order: 9
---

import DocTip from '@/components/DocTip.vue';
import CodeTitle from '@/components/CodeTitle.vue';

# Composition Helpers

The composition helpers are various functions that you can use to craft specialized form components, like a submission indicator component or a custom error messages component.

These functions expose validation state to child components, most of these functions expose 2 variants of each state. On a form level and a field level.

## API Reference

<DocTip>

All of the following code snippets assume you are using them inside a `setup` function.

</DocTip>

<CodeTitle level="4">

`useFieldError(field?: string): ComputedRef<string | undefined>`

</CodeTitle>

Returns a computed ref to a single field's error message, returns `undefined` if no errors were found for that field or if the field does not exist.

```js
import { useFieldError } from 'vee-validate';

const message = useFieldError('fieldName');

message.value; // string or `undefined`
```

You can also use it in a child component that has a parent that used `useField`, The `useFieldError` will automatically pick up the field and produce its error messages.

```js
import { useFieldError } from 'vee-validate';

// Will look for the first parent that used `useField`
const message = useFieldError();
message.value;
```

<CodeTitle level="4">

`useFormErrors(): ComputedRef<Record<string, string | undefined>>`

</CodeTitle>

Returns a computed ref to the error bag of the entire form, fields with no errors will not be included in the error bag object.

```js
import { useFormErrors } from 'vee-validate';

const errors = useFormErrors();

message.value; // {}
```

<CodeTitle level="4">

`useIsFieldDirty(field?: string): ComputedRef<boolean>`

</CodeTitle>

Returns a computed ref to the specified field's `dirty` meta state.

```js
import { useIsFieldDirty } from 'vee-validate';

const isDirty = useIsFieldDirty();

isDirty.value; // true or false
```

You can also use it in a child component that has a parent that used `useField`, The `useIsFieldDirty` will automatically pick up the field and produce its meta `dirty` value

```js
import { useIsFieldDirty } from 'vee-validate';

// Will look for the first parent that used `useField`
const isDirty = useIsFieldDirty();
```

<CodeTitle level="4">

`useIsFormDirty(): ComputedRef<boolean>`

</CodeTitle>

Returns a computed ref to the context form `dirty` meta state.

```js
import { useIsFormDirty } from 'vee-validate';

const isDirty = useIsFormDirty();

isDirty.value; // true or false
```

<CodeTitle level="4">

`useIsFieldTouched(field?: string): ComputedRef<boolean>`

</CodeTitle>

Returns a computed ref to the specified field's `touched` meta state.

```js
import { useIsFieldTouched } from 'vee-validate';

const isTouched = useIsFieldTouched('fieldName');

isTouched.value; // true or false
```

You can also use it in a child component that has a parent that used `useField`, The `useIsFieldTouched` will automatically pick up the field and produce its meta `touched` value

```js
import { useIsFieldTouched } from 'vee-validate';

// Will look for the first parent that used `useField`
const isTouched = useIsFieldTouched();
```

<CodeTitle level="4">

`useIsFormTouched(): ComputedRef<boolean>`

</CodeTitle>

Returns a computed ref to the context form `touched` meta state.

```js
import { useIsFormTouched } from 'vee-validate';

const isTouched = useIsFormTouched();

isTouched.value; // true or false
```

<CodeTitle level="4">

`useIsFieldValid(field?: string): ComputedRef<boolean>`

</CodeTitle>

Returns a computed ref to the specified field's `valid` meta state, inner `value` will be `true` if the field has no errors, and `false` if it has any error message.

```js
import { useIsFieldValid } from 'vee-validate';

const isValid = useIsFieldValid('fieldName');

isValid.value; // true or false
```

You can also use it in a child component that has a parent that used `useField`, The `useIsFieldValid` will automatically pick up the field and produce its meta `valid` value

```js
import { useIsFieldValid } from 'vee-validate';

// Will look for the first parent that used `useField`
const isValid = useIsFieldValid();
```

<DocTip type="warn">

Creating disabled buttons based on the `valid` attribute isn't accurate, because if the field hasn't been validated yet it, the `valid` property will be `true` which isn't accurate. You should combine `valid` checks with `dirty` state to get the most accuracy.

</DocTip>

<CodeTitle level="4">

`useIsFormValid(): ComputedRef<boolean>`

</CodeTitle>

Returns a computed ref to the context form `valid` meta state.

```js
import { useIsFormValid } from 'vee-validate';

const isValid = useIsFormValid();

isValid.value; // true or false
```

<DocTip type="warn">

Creating disabled buttons based on the `valid` attribute isn't accurate, because if the form hasn't been validated yet it, the `valid` property will be `true` which isn't accurate. You should combine `valid` checks with `dirty` state to get the most accuracy.

</DocTip>

<CodeTitle level="4">

`useValidateField(field?: string): () => Promise<ValidationResult>`

</CodeTitle>

Returns a function that validates the field and returns a validation result object containing any errors, if the `errors` field is empty then it means the field is valid. If a field doesn't not exist it will return an empty `errors` field with a warning.

```js
import { useValidateField } from 'vee-validate';

const validate = useValidateField('fieldName');

await validate();
```

You can also use it in a child component that has a parent that used `useField`, The `useValidateField` will automatically pick up the field and will return the function that validates it.

```js
import { useValidateField } from 'vee-validate';

// Will look for the first parent that used `useField`
const validate = useValidateField();
```

<CodeTitle level="4">

`useValidateForm(): () => Promise<FormValidationResult>`

</CodeTitle>

Returns a function that validates the form and returns a `Form`.

```js
import { useValidateForm } from 'vee-validate';

const validate = useValidateForm();

await validate();
```

<CodeTitle level="4">

`useIsSubmitting(): ComputedRef<boolean>`

</CodeTitle>

Returns a computed ref to the form's `isSubmitting` state.

```js
import { useIsSubmitting } from 'vee-validate';

const isSubmitting = useIsSubmitting();

isSubmitting.value; // true or false
```

<CodeTitle level="4">

`useIsValidating(): ComputedRef<boolean>`

</CodeTitle>

Returns a computed ref to the form's `isValidating` state.

```js
import { useIsValidating } from 'vee-validate';

const isValidating = useIsValidating();

isValidating.value; // true or false
```

<CodeTitle level="4">

`useSubmitCount(): ComputedRef<number>`

</CodeTitle>

Returns a computed ref to the form's `submitCount` state.

```js
import { useSubmitCount } from 'vee-validate';

const count = useSubmitCount();

count.value;
```

<CodeTitle level="4">

`useResetForm(): () => void`

</CodeTitle>

Returns a function that you can use to reset the form

```js
import { useResetForm } from 'vee-validate';

const resetForm = useResetForm();

resetForm(); // resets the form
```

<CodeTitle level="4">

`useSubmitForm(cb: SubmissionHandler): () => void`

</CodeTitle>

Returns a function that you can use to validate the form and submit if it turns out valid. It does this by accepting a function that should handle the submission logic like sending data to your API. That function will not run unless the form is valid and it receives all the fields current values packed in an object.

```js
import { useSubmitForm } from 'vee-validate';

const submitForm = useSubmitForm((values, actions) => {
  // Send data to your api ...
  alert(JSON.stringify(values, null, 2));

  // You can perform any of the form actions using the actions object
  // set a single field value
  actions.setFieldValue('field', 'hello');
  // set multiple fields values
  actions.setValues({ email: 'value', password: 'hi' });
  // set a single field error
  actions.setFieldError('field', 'this field is bad');
  // set multiple fields errors
  actions.setErrors({ email: 'bad email', password: 'bad password' });
  // reset the form
  actions.resetForm();
});
```

<DocTip title="Virtual Forms">

While it is recommended to use actual `form` elements for accessibility, you could still use `useSubmitForm` to submit any group of data which may or may not be involved with a `form` element.

</DocTip>

<CodeTitle level="4">

`useFieldValue(field?: string): ComputedRef<any>`

</CodeTitle>

Returns a computed ref to the specified field's current value.

```js
import { useFieldValue } from 'vee-validate';

const currentValue = useFieldValue('fieldName');

currentValue.value;
```

You can also use it in a child component that has a parent that used `useField`, The `useFieldValue` will automatically pick up the field and produce its current value.

```js
import { useFieldValue } from 'vee-validate';

// Will look for the first parent that used `useField`
const currentValue = useFieldValue();
```

<CodeTitle level="4">

`useFormValues(): ComputedRef<Record<string, any>>`

</CodeTitle>

Returns a computed ref to the context form current values.

```js
import { useFormValues } from 'vee-validate';

const values = useFormValues();

values.value;
```
