### Install @vuehookform/core dependencies

Source: https://github.com/vuehookform/core/blob/main/docs/guide/quick-start.md

Commands to install the core library and Zod validation package using various package managers.

```npm
npm install @vuehookform/core zod
```

```pnpm
pnpm add @vuehookform/core zod
```

```yarn
yarn add @vuehookform/core zod
```

```bun
bun add @vuehookform/core zod
```

--------------------------------

### Implement a complete login form with Vue Hook Form

Source: https://github.com/vuehookform/core/blob/main/docs/guide/quick-start.md

A full example demonstrating schema definition, form initialization, input registration, and submission handling in a Vue component.

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

const schema = z.object({
  email: z.email('Please enter a valid email'),
  password: z.string().min(8, 'Password must be at least 8 characters'),
})

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

const onSubmit = (data: z.infer<typeof schema>) => {
  console.log('Form data:', data)
}
</script>

<template>
  <form @submit="handleSubmit(onSubmit)">
    <div>
      <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>
      <label for="password">Password</label>
      <input id="password" v-bind="register('password')" type="password" />
      <span v-if="formState.value.errors.password" class="error">
        {{ formState.value.errors.password }}
      </span>
    </div>

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

<style scoped>
.error {
  color: red;
  font-size: 0.875rem;
}
</style>
```

--------------------------------

### Configure form validation and defaults

Source: https://github.com/vuehookform/core/blob/main/docs/guide/quick-start.md

Examples of how to set default form values and configure validation trigger modes.

```typescript
// Setting default values
const { register, handleSubmit, formState } = useForm({
  schema,
  defaultValues: {
    email: 'user@example.com',
    password: '',
  },
})

// Configuring validation modes
useForm({
  schema,
  mode: 'onSubmit', // 'onSubmit', 'onBlur', 'onChange', 'onTouched'
})
```

--------------------------------

### Install Dependencies

Source: https://github.com/vuehookform/core/blob/main/README.md

Command to install the core library and Zod for schema validation.

```bash
npm install @vuehookform/core zod
```

--------------------------------

### Basic Form Setup with Schema

Source: https://github.com/vuehookform/core/blob/main/docs/guide/essentials/form-setup.md

Demonstrates the most basic setup for `useForm` which requires only a Zod schema for validation. This initializes the form with validation rules and provides essential methods like `register` and `handleSubmit`.

```typescript
import { useForm } from '@vuehookform/core'
import { z } from 'zod'

const schema = z.object({
  name: z.string().min(1, 'Name is required'),
})

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

--------------------------------

### Vue Example: Form Preview with All Fields Watched

Source: https://github.com/vuehookform/core/blob/main/docs/api/use-watch.md

Illustrates using useWatch to get all form data reactively, enabling features like a live preview. The example watches all fields and displays them in a separate preview area.

```vue
<script setup>
import { useForm, useWatch } from '@vuehookform/core'

const { control, register, handleSubmit } = useForm({ schema })
const formData = useWatch({ control })
</script>

<template>
  <div class="form-container">
    <form @submit="handleSubmit(onSubmit)">
      <input v-bind="register('title')" />
      <textarea v-bind="register('content')"></textarea>
    </form>

    <div class="preview">
      <h2>Preview</h2>
      <h3>{{ formData.title || 'Untitled' }}</h3>
      <p>{{ formData.content || 'No content yet...' }}</p>
    </div>
  </div>
</template>
```

--------------------------------

### Create Custom Input Component

Source: https://github.com/vuehookform/core/blob/main/docs/api/use-controller.md

A complete example of a reusable custom input component using useController to bind field state and validation errors.

```vue
<script setup lang="ts">
import { useController } from '@vuehookform/core'
import type { Control } from '@vuehookform/core'

const props = defineProps<{ name: string, control: Control<any>, label?: string }>()

const { field, fieldState } = useController({
  name: props.name,
  control: props.control,
})
</script>

<template>
  <input
    :value="field.value"
    @input="field.onChange(($event.target as HTMLInputElement).value)"
    @blur="field.onBlur"
  />
  <span v-if="fieldState.error">{{ fieldState.error }}</span>
</template>
```

--------------------------------

### Implement Multi-Step Wizard Validation

Source: https://github.com/vuehookform/core/blob/main/docs/examples/index.md

Demonstrates how to trigger partial form validation to control navigation between wizard steps.

```vue
<script setup>
import { ref } from 'vue'
import { useForm } from '@vuehookform/core'

const step = ref(1)
const { register, handleSubmit, trigger } = useForm({ schema })

const nextStep = async () => {
  const valid = await trigger(stepFields[step.value])
  if (valid) step.value++
}
</script>
```

--------------------------------

### Form Setup with Default Values

Source: https://github.com/vuehookform/core/blob/main/docs/guide/essentials/form-setup.md

Shows how to pre-populate form fields using the `defaultValues` option in `useForm`. The provided default values must match the structure defined by the schema, and TypeScript will enforce this. This is useful for editing existing data or providing initial user settings.

```typescript
const form = useForm({
  schema,
  defaultValues: {
    email: 'user@example.com',
    age: 25,
    preferences: {
      newsletter: true,
    },
  },
})
```

--------------------------------

### Vue Example: Watch Single Field

Source: https://github.com/vuehookform/core/blob/main/docs/api/use-watch.md

A complete Vue component example demonstrating how to use useWatch to display a single field's value reactively. It includes setup with useForm and rendering an input linked to the watched field.

```vue
<script setup>
import { useForm, useWatch } from '@vuehookform/core'

const { control, register } = useForm({ schema })
const email = useWatch({ control, name: 'email' })
</script>

<template>
  <input v-bind="register('email')" />
  <p>Current email: {{ email }}</p>
</template>
```

--------------------------------

### Form Setup with Async Default Values

Source: https://github.com/vuehookform/core/blob/main/docs/guide/essentials/form-setup.md

Demonstrates configuring `useForm` to load default values asynchronously, typically from an API. The `defaultValues` option accepts an async function that returns the initial data. Error handling for the async operation is managed via `onDefaultValuesError`.

```typescript
const { formState } = useForm({
  schema,
  defaultValues: async () => {
    const response = await fetch('/api/user')
    return response.json()
  },
  onDefaultValuesError: (error) => {
    console.error('Failed to load:', error)
  },
})
```

--------------------------------

### useWatch Return Value Examples

Source: https://github.com/vuehookform/core/blob/main/docs/api/use-watch.md

Provides examples of the return types for useWatch when watching single fields, multiple fields, and all fields. The hook returns reactive refs containing the watched values.

```typescript
// Single field
const email: Ref<string> = useWatch({ control, name: 'email' })

// Multiple fields
const values: Ref<[string, string]> = useWatch({
  control,
  name: ['email', 'password'],
})

// All fields
const all: Ref<FormValues> = useWatch({ control })
```

--------------------------------

### Implement Basic Form with Validation

Source: https://github.com/vuehookform/core/blob/main/README.md

A complete example showing how to initialize a form with Zod schema, register inputs, and handle submission in a Vue 3 component.

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

const schema = z.object({
  email: z.email('Invalid email'),
  password: z.string().min(8, 'At least 8 characters'),
})

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

const onSubmit = (data) => {
  console.log(data) // Fully typed: { email: string, password: string }
}
</script>

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

    <input v-bind="register('password')" type="password" />
    <span v-if="formState.value.errors.password">{{ formState.value.errors.password }}</span>

    <button type="submit" :disabled="formState.value.isSubmitting">Submit</button>
  </form>
</template>
```

--------------------------------

### Vue Example: Watching Multiple Fields for Combined Value

Source: https://github.com/vuehookform/core/blob/main/docs/api/use-watch.md

Demonstrates watching multiple specific fields and combining their values using Vue's computed property. This example creates a 'fullName' from 'firstName' and 'lastName'.

```vue
<script setup>
import { computed } from 'vue'
import { useForm, useWatch } from '@vuehookform/core'

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

const [firstName, lastName] = useWatch({
  control,
  name: ['firstName', 'lastName'],
})

const fullName = computed(() => {
  return `${firstName.value || ''} ${lastName.value || ''}`.trim()
})
</script>

<template>
  <input v-bind="register('firstName')" />
  <input v-bind="register('lastName')" />
  <p>Full name: {{ fullName || 'Enter your name' }}</p>
</template>
```

--------------------------------

### Vue Example: Computing Derived Values

Source: https://github.com/vuehookform/core/blob/main/docs/api/use-watch.md

Shows how to use useWatch in conjunction with Vue's computed property to derive values based on other form fields. This example calculates a 'total' price from 'quantity' and 'unitPrice'.

```vue
<script setup>
import { computed } from 'vue'
import { useForm, useWatch } from '@vuehookform/core'

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

const quantity = useWatch({ control, name: 'quantity' })
const unitPrice = useWatch({ control, name: 'unitPrice' })

const total = computed(() => {
  return (quantity.value || 0) * (unitPrice.value || 0)
})
</script>

<template>
  <input v-bind="register('quantity')" type="number" />
  <input v-bind="register('unitPrice')" type="number" />
  <p>Total: ${{ total.toFixed(2) }}</p>
</template>
```

--------------------------------

### Implement Dynamic Field Arrays in Vue

Source: https://github.com/vuehookform/core/blob/main/docs/guide/dynamic/field-arrays.md

Demonstrates the basic setup of a dynamic form using VueHookForm's fields API. It includes schema definition with Zod, form initialization, and rendering repeatable input fields.

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

const schema = z.object({
  items: z.array(
    z.object({
      name: z.string().min(1, 'Name required'),
      quantity: z.number().min(1, 'Min 1'),
    }),
  ),
})

const { register, handleSubmit, fields, formState } = useForm({
  schema,
  defaultValues: {
    items: [{ name: '', quantity: 1 }],
  },
})

const items = fields('items')
</script>

<template>
  <form @submit="handleSubmit(onSubmit)">
    <div v-for="field in items.value" :key="field.key" class="item-row">
      <input v-bind="register(`items.${field.index}.name`)" placeholder="Item name" />
      <input v-bind="register(`items.${field.index}.quantity`)" type="number" />
      <button type="button" @click="field.remove()">Remove</button>
    </div>

    <button type="button" @click="items.append({ name: '', quantity: 1 })">Add Item</button>

    <button type="submit">Submit</button>
  </form>
</template>
```

--------------------------------

### Share Form Context via Provide/Inject

Source: https://github.com/vuehookform/core/blob/main/docs/examples/index.md

Uses provideForm to share form state and methods across deeply nested component trees.

```vue
<script setup>
import { useForm, provideForm } from '@vuehookform/core'

const form = useForm({ schema })
provideForm(form) // Make form available to all descendants
</script>

<template>
  <form @submit="form.handleSubmit(onSubmit)">
    <PersonalInfoSection />
    <AddressSection />
    <PreferencesSection />
    <SubmitButton />
  </form>
</template>
```

--------------------------------

### Field Array Setup with Zod Schema in TypeScript

Source: https://github.com/vuehookform/core/blob/main/docs/public/llms.txt

Shows the setup for a field array using Vue Hook Form, including defining a Zod schema for validation and using 'fields' and 'register' to manage dynamic lists of form elements.

```typescript
const schema = z.object({
  items: z.array(z.object({
    name: z.string().min(1),
    quantity: z.number().min(1)
  })).min(1)
})

const { fields, register } = useForm({
  schema,
  defaultValues: { items: [{ name: '', quantity: 1 }] }
})

const itemFields = fields('items')
```

--------------------------------

### Implement Dynamic Field Array with Scoped Methods

Source: https://github.com/vuehookform/core/blob/main/docs/guide/dynamic/field-arrays.md

A complete example of a dynamic form using @vuehookform/core, demonstrating scoped registration, error handling, and item manipulation.

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

const schema = z.object({
  items: z.array(
    z.object({
      name: z.string().min(1, 'Name required'),
      price: z.number().min(0, 'Price must be positive'),
    }),
  ),
})

const { fields, formState, handleSubmit } = useForm({
  schema,
  defaultValues: { items: [{ name: '', price: 0 }] },
})

const items = fields('items')
</script>

<template>
  <form @submit="handleSubmit(onSubmit)">
    <div v-for="field in items.value" :key="field.key" class="item-row">
      <input v-bind="field.register('name')" placeholder="Item name" />
      <input v-bind="field.register('price')" type="number" placeholder="Price" />

      <span v-if="field.getFieldState('name').error" class="error">
        {{ field.getFieldState('name').error }}
      </span>

      <button type="button" @click="field.remove()">Remove</button>
    </div>

    <button type="button" @click="items.append({ name: '', price: 0 })">Add Item</button>
    <button type="submit">Submit</button>
  </form>
</template>
```

--------------------------------

### Implement User Registration Form with Validation

Source: https://github.com/vuehookform/core/blob/main/docs/examples/index.md

Demonstrates a basic registration form using Zod for schema validation. It includes a custom refinement to ensure password and confirmPassword fields match.

```vue
<script setup>
import { useForm } from '@vuehookform/core'
import { z } from 'zod'

const schema = z
  .object({
    name: z.string().min(2),
    email: z.string().email(),
    password: z.string().min(8),
    confirmPassword: z.string(),
  })
  .refine((data) => data.password === data.confirmPassword, {
    message: 'Passwords must match',
    path: ['confirmPassword'],
  })

const { register, handleSubmit, formState } = useForm({ schema })
</script>
```

--------------------------------

### Form Setup with Disabled State

Source: https://github.com/vuehookform/core/blob/main/docs/guide/essentials/form-setup.md

Shows how to disable the entire form using a reactive `ref` passed to the `disabled` option in `useForm`. When disabled, all inputs are marked with the `disabled` attribute, and form submission is prevented, which is useful during loading states.

```typescript
import { ref } from 'vue'

const isLoading = ref(false)

const form = useForm({
  schema,
  disabled: isLoading, // Reactive ref
})
```

--------------------------------

### Conventional Commits for Release Management

Source: https://github.com/vuehookform/core/blob/main/CLAUDE.md

Examples of Git commit messages following conventional commit standards for triggering automated releases with Release Please. Covers patch, minor, and major version bumps, as well as non-release commits.

```bash
# Patch release (0.3.1 → 0.3.2)
git commit -m "fix: correct validation error message formatting"

# Minor release (0.3.2 → 0.4.0)
git commit -m "feat: add onTouched validation mode"

# Major release (0.4.0 → 1.0.0)
git commit -m "feat!: change register() return type"
# or
git commit -m "feat: new API

BREAKING CHANGE: register() now returns an object instead of array"

# No release triggered
git commit -m "docs: update README examples"
git commit -m "chore: update CI workflow"
```

--------------------------------

### Provide and Use Form Context in Vue

Source: https://github.com/vuehookform/core/blob/main/docs/examples/index.md

Demonstrates how to provide a form instance to all descendant components using `provideForm` and access it in deeply nested components using `useFormContext`. This pattern avoids prop drilling in complex component trees.

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

const schema = z.object({
  firstName: z.string().min(2, 'At least 2 characters'),
  lastName: z.string().min(2, 'At least 2 characters'),
  email: z.string().email('Invalid email'),
  phone: z.string().min(10, 'Invalid phone number'),
})

const form = useForm({
  schema,
  mode: 'onBlur',
})

// Make form available to ALL descendants ✅
provideForm(form)

const onSubmit = (data) => {
  console.log('Form submitted:', data)
}
</script>

<template>
  <form @submit="form.handleSubmit(onSubmit)" class="form-wrapper">
    <h2>Contact Information</h2>
    <PersonalInfoSection />
    <ContactSection />
    <button type="submit" :disabled="form.formState.value.isSubmitting">Submit</button>
  </form>
</template>
```

```vue
<script setup lang="ts">
import { useFormContext } from '@vuehookform/core'
import FormInput from './FormInput.vue'

// Access form from any depth in the component tree ✅
const { register, formState } = useFormContext()
</script>

<template>
  <section>
    <h3>Personal Info</h3>
    <FormInput name="firstName" label="First Name" />
    <FormInput name="lastName" label="Last Name" />
  </section>
</template>
```

```vue
<script setup lang="ts">
import { computed } from 'vue'
import { useFormContext } from '@vuehookform/core'

const props = defineProps({
  name: String,
  label: String,
  type: String,
})

const { register, formState } = useFormContext()

// Use computed to reactively access errors ✅
const error = computed(() => formState.value.errors[props.name])
const isTouched = computed(() => formState.value.touchedFields[props.name])
</script>

<template>
  <div class="form-input">
    <label v-if="label" :for="name">{{ label }}</label>
    <input
      :id="name"
      v-bind="register(name)"
      :type="type ?? 'text'"
      :class="{ 'has-error': error }"
    />
    <!-- Error updates reactively via computed ✅ -->
    <span v-if="error" class="error">{{ error }}</span>
    <span v-if="isTouched && !error" class="success">✓</span>
  </div>
</template>

<style scoped>
.form-input {
  margin-bottom: 1rem;
}
label {
  display: block;
  margin-bottom: 0.25rem;
}
input {
  width: 100%;
  padding: 0.5rem;
  border: 1px solid #ccc;
  border-radius: 4px;
}
.has-error {
  border-color: #ef4444;
}
.error {
  color: #ef4444;
  font-size: 0.875rem;
}
.success {
  color: #10b981;
  font-size: 0.875rem;
}
</style>
```

--------------------------------

### Vue Example: Conditional Rendering based on Field Value

Source: https://github.com/vuehookform/core/blob/main/docs/api/use-watch.md

Demonstrates using useWatch to control UI rendering based on a specific form field's value. The example shows conditional display of input fields based on the 'accountType' selection.

```vue
<script setup>
import { useForm, useWatch } from '@vuehookform/core'

const { control, register } = useForm({ schema })
const accountType = useWatch({ control, name: 'accountType' })
</script>

<template>
  <select v-bind="register('accountType')">
    <option value="personal">Personal</option>
    <option value="business">Business</option>
  </select>

  <!-- Only show for business accounts -->
  <div v-if="accountType === 'business'">
    <input v-bind="register('companyName')" placeholder="Company Name" />
    <input v-bind="register('taxId')" placeholder="Tax ID" />
  </div>
</template>
```

--------------------------------

### Configure Dynamic Validation Modes

Source: https://github.com/vuehookform/core/blob/main/docs/examples/index.md

Illustrates how to switch between different validation modes (onSubmit, onBlur, onChange, onTouched) dynamically. It uses a shallowRef to re-initialize the form instance when the mode changes.

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

const schema = z.object({
  email: z.string().email('Invalid email'),
  username: z.string().min(3, 'Username must be at least 3 characters'),
})

const selectedMode = ref<ValidationMode>('onSubmit')
const formKey = ref(0)

const createForm = (mode: ValidationMode) => {
  return useForm({
    schema,
    mode,
    defaultValues: { email: '', username: '' },
  })
}

const form = shallowRef(createForm(selectedMode.value))

const onModeChange = () => {
  form.value = createForm(selectedMode.value)
  formKey.value++
}
</script>

<template>
  <select v-model="selectedMode" @change="onModeChange">
    <option value="onSubmit">onSubmit</option>
    <option value="onBlur">onBlur</option>
    <option value="onChange">onChange</option>
    <option value="onTouched">onTouched</option>
  </select>

  <form :key="formKey" @submit.prevent="form.handleSubmit(onSubmit)($event)">
    <input v-bind="form.register('email')" />
    <input v-bind="form.register('username')" />
  </form>
</template>
```

--------------------------------

### Implement Form Management with @vuehookform/core and Zod

Source: https://github.com/vuehookform/core/blob/main/docs/guide/advanced/programmatic-control.md

This example demonstrates how to initialize a form with Zod validation schemas, handle field registration, manage form state, and perform manual operations like resetting, triggering validation, and setting server-side errors.

```vue
<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(1),
  email: z.email(),
  role: z.enum(['admin', 'user', 'guest']),
})

const { register, handleSubmit, formState, setValue, getValues, reset, trigger, setError, clearErrors } = useForm({
  schema,
  defaultValues: { name: '', email: '', role: 'user' },
})

const isEditing = ref(false)
const originalData = ref(null)

const loadUser = async (userId: string) => {
  const user = await fetchUser(userId)
  reset(user)
  originalData.value = user
  isEditing.value = true
}

const cancelEdit = () => {
  originalData.value ? reset(originalData.value) : reset()
}

const onSubmit = async (data) => {
  clearErrors()
  try {
    const result = await saveUser(data)
    if (result.success) {
      reset()
      isEditing.value = false
    }
  } catch (error) {
    if (error.validationErrors) {
      for (const [field, message] of Object.entries(error.validationErrors)) {
        setError(field, message)
      }
    }
  }
}
</script>

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

--------------------------------

### Create Dynamic Shopping Cart Form

Source: https://github.com/vuehookform/core/blob/main/docs/examples/index.md

Shows how to manage a dynamic list of items using field arrays. Users can append or remove items, with each item validated against a quantity constraint.

```vue
<script setup>
import { useForm } from '@vuehookform/core'
import { z } from 'zod'

const schema = z.object({
  items: z
    .array(
      z.object({
        product: z.string(),
        quantity: z.number().min(1),
      }),
    )
    .min(1),
})

const { register, handleSubmit, fields } = useForm({
  schema,
  defaultValues: { items: [{ product: '', quantity: 1 }] },
})

const items = fields('items')
</script>

<template>
  <form @submit="handleSubmit(onSubmit)">
    <div v-for="field in items.value" :key="field.key">
      <input v-bind="register(`items.${field.index}.product`)" />
      <input v-bind="register(`items.${field.index}.quantity`)" type="number" />
      <button type="button" @click="items.remove(field.index)">Remove</button>
    </div>
    <button type="button" @click="items.append({ product: '', quantity: 1 })">Add Item</button>
    <button type="submit">Checkout</button>
  </form>
</template>
```

--------------------------------

### Field Array Rendering and Manipulation in Vue

Source: https://github.com/vuehookform/core/blob/main/docs/public/llms.txt

Provides a Vue template example for rendering and managing a field array. It shows how to iterate over fields, bind inputs using 'register', and handle adding/removing items.

```vue
<div v-for="field in itemFields.value" :key="field.key">
  <!-- CRITICAL: Use field.key for :key, NOT index -->
  <input v-bind="register(`items.${field.index}.name`)" />
  <input v-bind="register(`items.${field.index}.quantity`)" type="number" />
  <button @click="field.remove()">Remove</button>
</div>
<button @click="itemFields.append({ name: '', quantity: 1 })">Add</button>
```

--------------------------------

### Form Configuration with Zod Schema

Source: https://github.com/vuehookform/core/blob/main/docs/guide/essentials/form-setup.md

Illustrates how to configure `useForm` with a Zod schema, defining field types and validation rules such as email format and minimum age. The schema dictates the structure and constraints of the form data.

```typescript
const schema = z.object({
  email: z.email(),
  age: z.number().min(18),
  preferences: z.object({
    newsletter: z.boolean(),
  }),
})

const form = useForm({ schema })
```

--------------------------------

### Form Configuration with Validation Mode

Source: https://github.com/vuehookform/core/blob/main/docs/guide/essentials/form-setup.md

Explains how to control when form validation occurs using the `mode` option in `useForm`. Available modes include 'onSubmit', 'onBlur', 'onChange', and 'onTouched', allowing developers to tailor the validation experience.

```typescript
const form = useForm({
  schema,
  mode: 'onBlur', // 'onSubmit' | 'onBlur' | 'onChange' | 'onTouched'
})
```

--------------------------------

### Configure useController Options

Source: https://github.com/vuehookform/core/blob/main/docs/api/use-controller.md

Demonstrates how to initialize useController with specific options like name, control, and custom default values.

```typescript
const controller = useController({
  name: 'country',
  control,
  defaultValue: 'US',
})
```

--------------------------------

### Dynamic Field Arrays with Vue Hook Form Core

Source: https://github.com/vuehookform/core/blob/main/docs/examples/index.md

Manages dynamic arrays of form fields, supporting adding, removing, and validation. It emphasizes using `field.key` for Vue's `:key` binding and requires the `fields` function to be called within the setup context.

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

const schema = z.object({
  name: z.string().min(2),
  addresses: z
    .array(
      z.object({
        street: z.string().min(1, 'Street is required'),
        city: z.string().min(1, 'City is required'),
      }),
    )
    .min(1),
})

const { register, handleSubmit, fields, getErrors } = useForm({
  schema,
  defaultValues: {
    name: '',
    addresses: [{ street: '', city: '' }],
  },
})

// Call fields() in setup, not in template
const addressFields = fields('addresses', {
  rules: { minLength: { value: 1, message: 'At least one address required' } },
})
</script>

<template>
  <form @submit="handleSubmit(onSubmit)">
    <input v-bind="register('name')" />

    <!-- Always use field.key for :key -->
    <div v-for="field in addressFields.value" :key="field.key">
      <h4>Address {{ field.index + 1 }}</h4>
      <input v-bind="register(`addresses.${field.index}.street`)" />
      <input v-bind="register(`addresses.${field.index}.city`)" />
      <button type="button" @click="addressFields.remove(field.index)">Remove</button>
    </div>

    <button type="button" @click="addressFields.append({ street: '', city: '' })">
      Add Address
    </button>
  </form>
</template>
```

--------------------------------

### Initialize useController

Source: https://github.com/vuehookform/core/blob/main/docs/api/use-controller.md

Basic implementation of the useController composable to manage a specific form field. It requires the field name and the control object from useForm.

```typescript
import { useController } from '@vuehookform/core'

const { field, fieldState } = useController({
  name: 'email',
  control,
})
```

--------------------------------

### Complete Form Example with Validation and API (Vue)

Source: https://github.com/vuehookform/core/blob/main/docs/guide/essentials/submission.md

A comprehensive Vue.js example using Vue Hook Form for form management. It includes schema validation with Zod, handling form submission to an API endpoint, displaying server errors, and managing submission state. The `useForm` hook is central to this example.

```vue
<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>
```

--------------------------------

### Initialize Form with Async Default Values

Source: https://github.com/vuehookform/core/blob/main/docs/guide/advanced/async-patterns.md

Demonstrates how to fetch initial form data from an API using an async function within the useForm configuration. It also shows how to use isLoading to manage UI states during the fetch.

```vue
<script setup>
import { useForm } from '@vuehookform/core'

const { register, handleSubmit, formState } = useForm({
  schema,
  defaultValues: async () => {
    const response = await fetch('/api/user/profile')
    return response.json()
  },
})
</script>

<template>
  <div v-if="formState.value.isLoading" class="loading">Loading form data...</div>

  <form v-else @submit="handleSubmit(onSubmit)">
    <input v-bind="register('name')" />
    <input v-bind="register('email')" />
    <button type="submit">Save</button>
  </form>
</template>
```

--------------------------------

### Configure form options

Source: https://github.com/vuehookform/core/blob/main/docs/api/use-form.md

Various configuration options for useForm including default values, validation modes, and performance settings like debouncing.

```typescript
const form = useForm({
  schema,
  defaultValues: { email: 'user@example.com', age: 25 },
  mode: 'onChange',
  validationDebounce: 150,
  delayError: 300
})
```

--------------------------------

### useForm Return Values Overview

Source: https://github.com/vuehookform/core/blob/main/docs/guide/essentials/form-setup.md

Lists the comprehensive set of values returned by the `useForm` hook, including methods for input registration, submission handling, form state management, programmatic control, validation, error manipulation, and focus management.

```typescript
const {
  // Register inputs
  register,
  unregister,

  // Handle form submission
  handleSubmit,

  // Reactive form state
  formState,

  // Field array management
  fields,

  // Programmatic control
  setValue,
  getValue,
  getValues,
  getFieldState,
  reset,
  resetField,

  // Validation
  trigger, // Manually trigger validation

  // Error management
  setError,
  setErrors,
  clearErrors,
  hasErrors,
  getErrors,

  // Watch field values
  watch,

  // Focus management
  setFocus,

  // For child components
  control,
} = useForm({ schema })
```

--------------------------------

### Vue Example: Watching Field in Child Component

Source: https://github.com/vuehookform/core/blob/main/docs/api/use-watch.md

Shows how to watch a form field from a parent component within a child component using the 'control' prop. This example calculates password strength based on the 'password' field.

```vue
<!-- PasswordStrength.vue -->
<script setup>
import { computed } from 'vue'
import { useWatch } from '@vuehookform/core'
import type { Control } from '@vuehookform/core'

const props = defineProps({
  control: { type: Object, required: true } // Explicitly define type if possible
})

const password = useWatch({
  control: props.control,
  name: 'password',
  defaultValue: '',
})

const strength = computed(() => {
  const p = password.value
  if (!p) return 0
  let score = 0
  if (p.length >= 8) score++
  if (/[A-Z]/.test(p)) score++
  if (/[0-9]/.test(p)) score++
  if (/[^A-Za-z0-9]/.test(p)) score++
  return score
})

const strengthLabel = computed(() => {
  const labels = ['Weak', 'Fair', 'Good', 'Strong']
  return labels[strength.value - 1] || 'Too short'
})
</script>

<template>
  <div class="password-strength">
    <div class="strength-bar" :data-strength="strength" />
    <span>{{ strengthLabel }}</span>
  </div>
</template>
```

--------------------------------

### Calling fields() Outside of Setup

Source: https://github.com/vuehookform/core/blob/main/docs/public/llms.txt

Discourages calling the `fields()` function directly within the template of a Vue component. It recommends fetching the field array in the `setup` function and then using the result in the template for better performance and maintainability.

```vue
<!-- WRONG: <div v-for="item in fields('items').value"> -->

<!-- RIGHT: -->
<script setup>
const items = fields('items') // in setup
</script>
<template>
  <div v-for="item in items.value">
    <!-- ... item content ... -->
  </div>
</template>
```

--------------------------------

### Vue Hook Form Error Structure Example

Source: https://github.com/vuehookform/core/blob/main/docs/guide/essentials/error-handling.md

Illustrates the nested structure of validation errors in Vue Hook Form, which mirrors the schema definition. This example shows how to access errors for nested objects, arrays, and their properties.

```typescript
const schema = z.object({
  email: z.email(),
  profile: z.object({
    name: z.string(),
    bio: z.string(),
  }),
  items: z.array(
    z.object({
      title: z.string(),
    }),
  ),
})

// Accessing errors
formState.value.errors.email // string | undefined
formState.value.errors.profile?.name // string | undefined
formState.value.errors.items?.[0]?.title // string | undefined
```

--------------------------------

### Initialize useForm with Zod schema

Source: https://github.com/vuehookform/core/blob/main/docs/api/use-form.md

Basic usage of the useForm composable to manage form state using a Zod validation schema.

```typescript
import { useForm } from '@vuehookform/core'

const form = useForm({
  schema: z.object({
    email: z.email(),
    password: z.string().min(8),
  }),
})
```

--------------------------------

### Track Async Loading States

Source: https://github.com/vuehookform/core/blob/main/docs/guide/advanced/async-patterns.md

Explains the use of isLoading and isReady properties to provide feedback to users while the form is initializing.

```vue
<script setup>
const { formState } = useForm({
  schema,
  defaultValues: async () => fetchUserData(),
})

const loading = computed(() => formState.value.isLoading)
const ready = computed(() => formState.value.isReady)
</script>

<template>
  <div v-if="!formState.value.isReady">
    <Spinner />
  </div>
  <form v-else>...</form>
</template>
```

--------------------------------

### Form Setup with Field Unregistration Control

Source: https://github.com/vuehookform/core/blob/main/docs/guide/essentials/form-setup.md

Configures `useForm` to control whether field data is removed when a field unmounts using `shouldUnregister`. Setting it to `true` removes field data, useful for dynamic forms, while `false` (default) retains data for persistence, suitable for multi-step forms.

```typescript
const form = useForm({
  schema,
  shouldUnregister: true, // Remove data when fields unmount (default: false)
})
```

--------------------------------

### Handling Dynamic Paths with Loose Overloads

Source: https://github.com/vuehookform/core/blob/main/docs/api/use-form.md

Demonstrates how loose overloads allow dynamic path construction, such as array indexing, which would otherwise fail TypeScript's strict template literal type checking.

```typescript
const index = 0;
// Without loose overloads, this would require a cast
register(`items.${index}.name`); // TypeScript can't verify this at compile time

// With loose overloads, it works without casts
register(`items.${index}.name`); // ✅ Accepted by loose overload
```

--------------------------------

### Handle Validation Modes

Source: https://github.com/vuehookform/core/blob/main/docs/api/use-controller.md

Shows how useController respects form validation modes and reValidateMode settings after submission.

```typescript
const { control } = useForm({
  schema,
  mode: 'onSubmit',
  reValidateMode: 'onChange',
})

const { field } = useController({ name: 'email', control })
```

--------------------------------

### Avoid Non-Reactive Error Display Patterns

Source: https://github.com/vuehookform/core/blob/main/docs/examples/index.md

Highlights a common anti-pattern where getFieldState is used incorrectly, resulting in non-reactive error messages that fail to update.

```vue
<script setup lang="ts">
import { useFormContext } from '@vuehookform/core'

const props = defineProps<{ name: string }>()

// ❌ WRONG: Snapshot never updates!
const fieldState = useFormContext().getFieldState(props.name)
</script>

<template>
  <div>
    <input v-bind="register(name)" />
    <!-- This error will NEVER clear, even after fixing the input -->
    <span v-if="fieldState.error" class="error">{{ fieldState.error }}</span>
  </div>
</template>
```

--------------------------------

### Initialize Form State with useForm

Source: https://github.com/vuehookform/core/blob/main/docs/guide/index.md

Demonstrates the core composable used to manage form state, including registration, submission handling, and state tracking based on a provided schema.

```typescript
const { register, handleSubmit, formState, fields } = useForm({ schema })
```

--------------------------------

### Implement Reusable Components with LooseControl

Source: https://github.com/vuehookform/core/blob/main/docs/api/use-controller.md

Demonstrates the use of LooseControl to create generic, reusable form components that work across different form schemas without explicit type casting.

```vue
<!-- FormInput.vue - Reusable component -->
<script setup lang="ts">
import { useController } from '@vuehookform/core'
import type { LooseControl } from '@vuehookform/core'

const props = defineProps<{
  name: string
  control: LooseControl
  label?: string
  placeholder?: string
}>()

const { field, fieldState } = useController({
  name: props.name,
  control: props.control,
})
</script>

<template>
  <div class="form-field">
    <label v-if="label" :for="name">{{ label }}</label>
    <input
      :id="name"
      :name="field.name"
      :value="field.value"
      :placeholder="placeholder"
      @input="field.onChange(($event.target as HTMLInputElement).value)"
      @blur="field.onBlur"
    />
    <span v-if="fieldState.error" class="error">
      {{ fieldState.error }}
    </span>
  </div>
</template>
```

--------------------------------

### Handle Async Initialization Errors

Source: https://github.com/vuehookform/core/blob/main/docs/guide/advanced/async-patterns.md

Shows how to catch errors during async default value loading using onDefaultValuesError and how to display error states in the template.

```typescript
const { formState } = useForm({
  schema,
  defaultValues: async () => {
    const response = await fetch('/api/user/profile')
    if (!response.ok) {
      throw new Error('Failed to load profile')
    }
    return response.json()
  },
  onDefaultValuesError: (error) => {
    console.error('Failed to load form data:', error)
    toast.error('Could not load your profile data')
  },
})
```

```vue
<template>
  <div v-if="formState.value.isLoading">Loading...</div>

  <div v-else-if="formState.value.defaultValuesError" class="error">
    Failed to load form data.
    <button @click="retryLoad">Retry</button>
  </div>

  <form v-else @submit="handleSubmit(onSubmit)">
  </form>
</template>
```

--------------------------------

### Define Survey Schema with Discriminated Unions

Source: https://github.com/vuehookform/core/blob/main/docs/examples/index.md

Utilizes Zod's discriminated unions to handle heterogeneous form structures, such as different question types in a survey.

```vue
<script setup>
import { useForm } from '@vuehookform/core'
import { z } from 'zod'

const questionSchema = z.discriminatedUnion('type', [
  z.object({
    type: z.literal('text'),
    question: z.string(),
    answer: z.string(),
  }),
  z.object({
    type: z.literal('rating'),
    question: z.string(),
    rating: z.number().min(1).max(5),
  }),
])

const schema = z.object({
  title: z.string(),
  questions: z.array(questionSchema),
})
</script>
```

--------------------------------

### Field Arrays: Scoped Methods vs Loose Overloads

Source: https://github.com/vuehookform/core/blob/main/docs/api/use-form.md

Compares the recommended approach of using scoped methods for full type safety against using loose overloads for dynamic path construction in field arrays.

```typescript
const items = fields('items');

// Option 1: Scoped methods (recommended) - full type safety
items.value.forEach((field) => {
  field.register('name'); // ✅ Full type safety
});

// Option 2: Loose overloads - no cast needed
items.value.forEach((field) => {
  register(`items.${field.index}.name`); // ✅ Works without cast
});
```

--------------------------------

### Display Validation Errors in Vue Hook Form

Source: https://github.com/vuehookform/core/blob/main/docs/guide/essentials/submission.md

Provides an example of how to display client-side validation errors associated with specific form fields. It checks `formState.value.errors` for each field.

```vue
<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>
```

--------------------------------

### Compare Manual vs Scoped Field Registration

Source: https://github.com/vuehookform/core/blob/main/docs/guide/dynamic/field-arrays.md

Shows the difference between manually constructing paths for form fields versus using scoped methods provided by field array items for cleaner, type-safe code.

```vue
<!-- Manual path building (verbose) -->
<input v-bind="register(`items.${field.index}.name`)" />
<input v-bind="register(`items.${field.index}.price`)" />

<!-- Scoped methods (cleaner, type-safe) -->
<input v-bind="field.register('name')" />
<input v-bind="field.register('price')" />
```

--------------------------------

### Logging Form State with watchEffect

Source: https://github.com/vuehookform/core/blob/main/docs/guide/troubleshooting.md

Provides a TypeScript example using `watchEffect` to log changes in form state, including errors, dirty status, and validity, which is useful for debugging.

```typescript
import { watchEffect } from 'vue'

watchEffect(() => {
  console.log('Form state:', {
    errors: formState.value.errors,
    isDirty: formState.value.isDirty,
    isValid: formState.value.isValid,
  })
})
```

--------------------------------

### Validation Mode Configuration

Source: https://github.com/vuehookform/core/blob/main/docs/guide/dynamic/field-arrays.md

Examples showing how different validation modes affect field array operations. Operations trigger validation based on the form's configured mode.

```typescript
// Mode: onSubmit - operations don't trigger validation
const { fields } = useForm({ schema, mode: 'onSubmit' });

// Mode: onChange - operations trigger validation
const { fields } = useForm({ schema, mode: 'onChange' });
```

--------------------------------

### Vue Hook Form Core Commands

Source: https://github.com/vuehookform/core/blob/main/CLAUDE.md

Common npm commands for building, type-checking, linting, formatting, serving documentation, and running tests for the Vue Hook Form library.

```bash
npm run build
npm run type-check
npm run lint
npm run format
npm run docs
npm test
npm run test:run
```