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

quick-start.md

129 lines3.4 KB

1---
2id: quick-start
3title: Quick Start
4---
5​
6TanStack Form is a headless, type-safe form library. It owns form state and
7validation while leaving markup, styling, and component choice to you.
8​
9Install the Angular adapter:
10​
11```bash
12npm install @tanstack/angular-form
13```
14​
15## Create a form
16​
17`injectForm` requires `defaultValues`. Their shape becomes the form's inferred
18value type. Call it in an Angular injection context, such as a component field
19initializer.
20​
21```ts
22import { ChangeDetectionStrategy, Component } from '@angular/core'
23import {
24 TanStackField,
25 injectForm,
26 injectSelector,
27} from '@tanstack/angular-form'
28​
29@Component({
30 selector: 'app-profile-form',
31 standalone: true,
32 changeDetection: ChangeDetectionStrategy.OnPush,
33 imports: [TanStackField],
34 template: `
35 <form (submit)="handleSubmit($event)">
36 <ng-container
37 [tanstackField]="form"
38 name="fullName"
39 [validators]="fullNameValidators"
40 #fullName="field"
41 >
42 <label>
43 Full name
44 <input
45 [name]="fullName.api.name"
46 [value]="fullName.api.value"
47 (blur)="fullName.api.handleBlur()"
48 (input)="fullName.api.handleChange($any($event).target.value)"
49 [attr.aria-invalid]="fullName.api.meta.isInvalid"
50 />
51 @for (error of fullName.api.errors; track error) {
52 <span role="alert">{{ error.message }}</span>
53 }
54 </label>
55 </ng-container>
56​
57 <ng-container
58 [tanstackField]="form"
59 name="age"
60 [validators]="ageValidators"
61 #age="field"
62 >
63 <label>
64 Age
65 <input
66 type="number"
67 [name]="age.api.name"
68 [value]="age.api.value"
69 (blur)="age.api.handleBlur()"
70 (input)="age.api.handleChange($any($event).target.valueAsNumber)"
71 [attr.aria-invalid]="age.api.meta.isInvalid"
72 />
73 </label>
74 </ng-container>
75​
76 <button type="submit" [disabled]="!canSubmit() || isSubmitting()">
77 {{ isSubmitting() ? 'Saving…' : 'Save' }}
78 </button>
79 </form>
80 `,
81})
82export class ProfileFormComponent {
83 fullNameValidators = [
84 {
85 triggers: ['change', 'blur'] as const,
86 run: ({ value }: { value: string }) =>
87 value.trim() ? undefined : 'Enter your full name',
88 },
89 ]
90​
91 ageValidators = [
92 {
93 triggers: ['change'] as const,
94 run: ({ value }: { value: number }) =>
95 value >= 13 ? undefined : 'You must be at least 13',
96 },
97 ]
98​
99 form = injectForm({
100 defaultValues: {
101 fullName: '',
102 age: 0,
103 },
104 onSubmit: async ({ value }) => {
105 console.log(value)
106 },
107 })
108​
109 canSubmit = injectSelector(this.form, (state) => state.canSubmit)
110 isSubmitting = injectSelector(this.form, (state) => state.isSubmitting)
111​
112 handleSubmit(event: SubmitEvent) {
113 event.preventDefault()
114 void this.form.handleSubmit()
115 }
117```
118​
119The important pieces are:
120​
121- `defaultValues` define the complete initial value and drive type inference.
122- `TanStackField` turns an element or `ng-container` with `[tanstackField]`
123 into a field directive. The exported `field` reference exposes `api.value`,
124 `api.meta`, and event handlers.
125- Validators are ordered objects with a `run` function and explicit
126 `triggers`.
127- `injectSelector` creates an Angular signal for selected form state without
128 making unrelated fields rerender.
129- `form.handleSubmit()` validates the form before calling `onSubmit`.