Open History to see the last commit
1---
2id: ui-libraries
3title: UI Libraries
4---
5β
6TanStack Form is headless. UI library integration consists of adapting a
7field's value, blur callback, change callback, invalid state, and errors to the
8component's inputs and outputs.
9β
10## Text inputs
11β
12Wrap a UI component with `TanStackField` and pass its emitted value to
13`field.api.handleChange`:
14β
15```html
16<ng-container [tanstackField]="form" name="name" #field="field">
17 <ui-text-input
18 [name]="field.api.name"
19 label="Name"
20 [value]="field.api.value"
21 [error]="field.api.errors.map(errorMessage).join(', ')"
22 (blur)="field.api.handleBlur()"
23 (valueChange)="field.api.handleChange($event)"
24 />
25</ng-container>
26```
27β
28```ts
29errorMessage = (error: { message: string }) => error.message
30```
31β
32Pass the current `value`, not a one-time default, so the UI component remains
33driven by form state.
34β
35## Checkboxes and switches
36β
37Adapt the output used by the component library:
38β
39```html
40<ng-container [tanstackField]="form" name="acceptedTerms" #field="field">
41 <ui-checkbox
42 [checked]="field.api.value"
43 [attr.aria-invalid]="field.api.meta.isInvalid"
44 (blur)="field.api.handleBlur()"
45 (checkedChange)="field.api.handleChange($event)"
46 />
47</ng-container>
48```
49β
50Some libraries emit a details object or a union such as
51`boolean | 'indeterminate'`. Normalize it at the boundary:
52β
53```html
54<ui-checkbox
55 [checked]="field.api.value"
56 (checkedChange)="field.api.handleChange($event === true)"
57/>
58```
59β
60## Selects, date pickers, and custom controls
61β
62The integration does not require a native event. Pass the value emitted by the
63component to `field.api.handleChange`:
64β
65```html
66<ui-date-picker
67 [value]="field.api.value"
68 (valueChange)="field.api.handleChange($event)"
69 (blur)="field.api.handleBlur()"
70/>
71```
72β
73Choose a serializable form value appropriate for your application, then adapt
74the UI library's richer object at the component boundary if necessary.
75β
76## Reuse the adapter
77β
78When the same wiring appears throughout the application, create an Angular
79field component that calls `injectField`:
80β
81```ts
82import { ChangeDetectionStrategy, Component, input } from '@angular/core'
83import { injectField } from '@tanstack/angular-form'
84β
85@Component({
86 selector: 'app-text-field',
87 standalone: true,
88 changeDetection: ChangeDetectionStrategy.OnPush,
89 template: `
90 <label>
91 {{ label() }}
92 <input
93 [name]="field.api.name"
94 [value]="field.api.value"
95 (blur)="field.api.handleBlur()"
96 (input)="field.api.handleChange($any($event).target.value)"
97 [attr.aria-invalid]="field.api.meta.isInvalid"
98 />
99 @for (error of field.api.errors; track error) {
100 <span role="alert">{{ error.message }}</span>
101 }
102 </label>
103 `,
104})
105export class TextFieldComponent {
106 label = input.required<string>()
107 field = injectField<string>()
108}
109```
110β
111Apply `tanstack-app-field` alongside the field directive so the component can
112inject its field API:
113β
114```html
115<app-text-field
116 label="Name"
117 tanstack-app-field
118 [tanstackField]="form"
119 name="name"
120/>
121```
122β
123Import `TanStackAppField`, `TanStackField`, and the reusable field component in
124the parent.
125β
126For the helper types used when passing a form or field to an extracted
127component, see [Splitting forms](../../../splitting-forms).
128β
129The repository's `examples/angular/basic-splitting-form` and
130`examples/angular/large-form` examples demonstrate this pattern with typed
131child components.