useForm #

useForm is a custom hook for managing forms with ease. It takes one object as optional argument.

declare function useForm<TFieldValues extends FieldValues = FieldValues>(
  props?: Partial<UseFormProps<TFieldValues>>
): UseFormReturn<TFieldValues>

• Options

interface UseFormProps<TFieldValues extends object> {
  mode: Mode
  reValidateMode: Exclude<Mode, 'onTouched' | 'all'>
  defaultValues: DefaultValues<TFieldValues>
  resolver: Resolver<TFieldValues>
  shouldFocusError: boolean
  criteriaMode: CriteriaMode
  delayError: number
}

mode #

It decide when to trigger validate for

• Type

type Mode = 'onSubmit' | 'onBlur' | 'onChange' | 'onTouched' | 'all'

Details #

• onSubmit: Validation will trigger on the submit event and invalid inputs will attach onChange event listeners to re-validate them.

• onBlur: Validation will trigger on the blur event.

• onChange: Validation will trigger on the change event with each input, and lead to multiple re-renders. Warning: this often comes with a significant impact on performance.

• onTouched: Validation will trigger on the first blur event. After that, it will trigger on every change event.

• all: Validation will trigger on the blur and change events.

reValidateMode #

This option allows you to configure validation strategy when inputs with errors get re-validated after a user submits the form (onSubmit event). By default, validation is triggered during the input change event.

• Type

const reValidateMode: 'onSubmit' | 'onBlur' | 'onChange' = 'onSubmit'

defaultValues #

The defaultValues for inputs are used as the initial value when a component is first rendered, before a user interacts with it. It is encouraged that you set defaultValues for all inputs to non-undefined values such as the empty string or null.

• Type

const defaultValues: Record<string, any> = {}

• Usage

<script setup lang="ts">
interface Inputs {
  username: string
}

const {
  register
} = useForm<Inputs>({
  defaultValues: {
    username: 'Alice'
  }
})
</script>

<template>
  <input :="register('username')">
</template>

shouldFocusError #

When set to true (default) and the user submits a form that fails the validation, it will try to set focus on the first field with an error.

• try to

• Type

const shouldFocusError = true

criteriaMode #

• When set to firstError (default), only the first error from each field will be gathered.

• When set to all, all errors from each field will be gathered.

• Type

const criteriaMode: 'all' | 'firstError' = 'firstError'

resolver #

This function allows you to use any external validation library such as yup, class-validator

• example

<script lang="ts" setup>
import { useForm } from 'vue-use-form'
import * as yup from 'yup'
import { useYupResolver } from '@vue-use-form/yup'

const schema = yup.object().shape({
  username: yup.string().required(),
  age: yup.number().required().positive().integer(),
  email: yup.string().email(),
})

const {
  register,
  formState: { errors },
} = useForm<{
  username: string
  email: string
  age: number
}>({
  resolver: useYupResolver(schema),
})
</script>

<template>
  <input :="register('username')">
  <input :="register('email')">
  <input :="register('age')">
</template>

delayError #

This config will delay the error state to be displayed to the end-user in milliseconds. Correct the error input will remove the error instantly and delay will not be applied.

• Type

const delayError: number = 0