Vue Composition API Form Adapters

The problem: Vue’s fine-grained reactivity makes it easy to accidentally trigger validation on every keystroke, run stale async checks after the user has already moved on, or leak a setTimeout handle when a routed component unmounts. If you have debugged a form where error messages flash in the wrong order, submissions race a pending validation, or a watch keeps firing after the component is gone — this page is for you.

This page covers the architecture of a production-ready form adapter composable: how to model the state machine, wire a cancellable validation pipeline, handle submission without data races, and clean up every async handle on teardown. For how this adapter integrates into a larger cross-framework strategy, see Framework Adapters & Custom Hooks.

State Machine Specification

Before writing a single ref, model the states the form can occupy. Every unexpected UI bug traces back to a state that was left undefined.

The state table below maps each state to its Vue primitive and to the transition that triggers it.

Core Implementation

The composable below is production-ready: it handles debouncing, asynchronous validation strategies with AbortController cancellation, duplicate-submission prevention, and full teardown on onUnmounted. Read the inline comments carefully — AbortController misuse is the most common source of stale validation results in Vue forms.

import { ref, reactive, watch, computed, onUnmounted } from 'vue';

// Partial record so callers can return only the fields that failed.
export type ValidationErrors<T> = Partial<Record<keyof T, string | null>>;

export interface FormAdapterConfig<T extends Record<string, unknown>> {
  initialValues: T;
  // validate receives a stable snapshot and an AbortSignal so it can cancel
  // in-flight fetch calls when the user types again before results arrive.
  validate: (values: T, signal: AbortSignal) => Promise<ValidationErrors<T>>;
  onSubmit?: (values: T) => Promise<void>;
}

export function useFormAdapter<T extends Record<string, unknown>>(
  config: FormAdapterConfig<T>
) {
  // reactive() gives Vue deep property-level tracking for the field values.
  const values = reactive<T>({ ...config.initialValues });

  // ref() for scalar flags — Vue optimises shallow refs differently from reactive proxies.
  const errors = ref<ValidationErrors<T>>({});
  const isSubmitting = ref(false);
  const isDirty = ref(false);

  // Timer handle for the debounce window (300 ms default).
  let debounceTimer: ReturnType<typeof setTimeout>;

  // AbortController for the CURRENTLY in-flight validation request.
  // Stored at module scope so the watcher's next invocation can cancel the previous one.
  let validationController: AbortController | null = null;

  // Derived: form is valid when no error slot holds a non-null, non-undefined string.
  const isValid = computed(() =>
    Object.values(errors.value).every(err => err === null || err === undefined)
  );

  // Watch a plain-object spread so Vue diffs individual field values,
  // not the reactive proxy identity.  Without the spread, deep: true is needed
  // and Vue will re-run for mutations to nested objects the form doesn't own.
  watch(
    () => ({ ...values }),
    async (newValues) => {
      isDirty.value = true;
      clearTimeout(debounceTimer);

      // Cancel the previous validation run before starting a new one.
      // This is the key guard against stale error maps overwriting fresh ones.
      validationController?.abort();
      validationController = new AbortController();

      // Capture the controller reference for the closure below.
      // If the outer variable is reassigned before the timeout fires,
      // the closure still holds the right signal.
      const controller = validationController;

      debounceTimer = setTimeout(async () => {
        try {
          const validationErrors = await config.validate(
            newValues as T,
            controller.signal   // passed to fetch/XHR so the request is cancellable
          );

          // Only write results if this run was not superseded by a newer one.
          if (!controller.signal.aborted) {
            errors.value = validationErrors;
          }
        } catch (err) {
          // AbortError is expected when the user types faster than the debounce window.
          if (err instanceof DOMException && err.name === 'AbortError') return;
          console.error('[FormAdapter] Validation pipeline failed:', err);
        }
      }, 300);
    },
    { deep: true }
  );

  async function handleSubmit() {
    // Guard: prevent parallel submissions and block INVALID forms.
    if (!isValid.value || isSubmitting.value) return;

    isSubmitting.value = true;
    try {
      // Run a final synchronous-equivalent validation pass with a fresh signal.
      // This catches the edge case where onSubmit fires before the debounce window closes.
      const finalController = new AbortController();
      const finalErrors = await config.validate(
        { ...values } as T,
        finalController.signal
      );
      errors.value = finalErrors;

      // Re-check validity after the final pass — server may have returned extra constraints.
      if (!isValid.value) return;

      await config.onSubmit?.(values);
      return { success: true };
    } catch (error) {
      console.error('[FormAdapter] Submission failed:', error);
      return { success: false, error };
    } finally {
      // Always release the lock, even if an unhandled error propagates.
      isSubmitting.value = false;
    }
  }

  function reset() {
    Object.assign(values, config.initialValues);
    errors.value = {};
    isDirty.value = false;
  }

  onUnmounted(() => {
    // Prevent the debounce callback from writing to reactive state after the
    // component tree has been torn down — Vue will warn but not throw.
    clearTimeout(debounceTimer);
    // Cancel any pending fetch calls routed through the AbortSignal.
    validationController?.abort();
  });

  return { values, errors, isSubmitting, isValid, isDirty, handleSubmit, reset };
}

Wiring into a template

<script setup lang="ts">
import { useFormAdapter } from '@/composables/useFormAdapter';
import { validateWithZod } from '@/lib/zodAdapter';

const { values, errors, isSubmitting, isValid, handleSubmit } = useFormAdapter({
  initialValues: { email: '', password: '' },
  validate: validateWithZod(loginSchema),
  onSubmit: async (data) => { await api.login(data); },
});
</script>

<template>
  <form @submit.prevent="handleSubmit" novalidate>
    <div>
      <label for="email">Email</label>
      <input
        id="email"
        v-model="values.email"
        type="email"
        :aria-invalid="!!errors.email"
        aria-describedby="email-error"
        data-testid="field-email"
      />
      <span
        id="email-error"
        role="alert"
        aria-live="polite"
      >{{ errors.email }}</span>
    </div>

    <button type="submit" :disabled="!isValid || isSubmitting">
      {{ isSubmitting ? 'Submitting…' : 'Log in' }}
    </button>
  </form>
</template>

aria-invalid and aria-describedby are not cosmetic — screen readers use them to announce which field failed and why. The role="alert" on the error span triggers a live-region announcement without requiring a separate aria-live container on the form root.

Integration Guidance

This adapter sits between your component layer and your validation schema engine. It does not care whether you use Zod, Yup, or Valibot — swap them by changing the validate function signature alone.

For state that must survive route transitions (multi-step wizards, back-navigation after partial completion), the adapter’s values proxy can be extracted into a Pinia store. Syncing Vue Form State with Pinia covers how to lift the reactive object into a store action without losing Vue’s dependency tracking.

Unlike React Form Hook Architecture — where state is held in a useReducer and updates flow through dispatch — Vue’s mutable reactive proxy lets you mutate values.email directly in the watcher callback without creating a new object. The trade-off is that accidental mutations inside child components are harder to trace; keep the values proxy private to the composable and expose only typed setters if your form is large.

Compared to Svelte Store Integration for Forms, Vue’s approach requires explicit watch configuration — Svelte’s reactivity is compile-time and tracks assignments automatically. This means Vue adapters carry more boilerplate but give you more surgical control over what triggers validation.

For forms that also need to signal dirty and pristine state tracking to the parent (e.g., showing a “You have unsaved changes” banner on navigation), expose isDirty from the composable and let the router guard subscribe to it via a shared store or provide/inject.

Edge Cases and Failure Modes

Concurrency: the debounce-vs-async race

If validate performs a network call (checking email uniqueness, for instance) and the user types faster than the network responds, you can receive responses out of order. The AbortController pattern above solves this: each new watch invocation aborts the previous signal before the next setTimeout fires. If your validation library does not accept a signal, wrap the call:

async function cancellableValidate(values: T, signal: AbortSignal): Promise<ValidationErrors<T>> {
  // Poll the signal manually if the underlying library has no abort support.
  const result = await thirdPartyValidate(values);
  if (signal.aborted) throw new DOMException('Aborted', 'AbortError');
  return result;
}

Hydration mismatches in SSR (Nuxt)

When using Nuxt or any Vue SSR setup, reactive() initialised on the server must produce the same shape as on the client or Vue’s hydration will throw. Keep initialValues serialisable (no Date, Map, Set, undefined), and defer async default fetching to onMounted so it only runs client-side.

Shadow DOM and custom element boundaries

If your form fields live inside custom elements (Web Components), Vue’s event listeners cannot cross the shadow boundary unless the component re-emits events on the light DOM. Use composed: true in CustomEvent dispatches and attach your watch to an intermediate signal store rather than directly to v-model.

Autofill and programmatic population

Browser autofill fires the input event asynchronously and in batch — sometimes before Vue has finished mounting. If your adapter’s watch does not fire on autofill, add a one-shot onMounted check:

onMounted(async () => {
  // Detect autofill population that may have arrived before watch was active.
  const autofillController = new AbortController();
  const initial = await config.validate({ ...values } as T, autofillController.signal);
  if (!autofillController.signal.aborted) {
    errors.value = initial;
  }
});

Cross-browser: AbortError name inconsistency

Safari 14 and below throws a plain Error with name: 'AbortError' rather than a DOMException. The guard err instanceof DOMException && err.name === 'AbortError' is already robust here — check only name, not the constructor, if you need to support those versions:

if ((err as Error).name === 'AbortError') return;

Troubleshooting Reference

Testing and QA Hooks

Data-attribute selectors

Every input and error span should carry data-testid attributes so Playwright and Cypress selectors remain stable even when class names or IDs change:

<input data-testid="field-email" ... />
<span  data-testid="error-email" role="alert">{{ errors.email }}</span>
<button data-testid="submit-btn" :disabled="!isValid || isSubmitting">Submit</button>

In Playwright:

await page.getByTestId('field-email').fill('not-an-email');
await expect(page.getByTestId('error-email')).toBeVisible();
await expect(page.getByTestId('submit-btn')).toBeDisabled();

Accessibility regression coverage

ARIA state must be tested, not assumed. In Vitest with @vue/test-utils:

import { mount } from '@vue/test-utils';
import LoginForm from '@/components/LoginForm.vue';

test('marks email input aria-invalid after blur with bad value', async () => {
  const wrapper = mount(LoginForm);
  const input = wrapper.find('[data-testid="field-email"]');
  await input.setValue('bad');
  await input.trigger('input');
  await new Promise(r => setTimeout(r, 350)); // wait past debounce
  expect(input.attributes('aria-invalid')).toBe('true');
});

Run axe-core against the rendered component in each test to catch contrast and role violations introduced by state changes.

Common Pitfalls

• Deep-watching the reactive proxy directly: watch(values, ...) re-runs for every nested mutation including those your composable makes to errors. Always spread: watch(() => ({ ...values }), ...).
• Forgetting to abort on unmount: An in-flight setTimeout callback writes to errors.value after the component is destroyed. Vue will warn; real apps with many route transitions will leak handles silently. Always call clearTimeout and validationController?.abort() in onUnmounted.
• Running final validation with the same (possibly aborted) controller: The handleSubmit function creates its own AbortController for the final pass — never reuse the watcher’s controller, which may already be aborted.
• Mutating values inside the validate callback: Validation is a pure read operation. Mutating values inside validate creates a new watch cycle, which re-triggers validation — an infinite loop disguised as a slow page.
• Using watchEffect instead of watch: watchEffect auto-tracks any reactive reference it reads at call time, including errors itself. This pulls the error-write step into the dependency graph and causes the watcher to re-run every time errors are updated.

Frequently Asked Questions

How do Vue form adapters handle dynamic field arrays without triggering full re-validation?

Isolate array mutations with shallowReactive wrappers and apply targeted validation only to the modified index. Track array length changes in a separate watcher keyed on array.length to avoid cascading the full deep-validation cycle. Each array item can own its own useFormAdapter instance with a scoped initialValues.

Should I use watch or watchEffect for the validation pipeline?

Use watch with an explicit source returning a shallow copy of values. watchEffect auto-tracks every reactive dependency it touches during execution, which can pull in errors, isSubmitting, or other state and make the teardown graph unpredictable when those refs change inside async callbacks.

Can this adapter integrate with third-party UI component libraries such as PrimeVue or Vuetify?

Yes. Expose a normalised onUpdate:modelValue interface and map each library’s change event to the adapter’s internal state via v-model binding on the values object. The adapter acts as a pure translation layer between UI events and your validation schema — no modifications to the component library are required.

How do I surface server-side validation errors back into the adapter’s error map?

Catch the HTTP error in handleSubmit, parse the response body into the same ValidationErrors<T> shape your validate function returns, then assign it directly to errors.value. Because errors is a ref, Vue propagates the update synchronously to any template binding that reads it.

Related

• Syncing Vue Form State with Pinia — persist adapter state across route transitions using a Pinia store
• React Form Hook Architecture — reducer-based form state with unidirectional dispatch
• Svelte Store Integration for Forms — compile-time reactive stores for zero-overhead subscriptions
• Asynchronous Validation Strategies — debounce patterns and AbortController in depth

← Framework Adapters & Custom Hooks