@vuehookform/core 0.4.2 → 0.4.3

package/README.md

@@ -121,12 +121,52 @@ const { value, ...bindings } = register('field', { controlled: true })
 
 ### Common Mistakes
 
-| Wrong                    | Right                    |
-| ------------------------ | ------------------------ |
-| `items[0].name`          | `items.0.name`           |
-| `:key="index"`           | `:key="field.key"`       |
-| `formState.errors`       | `formState.value.errors` |
-| `v-model` + `register()` | Either one, not both     |
+| Wrong                                | Right                                     | Why                                          |
+| ------------------------------------ | ----------------------------------------- | -------------------------------------------- |
+| `items[0].name`                      | `items.0.name`                            | Always use dot notation for paths            |
+| `:key="index"`                       | `:key="field.key"`                        | Index can change during reordering           |
+| `formState.errors`                   | `formState.value.errors`                  | formState is a Ref, must access `.value`     |
+| `v-model` + `register()`             | Either one, not both                      | Causes double binding conflict               |
+| `const state = getFieldState('x')`   | `formState.value.errors.x`                | getFieldState returns snapshot, not reactive |
+| `<CustomInput v-bind="register()"/>` | Use `controlled: true` or `useController` | Custom components need controlled mode       |
+
+#### ⚠️ Critical: `getFieldState()` is NOT Reactive
+
+**Problem:** Calling `getFieldState()` once returns a snapshot that never updates.
+
+```vue
+<!-- ❌ WRONG - Error will persist even after fixing the input -->
+<script setup>
+const emailState = getFieldState('email')
+</script>
+<template>
+  <span v-if="emailState.error">{{ emailState.error }}</span>
+</template>
+```
+
+**Solutions:**
+
+```vue
+<!-- ✅ Option 1: Use formState (always reactive) -->
+<span v-if="formState.value.errors.email">{{ formState.value.errors.email }}</span>
+
+<!-- ✅ Option 2: Use computed for specific field -->
+<script setup>
+const emailError = computed(() => formState.value.errors.email)
+</script>
+<template>
+  <span v-if="emailError">{{ emailError }}</span>
+</template>
+
+<!-- ✅ Option 3: Use useController for reusable components -->
+<script setup>
+const { fieldState } = useController({ name: 'email', control })
+// fieldState is a ComputedRef that updates automatically
+</script>
+<template>
+  <span v-if="fieldState.error">{{ fieldState.error }}</span>
+</template>
+```
 
 ## Contributing
 

package/dist/core/domSync.d.ts

@@ -1,5 +1,25 @@
 import { Ref } from 'vue';
 import { RegisterOptions } from '../types';
+/**
+ * Extract the actual HTMLInputElement from a ref value.
+ * Handles both native elements and Vue component instances (PrimeVue, Vuetify, etc.)
+ *
+ * Vue component libraries typically expose:
+ * - $el: The root DOM element of the component
+ * - Some components wrap inputs in divs, so we may need to query for the input
+ *
+ * @param refValue - The value from fieldRef.value (HTMLInputElement, Component, or null)
+ * @returns The underlying HTMLInputElement, or null if not found
+ */
+export declare function getInputElement(refValue: unknown): HTMLInputElement | null;
+/**
+ * Get a focusable element from a ref value.
+ * Works with both native elements and Vue component instances.
+ *
+ * @param refValue - The value from fieldRef.value
+ * @returns The focusable HTMLElement, or null if not found
+ */
+export declare function getFocusableElement(refValue: unknown): HTMLElement | null;
 /**
  * Sync values from uncontrolled DOM inputs to form data
  *
@@ -15,13 +35,14 @@ import { RegisterOptions } from '../types';
  * @param fieldOptions - Map of field names to their registration options
  * @param formData - The reactive form data object to update
  */
-export declare function syncUncontrolledInputs(fieldRefs: Map<string, Ref<HTMLInputElement | null>>, fieldOptions: Map<string, RegisterOptions>, formData: Record<string, unknown>): void;
+export declare function syncUncontrolledInputs(fieldRefs: Map<string, Ref<unknown>>, fieldOptions: Map<string, RegisterOptions>, formData: Record<string, unknown>): void;
 /**
  * Update a single DOM element with a new value
  *
  * Handles both checkbox and text inputs appropriately.
+ * Supports both native elements and Vue component instances.
  *
- * @param el - The DOM input element to update
+ * @param refValue - The ref value (HTMLInputElement, Vue component, or null)
  * @param value - The value to set
  */
-export declare function updateDomElement(el: HTMLInputElement, value: unknown): void;
+export declare function updateDomElement(refValue: unknown, value: unknown): void;

package/dist/core/formContext.d.ts

@@ -30,7 +30,7 @@ export interface FieldHandlers {
     /** Handler for input events, triggers validation based on mode */
     onInput: (e: Event) => Promise<void>;
     /** Handler for blur events, marks field as touched and may trigger validation */
-    onBlur: (e: Event) => Promise<void>;
+    onBlur: () => Promise<void>;
     /** Ref callback to capture the DOM element reference */
     refCallback: (el: unknown) => void;
 }

package/dist/types.d.ts

@@ -356,7 +356,7 @@ export interface RegisterReturn<TValue = unknown> {
     /** Input handler (fires on every keystroke) */
     onInput: (e: Event) => void;
     /** Blur handler */
-    onBlur: (e: Event) => void;
+    onBlur: () => void;
     /** Current value (for controlled mode) - only present when controlled: true */
     value?: Ref<TValue>;
     /** Disabled state from form-level disabled option */
@@ -418,6 +418,10 @@ export interface FieldArrayOptions<T = unknown> {
  * - minLength rule would be violated (remove, removeAll, removeMany)
  * - Index is out of bounds (remove, update, swap, move)
  *
+ * **Reactivity:** The `value` property is fully reactive - it automatically
+ * updates when array methods (append, remove, swap, etc.) are called.
+ * Your template will re-render when items change.
+ *
  * @template TItem - The type of items in the array (inferred from field path)
  *
  * @example
@@ -433,7 +437,7 @@ export interface FieldArrayOptions<T = unknown> {
  * }
  */
 export interface FieldArray<TItem = unknown> {
-    /** Current field items with metadata */
+    /** Current field items with metadata. Reactive - updates when array methods are called. */
     value: FieldArrayItem[];
     /** Append item(s) to end of array. Returns false if maxLength exceeded. */
     append: (value: TItem | TItem[], options?: FieldArrayFocusOptions) => boolean;

package/dist/useForm.d.ts

@@ -1,5 +1,11 @@
 import { ZodType } from 'zod';
 import { UseFormOptions, UseFormReturn } from './types';
+/**
+ * Set the internal flag to suppress getFieldState warnings.
+ * Used by useController before calling getFieldState inside computed().
+ * @internal
+ */
+export declare function setCalledFromController(value: boolean): void;
 /**
  * Main form management composable
  *

package/dist/vuehookform.cjs

@@ -222,26 +222,68 @@ function warnArrayIndexOutOfBounds(operation, path, index, length) {
 	if (!__DEV__) return;
 	warn(`${operation}() on "${path}": Index ${index} is out of bounds (array length: ${length}). Operation was silently ignored.`);
 }
-function getDefProp$1(schema, prop) {
-	return schema.def[prop];
-}
-function getTypeName(schema) {
-	return getDefProp$1(schema, "typeName");
+function getSchemaType(schema) {
+	return schema.type;
 }
 function isZodObject$1(schema) {
-	return getTypeName(schema) === "ZodObject";
+	return getSchemaType(schema) === "object";
 }
 function isZodArray$1(schema) {
-	return getTypeName(schema) === "ZodArray";
+	return getSchemaType(schema) === "array";
 }
 function unwrapSchema(schema) {
-	const typeName = getTypeName(schema);
-	const innerType = getDefProp$1(schema, "innerType");
-	const schemaType = getDefProp$1(schema, "schema");
-	if ((typeName === "ZodOptional" || typeName === "ZodNullable" || typeName === "ZodDefault") && innerType) return unwrapSchema(innerType);
-	if (typeName === "ZodEffects" && schemaType) return unwrapSchema(schemaType);
+	const schemaType = getSchemaType(schema);
+	if (schemaType === "optional" || schemaType === "nullable" || schemaType === "default") {
+		const schemaWithUnwrap = schema;
+		if (typeof schemaWithUnwrap.unwrap === "function") return unwrapSchema(schemaWithUnwrap.unwrap());
+	}
 	return schema;
 }
+function getInputElement(refValue) {
+	if (!refValue) return null;
+	if (refValue instanceof HTMLInputElement) return refValue;
+	if (refValue instanceof HTMLSelectElement || refValue instanceof HTMLTextAreaElement) return refValue;
+	if (typeof refValue === "object" && "$el" in refValue) {
+		const el = refValue.$el;
+		if (el instanceof HTMLInputElement) return el;
+		if (el instanceof HTMLSelectElement || el instanceof HTMLTextAreaElement) return el;
+		if (el instanceof Element) {
+			const input = el.querySelector("input, select, textarea");
+			if (input instanceof HTMLInputElement || input instanceof HTMLSelectElement || input instanceof HTMLTextAreaElement) return input;
+		}
+	}
+	return null;
+}
+function getFocusableElement(refValue) {
+	const input = getInputElement(refValue);
+	if (input) return input;
+	if (typeof refValue === "object" && refValue && "$el" in refValue) {
+		const el = refValue.$el;
+		if (el instanceof HTMLElement && typeof el.focus === "function") return el;
+	}
+	if (refValue instanceof HTMLElement && typeof refValue.focus === "function") return refValue;
+	return null;
+}
+function syncUncontrolledInputs(fieldRefs, fieldOptions, formData) {
+	for (const [name, fieldRef] of Array.from(fieldRefs.entries())) {
+		const el = getInputElement(fieldRef.value);
+		if (el) {
+			if (!fieldOptions.get(name)?.controlled) {
+				let value;
+				if (el.type === "checkbox") value = el.checked;
+				else if (el.type === "number" || el.type === "range") value = el.valueAsNumber;
+				else value = el.value;
+				set(formData, name, value);
+			}
+		}
+	}
+}
+function updateDomElement(refValue, value) {
+	const el = getInputElement(refValue);
+	if (!el) return;
+	if (el.type === "checkbox") el.checked = value;
+	else el.value = value;
+}
 function createFormContext(options) {
 	const formData = (0, vue.reactive)({});
 	const defaultValues = (0, vue.reactive)({});
@@ -305,8 +347,8 @@ function createFormContext(options) {
 					const fieldRef = fieldRefs.get(key);
 					const opts = fieldOptions.get(key);
 					if (fieldRef?.value && !opts?.controlled) {
-						const el = fieldRef.value;
-						if (el.type === "checkbox") el.checked = value;
+						const el = getInputElement(fieldRef.value);
+						if (el) if (el.type === "checkbox") el.checked = value;
 						else el.value = value;
 					}
 				}
@@ -566,7 +608,7 @@ function createFieldError(errors, criteriaMode = "firstError") {
 function createValidation(ctx) {
 	function applyNativeValidation(fieldPath, errorMessage) {
 		if (!ctx.options.shouldUseNativeValidation) return;
-		const el = ctx.fieldRefs.get(fieldPath)?.value;
+		const el = getInputElement(ctx.fieldRefs.get(fieldPath)?.value);
 		if (el && "setCustomValidity" in el) el.setCustomValidity(errorMessage || "");
 	}
 	function clearAllNativeValidation() {
@@ -863,7 +905,7 @@ function createFieldRegistration(ctx, validate) {
 					}
 				}
 			};
-			const onBlur = async (_e) => {
+			const onBlur = async () => {
 				markFieldTouched(ctx.touchedFields, name);
 				if (shouldValidateOnBlur(ctx.options.mode ?? "onSubmit", ctx.submitCount.value > 0, ctx.options.reValidateMode)) {
 					await validate(name);
@@ -882,10 +924,11 @@ function createFieldRegistration(ctx, validate) {
 				if (previousEl && el) return;
 				currentFieldRef.value = el;
 				const opts = ctx.fieldOptions.get(name);
-				if (el && !opts?.controlled && el instanceof HTMLInputElement) {
+				const inputEl = getInputElement(el);
+				if (inputEl && !opts?.controlled) {
 					const value = get(ctx.formData, name);
-					if (value !== void 0) if (el.type === "checkbox") el.checked = value;
-					else el.value = value;
+					if (value !== void 0) if (inputEl.type === "checkbox") inputEl.checked = value;
+					else inputEl.value = value;
 				}
 				if (previousEl && !el) {
 					const timer = ctx.debounceTimers.get(name);
@@ -995,20 +1038,6 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 				indexCache.set(item.key, idx);
 			});
 		};
-		const appendToCache = (startIndex) => {
-			const items = fa.items.value;
-			for (let i = startIndex; i < items.length; i++) {
-				const item = items[i];
-				if (item) indexCache.set(item.key, i);
-			}
-		};
-		const updateCacheAfterInsert = (insertIndex, _insertCount) => {
-			const items = fa.items.value;
-			for (let i = insertIndex; i < items.length; i++) {
-				const item = items[i];
-				if (item) indexCache.set(item.key, i);
-			}
-		};
 		const swapInCache = (indexA, indexB) => {
 			const items = fa.items.value;
 			const itemA = items[indexA];
@@ -1087,8 +1116,12 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 			const newValues = [...currentValues, ...values];
 			set(ctx.formData, name, newValues);
 			const newItems = values.map(() => createItem(generateId()));
-			fa.items.value = [...fa.items.value, ...newItems];
-			appendToCache(insertIndex);
+			const newItemsArray = [...fa.items.value, ...newItems];
+			for (let i = insertIndex; i < newItemsArray.length; i++) {
+				const item = newItemsArray[i];
+				if (item) indexCache.set(item.key, i);
+			}
+			fa.items.value = newItemsArray;
 			updateFieldDirtyState(ctx.dirtyFields, ctx.defaultValues, ctx.defaultValueHashes, name, get(ctx.formData, name));
 			validateIfNeeded();
 			handleFocus(insertIndex, values.length, focusOptions);
@@ -1109,9 +1142,12 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 			}
 			const newValues = [...values, ...currentValues];
 			set(ctx.formData, name, newValues);
-			const newItems = values.map(() => createItem(generateId()));
-			fa.items.value = [...newItems, ...fa.items.value];
-			updateCacheAfterInsert(0, values.length);
+			const newItemsArray = [...values.map(() => createItem(generateId())), ...fa.items.value];
+			for (let i = 0; i < newItemsArray.length; i++) {
+				const item = newItemsArray[i];
+				if (item) indexCache.set(item.key, i);
+			}
+			fa.items.value = newItemsArray;
 			updateFieldDirtyState(ctx.dirtyFields, ctx.defaultValues, ctx.defaultValueHashes, name, get(ctx.formData, name));
 			validateIfNeeded();
 			handleFocus(0, values.length, focusOptions);
@@ -1179,12 +1215,16 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 			];
 			set(ctx.formData, name, newValues);
 			const newItems = values.map(() => createItem(generateId()));
-			fa.items.value = [
+			const newItemsArray = [
 				...fa.items.value.slice(0, index),
 				...newItems,
 				...fa.items.value.slice(index)
 			];
-			updateCacheAfterInsert(index, values.length);
+			for (let i = index; i < newItemsArray.length; i++) {
+				const item = newItemsArray[i];
+				if (item) indexCache.set(item.key, i);
+			}
+			fa.items.value = newItemsArray;
 			updateFieldDirtyState(ctx.dirtyFields, ctx.defaultValues, ctx.defaultValueHashes, name, get(ctx.formData, name));
 			validateIfNeeded();
 			handleFocus(index, values.length, focusOptions);
@@ -1299,7 +1339,9 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 			return true;
 		};
 		return {
-			value: fa.items.value,
+			get value() {
+				return fa.items.value;
+			},
 			append,
 			prepend,
 			remove: removeAt,
@@ -1314,28 +1356,14 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 	}
 	return { fields };
 }
-function syncUncontrolledInputs(fieldRefs, fieldOptions, formData) {
-	for (const [name, fieldRef] of Array.from(fieldRefs.entries())) {
-		const el = fieldRef.value;
-		if (el) {
-			if (!fieldOptions.get(name)?.controlled) {
-				let value;
-				if (el.type === "checkbox") value = el.checked;
-				else if (el.type === "number" || el.type === "range") value = el.valueAsNumber;
-				else value = el.value;
-				set(formData, name, value);
-			}
-		}
-	}
-}
-function updateDomElement(el, value) {
-	if (el.type === "checkbox") el.checked = value;
-	else el.value = value;
+var isCalledFromController = false;
+function setCalledFromController(value) {
+	isCalledFromController = value;
 }
 function useForm(options) {
 	const ctx = createFormContext(options);
 	let isSubmissionLocked = false;
-	(0, vue.onUnmounted)(() => {
+	(0, vue.onScopeDispose)(() => {
 		ctx.cleanup();
 	});
 	const { validate, clearAllPendingErrors } = createValidation(ctx);
@@ -1351,11 +1379,10 @@ function useForm(options) {
 		}
 		const fieldRef = ctx.fieldRefs.get(name);
 		if (!fieldRef?.value) return;
-		const el = fieldRef.value;
-		if (typeof el.focus === "function") {
-			el.focus();
-			if (focusOptions?.shouldSelect && el instanceof HTMLInputElement && typeof el.select === "function") el.select();
-		}
+		const el = getFocusableElement(fieldRef.value);
+		if (!el) return;
+		el.focus();
+		if (focusOptions?.shouldSelect && el instanceof HTMLInputElement && typeof el.select === "function") el.select();
 	}
 	const setFocusWrapper = (name) => setFocus(name);
 	const { fields } = createFieldArrayManager(ctx, validate, setFocusWrapper);
@@ -1512,7 +1539,7 @@ function useForm(options) {
 		if (!opts.keepIsSubmitSuccessful) ctx.isSubmitSuccessful.value = false;
 		ctx.fieldArrays.clear();
 		for (const [name, fieldRef] of Array.from(ctx.fieldRefs.entries())) {
-			const el = fieldRef.value;
+			const el = getInputElement(fieldRef.value);
 			if (el) {
 				const value = get(newValues, name);
 				if (value !== void 0) if (el.type === "checkbox") el.checked = value;
@@ -1552,7 +1579,10 @@ function useForm(options) {
 		if (!opts.keepTouched) clearFieldTouched(ctx.touchedFields, name);
 		if (!ctx.fieldOptions.get(name)?.controlled) {
 			const fieldRef = ctx.fieldRefs.get(name);
-			if (fieldRef?.value) updateDomElement(fieldRef.value, clonedValue ?? (fieldRef.value.type === "checkbox" ? false : ""));
+			if (fieldRef?.value) {
+				const el = getInputElement(fieldRef.value);
+				updateDomElement(fieldRef.value, clonedValue ?? (el?.type === "checkbox" ? false : ""));
+			}
 		}
 	}
 	function watch$1(name) {
@@ -1663,6 +1693,7 @@ function useForm(options) {
 				const schemaResult = validatePathAgainstSchema(ctx.options.schema, name);
 				if (!schemaResult.valid) warnPathNotInSchema("getFieldState", name, schemaResult.availableFields);
 			}
+			if ((0, vue.getCurrentInstance)() && !isCalledFromController) console.warn(`[vue-hook-form] getFieldState('${name}') returns a snapshot, not reactive refs.\nFor reactive error display, use one of these alternatives:\n  • formState.value.errors.${name}\n  • const { fieldState } = useController({ name: '${name}', control })\n  • const ${name}Error = computed(() => formState.value.errors.${name})\n\nSee docs: https://github.com/vuehookform/core#common-mistakes`);
 		}
 		const error = get(ctx.errors.value, name);
 		return {
@@ -1778,7 +1809,10 @@ function useController(options) {
 		elementRef.value = el;
 	};
 	const fieldState = (0, vue.computed)(() => {
-		return form.getFieldState(name);
+		setCalledFromController(true);
+		const state = form.getFieldState(name);
+		setCalledFromController(false);
+		return state;
 	});
 	return {
 		field: {

package/dist/vuehookform.js

@@ -1,4 +1,4 @@
-import { computed, inject, nextTick, onUnmounted, provide, reactive, ref, shallowRef, toValue, watch } from "vue";
+import { computed, getCurrentInstance, inject, nextTick, onScopeDispose, provide, reactive, ref, shallowRef, toValue, watch } from "vue";
 var pathCache = /* @__PURE__ */ new Map();
 var PATH_CACHE_MAX_SIZE = 256;
 var MAX_ARRAY_INDEX = 1e4;
@@ -220,26 +220,68 @@ function warnArrayIndexOutOfBounds(operation, path, index, length) {
 	if (!__DEV__) return;
 	warn(`${operation}() on "${path}": Index ${index} is out of bounds (array length: ${length}). Operation was silently ignored.`);
 }
-function getDefProp$1(schema, prop) {
-	return schema.def[prop];
-}
-function getTypeName(schema) {
-	return getDefProp$1(schema, "typeName");
+function getSchemaType(schema) {
+	return schema.type;
 }
 function isZodObject$1(schema) {
-	return getTypeName(schema) === "ZodObject";
+	return getSchemaType(schema) === "object";
 }
 function isZodArray$1(schema) {
-	return getTypeName(schema) === "ZodArray";
+	return getSchemaType(schema) === "array";
 }
 function unwrapSchema(schema) {
-	const typeName = getTypeName(schema);
-	const innerType = getDefProp$1(schema, "innerType");
-	const schemaType = getDefProp$1(schema, "schema");
-	if ((typeName === "ZodOptional" || typeName === "ZodNullable" || typeName === "ZodDefault") && innerType) return unwrapSchema(innerType);
-	if (typeName === "ZodEffects" && schemaType) return unwrapSchema(schemaType);
+	const schemaType = getSchemaType(schema);
+	if (schemaType === "optional" || schemaType === "nullable" || schemaType === "default") {
+		const schemaWithUnwrap = schema;
+		if (typeof schemaWithUnwrap.unwrap === "function") return unwrapSchema(schemaWithUnwrap.unwrap());
+	}
 	return schema;
 }
+function getInputElement(refValue) {
+	if (!refValue) return null;
+	if (refValue instanceof HTMLInputElement) return refValue;
+	if (refValue instanceof HTMLSelectElement || refValue instanceof HTMLTextAreaElement) return refValue;
+	if (typeof refValue === "object" && "$el" in refValue) {
+		const el = refValue.$el;
+		if (el instanceof HTMLInputElement) return el;
+		if (el instanceof HTMLSelectElement || el instanceof HTMLTextAreaElement) return el;
+		if (el instanceof Element) {
+			const input = el.querySelector("input, select, textarea");
+			if (input instanceof HTMLInputElement || input instanceof HTMLSelectElement || input instanceof HTMLTextAreaElement) return input;
+		}
+	}
+	return null;
+}
+function getFocusableElement(refValue) {
+	const input = getInputElement(refValue);
+	if (input) return input;
+	if (typeof refValue === "object" && refValue && "$el" in refValue) {
+		const el = refValue.$el;
+		if (el instanceof HTMLElement && typeof el.focus === "function") return el;
+	}
+	if (refValue instanceof HTMLElement && typeof refValue.focus === "function") return refValue;
+	return null;
+}
+function syncUncontrolledInputs(fieldRefs, fieldOptions, formData) {
+	for (const [name, fieldRef] of Array.from(fieldRefs.entries())) {
+		const el = getInputElement(fieldRef.value);
+		if (el) {
+			if (!fieldOptions.get(name)?.controlled) {
+				let value;
+				if (el.type === "checkbox") value = el.checked;
+				else if (el.type === "number" || el.type === "range") value = el.valueAsNumber;
+				else value = el.value;
+				set(formData, name, value);
+			}
+		}
+	}
+}
+function updateDomElement(refValue, value) {
+	const el = getInputElement(refValue);
+	if (!el) return;
+	if (el.type === "checkbox") el.checked = value;
+	else el.value = value;
+}
 function createFormContext(options) {
 	const formData = reactive({});
 	const defaultValues = reactive({});
@@ -303,8 +345,8 @@ function createFormContext(options) {
 					const fieldRef = fieldRefs.get(key);
 					const opts = fieldOptions.get(key);
 					if (fieldRef?.value && !opts?.controlled) {
-						const el = fieldRef.value;
-						if (el.type === "checkbox") el.checked = value;
+						const el = getInputElement(fieldRef.value);
+						if (el) if (el.type === "checkbox") el.checked = value;
 						else el.value = value;
 					}
 				}
@@ -564,7 +606,7 @@ function createFieldError(errors, criteriaMode = "firstError") {
 function createValidation(ctx) {
 	function applyNativeValidation(fieldPath, errorMessage) {
 		if (!ctx.options.shouldUseNativeValidation) return;
-		const el = ctx.fieldRefs.get(fieldPath)?.value;
+		const el = getInputElement(ctx.fieldRefs.get(fieldPath)?.value);
 		if (el && "setCustomValidity" in el) el.setCustomValidity(errorMessage || "");
 	}
 	function clearAllNativeValidation() {
@@ -861,7 +903,7 @@ function createFieldRegistration(ctx, validate) {
 					}
 				}
 			};
-			const onBlur = async (_e) => {
+			const onBlur = async () => {
 				markFieldTouched(ctx.touchedFields, name);
 				if (shouldValidateOnBlur(ctx.options.mode ?? "onSubmit", ctx.submitCount.value > 0, ctx.options.reValidateMode)) {
 					await validate(name);
@@ -880,10 +922,11 @@ function createFieldRegistration(ctx, validate) {
 				if (previousEl && el) return;
 				currentFieldRef.value = el;
 				const opts = ctx.fieldOptions.get(name);
-				if (el && !opts?.controlled && el instanceof HTMLInputElement) {
+				const inputEl = getInputElement(el);
+				if (inputEl && !opts?.controlled) {
 					const value = get(ctx.formData, name);
-					if (value !== void 0) if (el.type === "checkbox") el.checked = value;
-					else el.value = value;
+					if (value !== void 0) if (inputEl.type === "checkbox") inputEl.checked = value;
+					else inputEl.value = value;
 				}
 				if (previousEl && !el) {
 					const timer = ctx.debounceTimers.get(name);
@@ -993,20 +1036,6 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 				indexCache.set(item.key, idx);
 			});
 		};
-		const appendToCache = (startIndex) => {
-			const items = fa.items.value;
-			for (let i = startIndex; i < items.length; i++) {
-				const item = items[i];
-				if (item) indexCache.set(item.key, i);
-			}
-		};
-		const updateCacheAfterInsert = (insertIndex, _insertCount) => {
-			const items = fa.items.value;
-			for (let i = insertIndex; i < items.length; i++) {
-				const item = items[i];
-				if (item) indexCache.set(item.key, i);
-			}
-		};
 		const swapInCache = (indexA, indexB) => {
 			const items = fa.items.value;
 			const itemA = items[indexA];
@@ -1085,8 +1114,12 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 			const newValues = [...currentValues, ...values];
 			set(ctx.formData, name, newValues);
 			const newItems = values.map(() => createItem(generateId()));
-			fa.items.value = [...fa.items.value, ...newItems];
-			appendToCache(insertIndex);
+			const newItemsArray = [...fa.items.value, ...newItems];
+			for (let i = insertIndex; i < newItemsArray.length; i++) {
+				const item = newItemsArray[i];
+				if (item) indexCache.set(item.key, i);
+			}
+			fa.items.value = newItemsArray;
 			updateFieldDirtyState(ctx.dirtyFields, ctx.defaultValues, ctx.defaultValueHashes, name, get(ctx.formData, name));
 			validateIfNeeded();
 			handleFocus(insertIndex, values.length, focusOptions);
@@ -1107,9 +1140,12 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 			}
 			const newValues = [...values, ...currentValues];
 			set(ctx.formData, name, newValues);
-			const newItems = values.map(() => createItem(generateId()));
-			fa.items.value = [...newItems, ...fa.items.value];
-			updateCacheAfterInsert(0, values.length);
+			const newItemsArray = [...values.map(() => createItem(generateId())), ...fa.items.value];
+			for (let i = 0; i < newItemsArray.length; i++) {
+				const item = newItemsArray[i];
+				if (item) indexCache.set(item.key, i);
+			}
+			fa.items.value = newItemsArray;
 			updateFieldDirtyState(ctx.dirtyFields, ctx.defaultValues, ctx.defaultValueHashes, name, get(ctx.formData, name));
 			validateIfNeeded();
 			handleFocus(0, values.length, focusOptions);
@@ -1177,12 +1213,16 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 			];
 			set(ctx.formData, name, newValues);
 			const newItems = values.map(() => createItem(generateId()));
-			fa.items.value = [
+			const newItemsArray = [
 				...fa.items.value.slice(0, index),
 				...newItems,
 				...fa.items.value.slice(index)
 			];
-			updateCacheAfterInsert(index, values.length);
+			for (let i = index; i < newItemsArray.length; i++) {
+				const item = newItemsArray[i];
+				if (item) indexCache.set(item.key, i);
+			}
+			fa.items.value = newItemsArray;
 			updateFieldDirtyState(ctx.dirtyFields, ctx.defaultValues, ctx.defaultValueHashes, name, get(ctx.formData, name));
 			validateIfNeeded();
 			handleFocus(index, values.length, focusOptions);
@@ -1297,7 +1337,9 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 			return true;
 		};
 		return {
-			value: fa.items.value,
+			get value() {
+				return fa.items.value;
+			},
 			append,
 			prepend,
 			remove: removeAt,
@@ -1312,28 +1354,14 @@ function createFieldArrayManager(ctx, validate, setFocus) {
 	}
 	return { fields };
 }
-function syncUncontrolledInputs(fieldRefs, fieldOptions, formData) {
-	for (const [name, fieldRef] of Array.from(fieldRefs.entries())) {
-		const el = fieldRef.value;
-		if (el) {
-			if (!fieldOptions.get(name)?.controlled) {
-				let value;
-				if (el.type === "checkbox") value = el.checked;
-				else if (el.type === "number" || el.type === "range") value = el.valueAsNumber;
-				else value = el.value;
-				set(formData, name, value);
-			}
-		}
-	}
-}
-function updateDomElement(el, value) {
-	if (el.type === "checkbox") el.checked = value;
-	else el.value = value;
+var isCalledFromController = false;
+function setCalledFromController(value) {
+	isCalledFromController = value;
 }
 function useForm(options) {
 	const ctx = createFormContext(options);
 	let isSubmissionLocked = false;
-	onUnmounted(() => {
+	onScopeDispose(() => {
 		ctx.cleanup();
 	});
 	const { validate, clearAllPendingErrors } = createValidation(ctx);
@@ -1349,11 +1377,10 @@ function useForm(options) {
 		}
 		const fieldRef = ctx.fieldRefs.get(name);
 		if (!fieldRef?.value) return;
-		const el = fieldRef.value;
-		if (typeof el.focus === "function") {
-			el.focus();
-			if (focusOptions?.shouldSelect && el instanceof HTMLInputElement && typeof el.select === "function") el.select();
-		}
+		const el = getFocusableElement(fieldRef.value);
+		if (!el) return;
+		el.focus();
+		if (focusOptions?.shouldSelect && el instanceof HTMLInputElement && typeof el.select === "function") el.select();
 	}
 	const setFocusWrapper = (name) => setFocus(name);
 	const { fields } = createFieldArrayManager(ctx, validate, setFocusWrapper);
@@ -1510,7 +1537,7 @@ function useForm(options) {
 		if (!opts.keepIsSubmitSuccessful) ctx.isSubmitSuccessful.value = false;
 		ctx.fieldArrays.clear();
 		for (const [name, fieldRef] of Array.from(ctx.fieldRefs.entries())) {
-			const el = fieldRef.value;
+			const el = getInputElement(fieldRef.value);
 			if (el) {
 				const value = get(newValues, name);
 				if (value !== void 0) if (el.type === "checkbox") el.checked = value;
@@ -1550,7 +1577,10 @@ function useForm(options) {
 		if (!opts.keepTouched) clearFieldTouched(ctx.touchedFields, name);
 		if (!ctx.fieldOptions.get(name)?.controlled) {
 			const fieldRef = ctx.fieldRefs.get(name);
-			if (fieldRef?.value) updateDomElement(fieldRef.value, clonedValue ?? (fieldRef.value.type === "checkbox" ? false : ""));
+			if (fieldRef?.value) {
+				const el = getInputElement(fieldRef.value);
+				updateDomElement(fieldRef.value, clonedValue ?? (el?.type === "checkbox" ? false : ""));
+			}
 		}
 	}
 	function watch$1(name) {
@@ -1661,6 +1691,7 @@ function useForm(options) {
 				const schemaResult = validatePathAgainstSchema(ctx.options.schema, name);
 				if (!schemaResult.valid) warnPathNotInSchema("getFieldState", name, schemaResult.availableFields);
 			}
+			if (getCurrentInstance() && !isCalledFromController) console.warn(`[vue-hook-form] getFieldState('${name}') returns a snapshot, not reactive refs.\nFor reactive error display, use one of these alternatives:\n  • formState.value.errors.${name}\n  • const { fieldState } = useController({ name: '${name}', control })\n  • const ${name}Error = computed(() => formState.value.errors.${name})\n\nSee docs: https://github.com/vuehookform/core#common-mistakes`);
 		}
 		const error = get(ctx.errors.value, name);
 		return {
@@ -1776,7 +1807,10 @@ function useController(options) {
 		elementRef.value = el;
 	};
 	const fieldState = computed(() => {
-		return form.getFieldState(name);
+		setCalledFromController(true);
+		const state = form.getFieldState(name);
+		setCalledFromController(false);
+		return state;
 	});
 	return {
 		field: {

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@vuehookform/core",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "TypeScript-first form library for Vue 3, inspired by React Hook Form. Form-level state management with Zod validation.",
   "type": "module",
+  "workspaces": [
+    "e2e"
+  ],
   "main": "./dist/vuehookform.cjs",
   "module": "./dist/vuehookform.js",
   "types": "./dist/index.d.ts",
@@ -34,6 +37,9 @@
     "test": "vitest",
     "test:run": "vitest run",
     "test:coverage": "vitest run --coverage",
+    "e2e:dev": "npm run -w e2e dev",
+    "test:e2e": "npm run build:lib && npm run -w e2e test:e2e:ci",
+    "test:e2e:open": "npm run build:lib && npm run -w e2e test:e2e:open",
     "prepare": "husky"
   },
   "repository": {