Submission

Handle form submission with validation, loading states, and error handling.

Basic Submission

Use handleSubmit to wrap your submission handler:

<script setup lang="ts">
import { useForm } from '@vuehookform/core'
import { z } from 'zod'

const schema = z.object({
  email: z.email(),
  message: z.string().min(10),
})

const { register, handleSubmit } = useForm({ schema })

const onSubmit = (data: z.infer<typeof schema>) => {
  console.log('Valid data:', data)
  // data is fully typed: { email: string, message: string }
}
</script>

<template>
  <form @submit="handleSubmit(onSubmit)">
    <input v-bind="register('email')" type="email" />
    <textarea v-bind="register('message')"></textarea>
    <button type="submit">Send</button>
  </form>
</template>

How handleSubmit Works

1. Prevents the default form submission
2. Syncs values from uncontrolled inputs
3. Validates all fields against the schema
4. If valid, calls your handler with a deep clone of the typed data (safe to mutate)
5. If invalid, populates formState.value.errors and auto-focuses first error field
6. Manages isSubmitting state automatically
7. Sets isSubmitSuccessful after successful submission

Auto-Focus on Error

By default, the first field with an error is focused after validation fails:

const { handleSubmit } = useForm({
  schema,
  shouldFocusError: true, // Default: true
})

Disable this behavior:

const { handleSubmit } = useForm({
  schema,
  shouldFocusError: false, // Don't auto-focus errors
})

Async Submission

Handle async operations like API calls:

const onSubmit = async (data: z.infer<typeof schema>) => {
  // formState.value.isSubmitting is true during this
  const response = await fetch('/api/submit', {
    method: 'POST',
    body: JSON.stringify(data),
  })

  if (!response.ok) {
    throw new Error('Submission failed')
  }

  // formState.value.isSubmitSuccessful is true after this
}

<template>
  <form @submit="handleSubmit(onSubmit)">
    <!-- fields -->
    <button type="submit" :disabled="formState.value.isSubmitting">
      {{ formState.value.isSubmitting ? 'Sending...' : 'Send' }}
    </button>
  </form>
</template>

Error Handling

Validation Errors

Validation errors are automatically populated:

<template>
  <form @submit="handleSubmit(onSubmit)">
    <input v-bind="register('email')" />
    <span v-if="formState.value.errors.email">
      {{ formState.value.errors.email }}
    </span>
    <button type="submit">Submit</button>
  </form>
</template>

Server Errors

Handle server-side errors manually:

<script setup>
import { ref } from 'vue'

const serverError = (ref < string) | (null > null)

const onSubmit = async (data) => {
  serverError.value = null

  try {
    const response = await fetch('/api/submit', {
      method: 'POST',
      body: JSON.stringify(data),
    })

    if (!response.ok) {
      const error = await response.json()
      serverError.value = error.message
      return
    }

    // Success handling
  } catch (error) {
    serverError.value = 'An unexpected error occurred'
  }
}
</script>

<template>
  <form @submit="handleSubmit(onSubmit)">
    <div v-if="serverError" class="error-banner">
      {{ serverError }}
    </div>
    <!-- fields -->
  </form>
</template>

Server Validation Errors

Map server validation errors back to fields:

const { setError } = useForm({ schema })

const onSubmit = async (data) => {
  const response = await fetch('/api/submit', {
    method: 'POST',
    body: JSON.stringify(data),
  })

  if (!response.ok) {
    const errors = await response.json()

    // Set field-specific errors from server
    if (errors.email) {
      setError('email', errors.email)
    }
    if (errors.username) {
      setError('username', errors.username)
    }
    return
  }
}

Invalid Submission Handler

Handle cases where validation fails:

const onSubmit = (data) => {
  // Only called if valid
  console.log('Valid:', data)
}

const onInvalid = (errors) => {
  // Called when validation fails
  console.log('Errors:', errors)
}

// In template
handleSubmit(onSubmit, onInvalid)

<template>
  <form @submit="handleSubmit(onSubmit, onInvalid)">
    <!-- fields -->
  </form>
</template>

Reset After Submission

Clear the form after successful submission:

const { handleSubmit, reset } = useForm({ schema })

const onSubmit = async (data) => {
  await submitData(data)
  reset() // Clear form
}

Or reset with new values:

const onSubmit = async (data) => {
  const result = await submitData(data)
  reset({
    id: result.id,
    // Pre-populate with server response
  })
}

Preventing Double Submission

The isSubmitting state prevents accidental double submissions:

<template>
  <button
    type="submit"
    :disabled="formState.value.isSubmitting"
    :class="{ 'opacity-50': formState.value.isSubmitting }"
  >
    <span v-if="formState.value.isSubmitting">
      <LoadingSpinner />
      Processing...
    </span>
    <span v-else>Submit</span>
  </button>
</template>

Complete Example

<script setup lang="ts">
import { ref } from 'vue'
import { useForm } from '@vuehookform/core'
import { z } from 'zod'

const schema = z.object({
  name: z.string().min(2),
  email: z.email(),
  message: z.string().min(10),
})

const serverError = ref<string | null>(null)
const submitted = ref(false)

const { register, handleSubmit, formState, reset } = useForm({
  schema,
  mode: 'onBlur',
})

const onSubmit = async (data: z.infer<typeof schema>) => {
  serverError.value = null

  try {
    await fetch('/api/contact', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data),
    })

    submitted.value = true
    reset()
  } catch (error) {
    serverError.value = 'Failed to send message. Please try again.'
  }
}

const onInvalid = () => {
  // Scroll to first error
  const firstError = document.querySelector('.error')
  firstError?.scrollIntoView({ behavior: 'smooth' })
}
</script>

<template>
  <div v-if="submitted" class="success">
    <h2>Thank you!</h2>
    <p>Your message has been sent.</p>
    <button @click="submitted = false">Send another</button>
  </div>

  <form v-else @submit="handleSubmit(onSubmit, onInvalid)">
    <div v-if="serverError" class="error-banner">
      {{ serverError }}
    </div>

    <div class="field">
      <label for="name">Name</label>
      <input id="name" v-bind="register('name')" />
      <span v-if="formState.value.errors.name" class="error">
        {{ formState.value.errors.name }}
      </span>
    </div>

    <div class="field">
      <label for="email">Email</label>
      <input id="email" v-bind="register('email')" type="email" />
      <span v-if="formState.value.errors.email" class="error">
        {{ formState.value.errors.email }}
      </span>
    </div>

    <div class="field">
      <label for="message">Message</label>
      <textarea id="message" v-bind="register('message')" rows="4"></textarea>
      <span v-if="formState.value.errors.message" class="error">
        {{ formState.value.errors.message }}
      </span>
    </div>

    <button type="submit" :disabled="formState.value.isSubmitting">
      {{ formState.value.isSubmitting ? 'Sending...' : 'Send Message' }}
    </button>
  </form>
</template>

Next Steps

• Learn about Controlled Inputs for custom components
• Explore Field Arrays for dynamic forms