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 prop names.
9β
10## Text inputs
11β
12Most controlled text inputs accept DOM-like props directly:
13β
14```tsx
15<form.Field name="name">
16 {(field) => (
17 <TextInput
18 name={field.name}
19 label="Name"
20 value={field.value}
21 onBlur={field.handleBlur}
22 onChange={(event) => field.handleChange(event.target.value)}
23 error={field.errors.map((error) => error.message).join(', ')}
24 />
25 )}
26</form.Field>
27```
28β
29Use `value`, not `defaultValue`, so the UI component remains controlled by form
30state.
31β
32## Checkboxes and switches
33β
34DOM-style checkbox components expose `event.target.checked`:
35β
36```tsx
37<form.Field name="acceptedTerms">
38 {(field) => (
39 <Checkbox
40 checked={field.value}
41 onBlur={field.handleBlur}
42 onChange={(event) => field.handleChange(event.target.checked)}
43 aria-invalid={field.meta.isInvalid}
44 />
45 )}
46</form.Field>
47```
48β
49Some libraries call back with a boolean, a details object, or a union such as
50`boolean | 'indeterminate'`. Normalize that value at the boundary:
51β
52```tsx
53<Checkbox
54 checked={field.value}
55 onCheckedChange={(checked) => field.handleChange(checked === true)}
56/>
57```
58β
59## Selects, date pickers, and custom controls
60β
61The integration does not require a native event. Pass the value produced by the
62component to `field.handleChange`:
63β
64```tsx
65<DatePicker
66 value={field.value}
67 onValueChange={(nextDate) => field.handleChange(nextDate)}
68 onBlur={field.handleBlur}
69/>
70```
71β
72Choose a serializable form value appropriate for your application, then adapt
73the UI library's richer object at the component boundary if necessary.
74β
75## Reuse the adapter
76β
77If the same wiring appears throughout the application, extract a component that
78accepts `FieldWithValue<T>` or register it with `createFormHook`.
79β
80For the helper types used when passing a form or field to an extracted
81component, see [Splitting forms](../../../splitting-forms).
82β
83To reuse several related fields together across different form shapes, see
84[Field groups](./field-groups).
85β
86The repository's `examples/react/ui-integration-shadcn` example demonstrates a
87larger component system with branded fields, lazy-loaded controls, labels,
88descriptions, and accessible error rendering.