vue-use-form

English

简体中文

English

简体中文

Appearance

Return to top
On this page

formState

This object contains information about the entire form state. It helps you to keep on track with the user's interaction with your form application.

  • Type
import type { toRefs } from 'vue'

type FormState<T> = toRefs<{
  isDirty: boolean
  dirtyFields: FieldNamesMarkedBoolean<T>
  isSubmitted: boolean
  isSubmitSuccessful: boolean
  submitCount: number
  isSubmitting: boolean
  isValidating: boolean
  isValid: boolean
  defaultValues: Partial<DefaultValues<TFieldValues>>
  errors: FieldErrors<T>
}>
  • Usage
<script setup>
import { useForm } from 'vue-use-form'

const {
  register,
  formState: { errors },
  isExistInErrors,
} = useForm({
  mode: 'onChange'
})
</script>

<template>
  isError: {{ isExistInErrors('name') }}
  <br>
  errors: {{ errors }}
  <br>
  <input :="register('name', { required: true })">
</template>

Try it on playground

  • Detail

The reason that formState can keep reactivity is use toRefs, so you can access these props by xxx.value

const {
  register,
  formState: { errors },
  isExistInErrors,
} = useForm({
  mode: 'onChange'
})

// access with `.value`
console.log(errors.value)

You may hate the way of access these props with .value, if so, you can use with Reactivity Transform

const {
  register,
  formState: { errors },
  isExistInErrors,
} = $(useForm({
  mode: 'onChange'
}))

// no need to access with `.value`
console.log(errors)

isDirty

Set to true after the user modifies any of the inputs. Type

const isDirty: boolean = false
  • Usage
const {
  formState,
  setValue,
} = useForm({ defaultValues: { test: '' } })

// formState.isDirty: true
setValue('test', 'change')

// formState.isDirty: false because there getValues() === defaultValues
setValue('test', '')

Try it on playground

dirtyFields

An object with the user-modified fields. Make sure to provide all inputs' defaultValues via useForm, so the library can compare against the defaultValues.

  • Type
const dirtyFields: Record<string, boolean> = {}
  • Usage
const {
  formState: { dirtyFields }
} = $(useForm())

defaultValues

The value which has been set at useForm's defaultValues or updated defaultValues via reset API.

  • Type
const dirtyFields: Record<string, boolean> = options.defaultValues || {}
  • Usage
<script setup>
import { useForm } from 'vue-use-form'

const {
  register,
  formState: { defaultValues },
  reset,
} = $(useForm({
  mode: 'onChange'
}))
</script>

<template>
  {{ defaultValues }}
  name: <input :="register('name', { required: true })">

  <button @click="reset({ name: 'a' })">
    reset
  </button>
</template>

try it on playground

isSubmitted

Set to true after the form is submitted. Will remain true until the reset method is invoked.

  • Type
const isSubmitted: boolean = false
  • Usage
<script setup>
import { createSubmitHandler, useForm } from 'vue-use-form'

const {
  register,
  formState: { isSubmitted },
  handleSubmit,
  reset,
} = useForm({
  mode: 'onChange'
})

const onSubmit = createSubmitHandler((data) => {
  alert('submit success')
})
</script>

<template>
  {{ isSubmitted }}
  <form @submit.prevent="handleSubmit(onSubmit)()">
    name: <input :="register('name', { required: true })">
    <button type="submit">
      submit
    </button>
  </form>
  <button @click="reset({})">
    reset
  </button>
</template>

try it on playground

isSubmitSuccessful

Indicate the form was successfully submitted without any Error been thrown within the handleSubmit callback. Will remain true until the reset method is invoked or submit failed.

  • Type
const isSubmitted: boolean = false
  • Usage
<script setup>
import { createSubmitHandler, useForm } from 'vue-use-form'

const {
  register,
  formState: { isSubmitSuccessful },
  handleSubmit,
  reset,
} = useForm({
  mode: 'onChange'
})

const onSubmit = createSubmitHandler((data) => {
  alert('submit success')
})
</script>

<template>
  {{ isSubmitSuccessful }}
  <form @submit.prevent="handleSubmit(onSubmit)()">
    name: <input :="register('name', { required: true })">
    <button type="submit">
      submit
    </button>
  </form>
  <button @click="reset({})">
    reset
  </button>
</template>

try it on playground

submitCount

Number of times the form was submitted.

  • Type
const submitCount: number = 0
  • Usage
<script setup>
import { createSubmitHandler, useForm } from 'vue-use-form'

const {
  register,
  formState: { submitCount },
  handleSubmit,
} = useForm({
  mode: 'onChange'
})

const onSubmit = createSubmitHandler((data) => {
  alert('submit success')
})
</script>

<template>
  {{ submitCount }}
  <form @submit.prevent="handleSubmit(onSubmit)()">
    name: <input :="register('name', { required: true })">
    <button type="submit">
      submit
    </button>
  </form>
</template>

try it on playground

isValid

Set to true if the form doesn't have any errors.

  • Type
const isValid: boolean = false
  • Usage
<script setup>
import { createErrorHandler, createSubmitHandler, useForm } from 'vue-use-form'

const {
  register,
  formState,
  handleSubmit,
} = useForm({
  mode: 'onChange'
})

const onSubmit = createSubmitHandler((data) => {
  alert('submit success')
})

const onError = createErrorHandler((errors) => {
  alert('submit failed')
})
</script>

<template>
  {{ formState.isValid }}
  <form @submit.prevent="handleSubmit(onSubmit, onError)()">
    name: <input :="register('name', { required: true })">
    <button type="submit">
      submit
    </button>
  </form>
</template>

try it on playground

isValidating

Set to true during validation.

  • Type
const isValidating: boolean = false
  • Usage
<script setup>
import { createErrorHandler, createSubmitHandler, useForm } from 'vue-use-form'

const {
  register,
  formState: { isValidating },
  handleSubmit,
} = useForm({
  mode: 'onChange'
})

const onSubmit = createSubmitHandler((data) => {
  alert('submit success')
})

const onError = createErrorHandler((errors) => {
  alert('submit failed')
})

const validate = async () => {
  await new Promise((resolve) => {
      		setTimeout(() => resolve(true), 3000)
      	})
  return true
}
</script>

<template>
  {{ isValidating }}
  <form @submit.prevent="handleSubmit(onSubmit, onError)()">
    name: <input
      :="register('name', {
        required: true,
        validate: {
          async pass() {
            await validate()

            return true
          }
        }
      })"
    >
    <button type="submit">
      submit
    </button>
  </form>
</template>

try it on playground

errors

An object with field errors. There is also an ErrorMessage component to retrieve error message easily.

  • Type
interface ErrorMessage {
  type: string
  message: string
}

const errors: Record<string, ErrorMessag> = {}
  • Usage
<script setup>
import { createErrorHandler, createSubmitHandler, useForm } from 'vue-use-form'

const {
  register,
  formState: { errors },
  isExistInErrors,
  handleSubmit,
} = useForm({
  mode: 'onChange'
})

const onSubmit = createSubmitHandler((data) => {
  alert('submit success')
})

const onError = createErrorHandler((errors) => {
  alert('submit failed')
})
</script>

<template>
  {{ errors }}
  <form @submit.prevent="handleSubmit(onSubmit, onError)()">
    name: <input :="register('name', { required: true })">
    <button type="submit">
      submit
    </button>
  </form>
</template>

try it on playground

Copyright © 2022-present webfansplz