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

quick-start.md

136 lines4.1 KB

1---
2id: quick-start
3title: Quick Start
4---
5​
6TanStack Form is unlike most form libraries you've used before. It's designed for large-scale production usage, with a focus on type safety, performance and composition for an unmatched developer experience.
7​
8As a result, we've developed [a philosophy around the library's usage](/form/latest/docs/philosophy) that values scalability and long-term developer experience over short and sharable code snippets.
9​
10Here's an example of a form following many of our best practices, which will allow you to rapidly develop even high-complexity forms after a short onboarding experience:
11​
12```tsx
13import React from 'react'
14import ReactDOM from 'react-dom/client'
15import { createFormHook, createFormHookContexts } from '@tanstack/react-form'
16// Form components that pre-bind events from the form hook; check our "Form Composition" guide for more
17import { TextField, NumberField, SubmitButton } from '~our-app/ui-library'
18// We also support Valibot, ArkType, and any other standard schema library
19import { z } from 'zod'
20​
21const { fieldContext, formContext } = createFormHookContexts()
22​
23// Allow us to bind components to the form to keep type safety but reduce production boilerplate
24// Define this once to have a generator of consistent form instances throughout your app
25const { useAppForm } = createFormHook({
26 fieldComponents: {
27 TextField,
28 NumberField,
29 },
30 formComponents: {
31 SubmitButton,
32 },
33 fieldContext,
34 formContext,
35})
36​
37const PeoplePage = () => {
38 const form = useAppForm({
39 defaultValues: {
40 username: '',
41 age: 0,
42 },
43 validators: {
44 // Pass a schema or function to validate
45 onChange: z.object({
46 username: z.string(),
47 age: z.number().min(13),
48 }),
49 },
50 onSubmit: ({ value }) => {
51 // Do something with form data
52 alert(JSON.stringify(value, null, 2))
53 },
54 })
55​
56 return (
57 <form
58 onSubmit={(e) => {
59 e.preventDefault()
60 form.handleSubmit()
61 }}
62 >
63 <h1>Personal Information</h1>
64 {/* Components are bound to `form` and `field` to ensure extreme type safety */}
65 {/* Use `form.AppField` to render a component bound to a single field */}
66 <form.AppField
67 name="username"
68 children={(field) => <field.TextField label="Full Name" />}
69 />
70 {/* The "name" property will throw a TypeScript error if typo'd */}
71 <form.AppField
72 name="age"
73 children={(field) => <field.NumberField label="Age" />}
74 />
75 {/* Components in `form.AppForm` have access to the form context */}
76 <form.AppForm>
77 <form.SubmitButton />
78 </form.AppForm>
79 </form>
80 )
82​
83const rootElement = document.getElementById('root')!
84ReactDOM.createRoot(rootElement).render(<PeoplePage />)
85```
86​
87While we generally suggest using `createFormHook` for reduced boilerplate in the long-run, we also support one-off components and other behaviors using `useForm` and `form.Field`:
88​
89```tsx
90import React from 'react'
91import ReactDOM from 'react-dom/client'
92import { useForm } from '@tanstack/react-form'
93​
94const PeoplePage = () => {
95 const form = useForm({
96 defaultValues: {
97 username: '',
98 age: 0,
99 },
100 onSubmit: ({ value }) => {
101 // Do something with form data
102 alert(JSON.stringify(value, null, 2))
103 },
104 })
105​
106 return (
107 <form.Field
108 name="age"
109 validators={{
110 // We can choose between form-wide and field-specific validators
111 onChange: ({ value }) =>
112 value > 13 ? undefined : 'Must be 13 or older',
113 }}
114 children={(field) => (
115 <>
116 <input
117 name={field.name}
118 value={field.state.value}
119 onBlur={field.handleBlur}
120 type="number"
121 onChange={(e) => field.handleChange(e.target.valueAsNumber)}
122 />
123 {!field.state.meta.isValid && (
124 <em>{field.state.meta.errors.join(',')}</em>
125 )}
126 </>
127 )}
128 />
129 )
131​
132const rootElement = document.getElementById('root')!
133ReactDOM.createRoot(rootElement).render(<PeoplePage />)
134```
135​
136All properties from `useForm` can be used in `useAppForm` and all properties from `form.Field` can be used in `form.AppField`.