agentleFS
skilld-devskilld-dev/vue-ecosystem-skills/skills/tanstack-vue-form-skilld/SKILL.md

tanstack-vue-form-skilld

Skill184 starsChanged 37 days agoMITView on GitHub

Use when writing, reviewing, or debugging code that imports @tanstack/vue-form (TanStack Form for Vue). Covers the 1.33.x API, including useForm, form.Field, form.FormGroup, form.Subscribe, form.useSelector, validators with Standard Schema, onDynamic with revalidateLogic, and array fields with mode="array". Result, forms built on current, non-deprecated Vue APIs with correct reactivity.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Import from the package root only.

    line 15
  2. Very specific:

    Do not write v-model on the slot input.

    line 59
  3. Very specific:

    Do not call the useField hook directly for reactivity.

    line 67

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

@tanstack/vue-form 1.33.5

Headless, type-safe form state for Vue 3. The package re-exports all of @tanstack/form-core and adds Vue components and hooks (src/index.ts:1-5).

Environment

  • Version studied: @tanstack/vue-form@1.33.5, bundling @tanstack/form-core@1.33.5 and @tanstack/vue-store@^0.11.0 (package.json:39-42).
  • Peer dependency: vue ^3.4.0 (package.json:48-50). TypeScript 5.4 through 5.9 are in the test matrix (package.json:54-60).
  • Import from the package root only. The sole subpath export is ./package.json (package.json:21-33). Dual ESM/CJS, sideEffects: false.
  • Official docs: https://tanstack.com/form/latest/docs/framework/vue/overview

Minimal form

<script setup lang="ts">
import { useForm } from '@tanstack/vue-form'

const form = useForm({
  defaultValues: {
    fullName: '',
  },
  onSubmit: async ({ value }) => {
    console.log(value)
  },
})
</script>

<template>
  <form @submit.prevent.stop="form.handleSubmit">
    <form.Field name="fullName">
      <template v-slot="{ field }">
        <input
          :name="field.name"
          :value="field.state.value"
          @blur="field.handleBlur"
          @input="(e) => field.handleChange((e.target as HTMLInputElement).value)"
        />
      </template>
    </form.Field>
    <button type="submit">Submit</button>
  </form>
</template>

Source: official quick start, https://tanstack.com/form/latest/docs/framework/vue/quick-start

Field binding rules

  • Fields are created with the form.Field component. The name prop must be a deep key of defaultValues, for example 'details.email' or `people[${i}].name`.
  • The scoped slot receives { field, state } (src/useField.tsx:543-547). field is a FieldApi, state mirrors field.state.
  • Inputs are controlled: bind :value="field.state.value", push updates through field.handleChange, and wire @blur="field.handleBlur".
  • For number inputs, use (e.target as HTMLInputElement).valueAsNumber.
  • Do not write v-model on the slot input; state flows through handleChange.
  • form.Field merges its props with fallthrough attrs before creating the field (src/useField.tsx:541), so validators and listeners can be passed as props or attrs.

Reactivity

  • In <script setup>, use form.useSelector((state) => state.values.firstName). It returns a Readonly<Ref<T>> (src/useForm.tsx:155-189).
  • form.useStore is deprecated; it is the same function as useSelector. Prefer form.useSelector (src/useForm.tsx:190-227, 336-337).
  • In the template, use <form.Subscribe> with an optional selector prop. Without selector, the slot receives the whole form state (src/useForm.tsx:338-349).
  • Do not call the useField hook directly for reactivity. It is designed for use inside form.Field; use form.useSelector instead (official basic-concepts note, https://tanstack.com/form/latest/docs/framework/vue/guides/basic-concepts).
  • useSelector and useStore are re-exported from @tanstack/vue-store for raw store access (src/index.ts:2).

Details: references/reactivity.md

Validation essentials

  • Pass validators via the validators prop on form.Field, or validators in useForm options. Hooks: onMount, onChange, onBlur, onSubmit, onDynamic, each with an Async variant.
  • A validator returns undefined when valid, or an error of any type (usually a string). Errors land in field.state.meta.errors and field.state.meta.errorMap.
  • Standard Schema libraries work directly as validators: Zod v3.24.0 or higher, Valibot v1.0.0 or higher, ArkType v2.1.20 or higher, Yup v1.7.0 or higher (official basic-concepts guide).
  • Debounce async validators with the async-debounce-ms prop or per-validator onChangeAsyncDebounceMs.
  • onDynamic validators only run when validationLogic: revalidateLogic() is set in useForm options.
<form.Field
  name="age"
  :validators="{
    onChange: z.number().gte(13, 'You must be 13 to make an account'),
  }"
>

Details: references/validation.md

Array fields

  • Give the wrapping field mode="array". In array mode the component tracks state.meta._arrayVersion instead of the value, so child edits do not re-render the whole list (src/useField.tsx:258-267, src/types.ts:12-15).
  • Render sub-fields with v-for over field.state.value and deep names such as `people[${i}].name`.
  • Mutate through the array methods: pushValue, removeValue, swapValues, moveValue, insertValue, replaceValue, clearValues.

Details: references/array-fields.md

Form groups

  • <form.FormGroup name="step1" v-slot="{ group }"> builds a sub-form for one key of the form data. The slot receives { group, state } (src/useFormGroup.tsx:525-529).
  • group.handleSubmit() submits and validates only the group; form.handleSubmit() submits the whole form.
  • Group validators can return { group, fields }, where fields keys are relative to the group, and Standard Schemas can be composed per step.

Details: references/form-groups.md

Version-specific rules

  • BREAKING since v1.28.0: field.state.meta.errors is flattened by default, so ['err'] not [['err']]. Restore the old nesting per field with disableErrorFlat: true in field options. Release: https://github.com/TanStack/form/releases/tag/%40tanstack%2Fvue-form%401.28.0
  • DEPRECATED: form.useStore, use form.useSelector (src/useForm.tsx:190-192, 336-337).
  • DEPRECATED: field.getValue(), read field.state.value instead (official FieldApi reference, https://tanstack.com/form/latest/docs/reference/classes/FieldApi).
  • Field accepts mode: 'value' | 'array'. Array mode exists to avoid list re-renders; see https://github.com/TanStack/form/issues/1925 (src/useField.tsx:258-259).
  • useForm generates an SSR-safe form id from Vue's useId when available, falling back to a uuid, so server markup and client hydration agree (src/useForm.tsx:272, src/useFormId.ts:18-24). useFormId itself is internal and not exported (dist/esm/index.js).
  • Reusable option sets: formOptions({ defaultValues }) from form-core, spread into useForm.

Pitfalls

  • Standard Schema transforms are not preserved. onSubmit always receives the input data; call schema.parse(value) inside onSubmit for transformed output (official submission guide, https://tanstack.com/form/latest/docs/framework/vue/guides/submission-handling).
  • A form-level validator error on a field can be overwritten by that field's own validator; field validation runs after form-level field errors are set (official validation guide).
  • Sync validators run first; the matching Async validator is skipped when sync fails, unless asyncAlways: true.
  • canSubmit is true until the form is touched. Combine !canSubmit || isPristine to gate a submit button before any interaction. Prefer aria-disabled over disabled for accessibility (official validation guide).
  • The Field and FormGroup components pass the parent form automatically. Only the standalone Field and FormGroup exports require an explicit form option.
  • Async default values: wrap them in reactive and computed refs (TanStack Query pattern, https://tanstack.com/form/latest/docs/framework/vue/guides/async-initial-values).

References

  • references/api-surface.md: exports, hooks, components, and core class methods with source citations.
  • references/reactivity.md: selectors, Subscribe, listeners, and reactive meta tracking.
  • references/validation.md: validators, schemas, dynamic validation, linked fields, and submission handling.
  • references/array-fields.md: array fields and array mutation methods.
  • references/form-groups.md: sub-forms, group validation, and group state.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.