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

ui-libraries.md

113 lines3.2 KB

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
8custom element or component's property and event names.
9​
10## Text inputs
11​
12For web components, use Lit property bindings for non-string values and event
13bindings for change notifications:
14​
15```ts
16this.form.field(
17 { name: 'name' },
18 (field) => html`
19 <ui-text-input
20 name=${field.name}
21 label="Name"
22 .value=${field.value}
23 @blur=${() => field.handleBlur()}
24 @input=${(event: InputEvent) =>
25 field.handleChange((event.currentTarget as HTMLInputElement).value)}
26 .error=${field.errors.map((error) => error.message).join(', ')}
27 ></ui-text-input>
28 `,
30```
31​
32Bind the current `field.value`; do not pass a one-time default. The form remains
33the source of truth.
34​
35## Checkboxes and switches
36​
37DOM-style checkbox components expose `checked` on the event target:
38​
39```ts
40this.form.field(
41 { name: 'acceptedTerms' },
42 (field) => html`
43 <ui-checkbox
44 .checked=${field.value}
45 @blur=${() => field.handleBlur()}
46 @change=${(event: Event) =>
47 field.handleChange((event.currentTarget as HTMLInputElement).checked)}
48 aria-invalid=${field.meta.isInvalid ? 'true' : 'false'}
49 ></ui-checkbox>
50 `,
52```
53​
54Some libraries emit a boolean, details object, or union such as
55`boolean | 'indeterminate'`. Normalize the custom event at the boundary:
56​
57```ts
58html`<ui-checkbox
59 .checked=${field.value}
60 @checked-change=${(event: CustomEvent<boolean | 'indeterminate'>) =>
61 field.handleChange(event.detail === true)}
62></ui-checkbox>`
63```
64​
65## Selects, date pickers, and custom controls
66​
67The integration does not require a native event. Pass the value emitted by the
68component to `field.handleChange`:
69​
70```ts
71html`<ui-date-picker
72 .value=${field.value}
73 @value-change=${(event: CustomEvent<string>) =>
74 field.handleChange(event.detail)}
75 @blur=${() => field.handleBlur()}
76></ui-date-picker>`
77```
78​
79Choose a serializable form value appropriate for your application, then adapt
80the UI library's richer object at the component boundary if necessary.
81​
82## Reuse the adapter
83​
84If the same wiring appears throughout the application, extract a render
85function or Lit component that accepts `FieldWithValue<T>`:
86​
87```ts
88import type { FieldWithValue } from '@tanstack/lit-form'
89​
90function textField(field: FieldWithValue<string>, label: string) {
91 return html`
92 <label>
93 ${label}
94 <input
95 .value=${field.value}
96 @input=${(event: InputEvent) =>
97 field.handleChange((event.currentTarget as HTMLInputElement).value)}
98 />
99 </label>
100 `
102```
103​
104Use `LitFormType<typeof sharedOptions>` when a split component or render helper
105needs the type of one concrete form. Use
106`getFieldGroupHelpers().withFields(...)` when a reusable bundle should accept
107typed virtual names that callers map to different concrete paths.
108​
109For the helper types used when passing a form or field to an extracted
110component, see [Splitting forms](../../../splitting-forms).
111​
112See the repository's `examples/lit/basic-splitting-form` and
113`examples/lit/field-groups` examples for both patterns.