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

debugging.md

99 lines3.2 KB

1---
2id: debugging
3title: Debugging Angular Usage
4---
5​
6This page covers common Angular and TypeScript problems when using TanStack
7Form.
8​
9## An input initially renders `undefined`
10​
11Every value rendered by an input must exist in form-level `defaultValues` from
12the first render.
13​
14```ts
15form = injectForm({
16 defaultValues: {
17 firstName: '',
18 subscribed: false,
19 },
20})
21```
22​
23Do not omit `defaultValues` or rely on a field-level default. When values come
24from an API, render a loading state before mounting the editable fields or
25supply a complete fallback shape.
26​
27## A field value is `unknown`
28​
29Field names and values are inferred from `defaultValues`. Check that you have
30not widened the initial object to `Record<string, unknown>`, `any`, or an
31unrelated union. Prefer a concrete value type:
32​
33```ts
34type Profile = { firstName: string; age: number }
35​
36const defaults: Profile = { firstName: '', age: 0 }
37form = injectForm({ defaultValues: defaults })
38```
39​
40For extremely large forms, split UI into typed components or scoped form and
41field groups instead of casting each field value.
42​
43## A child component rejects the form input
44​
45Use `formOptions` for reusable base options and derive the input type with
46`AngularFormType`. This keeps the child compatible when the parent adds
47`onSubmit`:
48​
49```ts
50import { Component, input } from '@angular/core'
51import { formOptions } from '@tanstack/angular-form'
52import type { AngularFormType } from '@tanstack/angular-form'
53​
54export const profileFormOptions = formOptions({
55 defaultValues: { firstName: '', age: 0 },
56})
57​
58@Component({
59 selector: 'app-profile-fields',
60 standalone: true,
61 template: `<!-- fields -->`,
62})
63export class ProfileFieldsComponent {
64 form = input.required<AngularFormType<typeof profileFormOptions>>()
66```
67​
68## Async defaults do not update
69​
70`injectForm` receives its initial options when the component is constructed.
71When data arrives later, call `form.reset(nextValues)` deliberately, normally
72inside an Angular `effect`, or resolve the data before constructing the form.
73Guard against replacing edits the user has already made.
74​
75## `injectForm` reports a missing injection context
76​
77Call `injectForm`, `injectSelector`, and `injectField` in an Angular injection
78context, such as a component field initializer or constructor. Do not call
79them later from an event handler, subscription callback, or arbitrary utility
80function.
81​
82## Type instantiation is excessively deep
83​
84This TypeScript error usually involves a very large recursive value shape, a
85widely inferred union, or unsupported composition. Reduce it to the smallest
86form that reproduces the problem, keep `defaultValues` concrete, and avoid
87unnecessary generic wrappers.
88​
89If the minimal reproduction still fails, report it in the
90[TanStack Form issue tracker](https://github.com/TanStack/form/issues). Include
91the Angular and TypeScript versions, the form value type, and the smallest
92failing field.
93​
94## Errors exist but are not displayed
95​
96`field.api.errors` respects the form's `errorVisibility` policy. Inspect
97`field.api.meta.original.errors` when debugging whether validation ran but the
98issues are intentionally hidden. Also confirm that the input calls
99`field.api.handleBlur()` if the policy depends on `isBlurred`.