Open History to see the last commit
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 Lit adapter:
10
11```bash
12npm install @tanstack/lit-form
13```
14
15## Create a form
16
17Create a `TanStackFormController` as a field on your Lit element. The controller
18requires complete `defaultValues`; their shape becomes the inferred form value
19type.
20
21```ts
22import { LitElement, html } from 'lit'
23import { TanStackFormController } from '@tanstack/lit-form'
24
25class ProfileForm extends LitElement {
26 private form = new TanStackFormController(this, {
27 defaultValues: {
28 fullName: '',
29 age: 0,
30 },
31 onSubmit: async ({ value }) => {
32 console.log(value)
33 },
34 })
35
36 render() {
37 return html`
38 <form
39 @submit=${(event: SubmitEvent) => {
40 event.preventDefault()
41 void this.form.api.handleSubmit()
42 }}
43 >
44 ${this.form.field(
45 {
46 name: 'fullName',
47 validators: [
48 {
49 triggers: ['change', 'blur'],
50 run: ({ value }) =>
51 value.trim() ? undefined : 'Enter your full name',
52 },
53 ],
54 },
55 (field) => html`
56 <label>
57 Full name
58 <input
59 name=${field.name}
60 .value=${field.value}
61 @blur=${() => field.handleBlur()}
62 @input=${(event: InputEvent) =>
63 field.handleChange(
64 (event.currentTarget as HTMLInputElement).value,
65 )}
66 aria-invalid=${field.meta.isInvalid ? 'true' : 'false'}
67 />
68 ${field.errors.map(
69 (error) => html`<span role="alert">${error.message}</span>`,
70 )}
71 </label>
72 `,
73 )}
74 ${this.form.field(
75 {
76 name: 'age',
77 validators: [
78 {
79 triggers: ['change'],
80 run: ({ value }) =>
81 value >= 13 ? undefined : 'You must be at least 13',
82 },
83 ],
84 },
85 (field) => html`
86 <label>
87 Age
88 <input
89 name=${field.name}
90 type="number"
91 .value=${String(field.value)}
92 @blur=${() => field.handleBlur()}
93 @input=${(event: InputEvent) =>
94 field.handleChange(
95 (event.currentTarget as HTMLInputElement).valueAsNumber,
96 )}
97 aria-invalid=${field.meta.isInvalid ? 'true' : 'false'}
98 />
99 </label>
100 `,
101 )}
102 ${this.form.subscribe(
103 (state) => [state.canSubmit, state.isSubmitting] as const,
104 ([canSubmit, isSubmitting]) => html`
105 <button type="submit" ?disabled=${!canSubmit || isSubmitting}>
106 ${isSubmitting ? 'Saving…' : 'Save'}
107 </button>
108 `,
109 )}
110 </form>
111 `
112 }
113}
114
115customElements.define('profile-form', ProfileForm)
116```
117
118The important pieces are:
119
120- `defaultValues` define the complete initial value and drive type inference.
121- `form.field(...)` subscribes only its Lit child part to one field. Its render
122 callback exposes `field.value`, `field.meta`, and event handlers.
123- Validators are ordered objects with a `run` function and explicit
124 `triggers`.
125- `form.subscribe(...)` updates only its child part when the selected form state
126 changes.
127- The public form API is available through `form.api`; calling
128 `form.api.handleSubmit()` validates before running `onSubmit`.