Skip to content
Source
Sign inSign up
TanStack/form
Open History to see the last commit

debugging.md

76 lines2.5 KB

1---
2id: debugging
3title: Debugging Vue Usage
4---
5​
6This page covers common Vue and TypeScript problems when using TanStack Form.
7​
8## An input initially renders `undefined`
9​
10Every value rendered by an input must exist in form-level `defaultValues` from
11the first render.
12​
13```vue
14<script setup lang="ts">
15import { useForm } from '@tanstack/vue-form'
16​
17const form = useForm({
18 defaultValues: {
19 firstName: '',
20 subscribed: false,
21 },
22})
23</script>
24```
25​
26Do not omit `defaultValues` or rely on a field-level default. When values come
27from an API, render a loading state before mounting the editable form or supply
28a complete fallback shape.
29​
30## A field value is `unknown`
31​
32Field names and values are inferred from `defaultValues`. Check that you have
33not widened the initial object to `Record<string, unknown>`, `any`, or an
34unrelated union. Prefer a concrete value type:
35​
36```ts
37type Profile = { firstName: string; age: number }
38​
39const defaults: Profile = { firstName: '', age: 0 }
40const form = useForm({ defaultValues: defaults })
41```
42​
43For extremely large forms, split UI into typed components or scoped form and
44field groups instead of casting each field value.
45​
46## Async defaults do not update
47​
48The Vue adapter observes reactive option objects. If data arrives after
49`useForm` runs, update `defaultValues` through a `reactive` options object or
50mount the editor only after the data exists. A plain object containing a
51one-time snapshot is not reactive.
52​
53## Composition types fail under Vue 3.5
54​
55Form v2 requires Vue 3.6 or newer. The adapter's typed field components,
56injection-based `AppForm`, and form composition rely on Vue 3.6 behavior that
57is not available in Vue 3.5.
58​
59## Type instantiation is excessively deep
60​
61This TypeScript error usually involves a very large recursive value shape, a
62widely inferred union, or unsupported composition. Reduce it to the smallest
63form that reproduces the problem, keep `defaultValues` concrete, and avoid
64unnecessary generic wrappers.
65​
66If the minimal reproduction still fails, report it in the
67[TanStack Form issue tracker](https://github.com/TanStack/form/issues). Include
68the Vue and TypeScript versions, the form value type, and the smallest failing
69field.
70​
71## Errors exist but are not displayed
72​
73`field.errors` respects the form's `errorVisibility` policy. Inspect
74`field.meta.original.errors` when debugging whether validation ran but the
75issues are intentionally hidden. Also confirm that the input calls
76`field.handleBlur` if the policy depends on `isBlurred`.