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

overview.md

147 lines5.2 KB

1---
2id: overview
3title: Overview
4---
5​
6TanStack Form is the ultimate solution for handling forms in web applications, providing a powerful and flexible approach to form management. Designed with first-class TypeScript support, headless UI components, and a framework-agnostic design, it streamlines form handling and ensures a seamless experience across various front-end frameworks.
7​
8> **TanStack Form is in release candidate mode, meaning that there should be extremely few or no breaking changes prior to a 1.x release.**
9>
10> To learn more and see [our roadmap to v1, please check our GitHub](https://github.com/TanStack/form/issues/813).
11​
12## Motivation
13​
14Most web frameworks do not offer a comprehensive solution for form handling, leaving developers to create their own custom implementations or rely on less-capable libraries. This often results in a lack of consistency, poor performance, and increased development time. TanStack Form aims to address these challenges by providing an all-in-one solution for managing forms that is both powerful and easy to use.
15​
16With TanStack Form, developers can tackle common form-related challenges such as:
17​
18- Reactive data binding and state management
19- Complex validation and error handling
20- Accessibility and responsive design
21- Internationalization and localization
22- Cross-platform compatibility and custom styling
23​
24By providing a complete solution for these challenges, TanStack Form empowers developers to build robust and user-friendly forms with ease.
25​
26## Enough talk, show me some code already!
27​
28In the example below, you can see TanStack Form in action with the React framework adapter:
29​
30[Open in CodeSandbox](https://codesandbox.io/s/github/tanstack/form/tree/main/examples/react/simple)
31​
32```tsx
33import * as React from 'react'
34import { createRoot } from 'react-dom/client'
35import { useForm } from '@tanstack/react-form'
36import type { AnyFieldApi } from '@tanstack/react-form'
37​
38function FieldInfo({ field }: { field: AnyFieldApi }) {
39 return (
40 <>
41 {field.state.meta.isTouched && field.state.meta.errors.length ? (
42 <em>{field.state.meta.errors.join(", ")}</em>
43 ) : null}
44 {field.state.meta.isValidating ? 'Validating...' : null}
45 </>
46 )
48​
49export default function App() {
50 const form = useForm({
51 defaultValues: {
52 firstName: '',
53 lastName: '',
54 },
55 onSubmit: async ({ value }) => {
56 // Do something with form data
57 console.log(value)
58 },
59 })
60​
61 return (
62 <div>
63 <h1>Simple Form Example</h1>
64 <form
65 onSubmit={(e) => {
66 e.preventDefault()
67 e.stopPropagation()
68 form.handleSubmit()
69 }}
70 >
71 <div>
72 {/* A type-safe field component*/}
73 <form.Field
74 name="firstName"
75 validators={{
76 onChange: ({ value }) =>
77 !value
78 ? 'A first name is required'
79 : value.length < 3
80 ? 'First name must be at least 3 characters'
81 : undefined,
82 onChangeAsyncDebounceMs: 500,
83 onChangeAsync: async ({ value }) => {
84 await new Promise((resolve) => setTimeout(resolve, 1000))
85 return (
86 value.includes('error') &&
87 'No "error" allowed in first name'
88 )
89 },
90 }}
91 children={(field) => {
92 // Avoid hasty abstractions. Render props are great!
93 return (
94 <>
95 <label htmlFor={field.name}>First Name:</label>
96 <input
97 id={field.name}
98 name={field.name}
99 value={field.state.value}
100 onBlur={field.handleBlur}
101 onChange={(e) => field.handleChange(e.target.value)}
102 />
103 <FieldInfo field={field} />
104 </>
105 )
106 }}
107 />
108 </div>
109 <div>
110 <form.Field
111 name="lastName"
112 children={(field) => (
113 <>
114 <label htmlFor={field.name}>Last Name:</label>
115 <input
116 id={field.name}
117 name={field.name}
118 value={field.state.value}
119 onBlur={field.handleBlur}
120 onChange={(e) => field.handleChange(e.target.value)}
121 />
122 <FieldInfo field={field} />
123 </>
124 )}
125 />
126 </div>
127 <form.Subscribe
128 selector={(state) => [state.canSubmit, state.isSubmitting]}
129 children={([canSubmit, isSubmitting]) => (
130 <button type="submit" disabled={!canSubmit}>
131 {isSubmitting ? '...' : 'Submit'}
132 </button>
133 )}
134 />
135 </form>
136 </div>
137 )
139​
140const rootElement = document.getElementById('root')!
141​
142createRoot(rootElement).render(<App />)
143```
144​
145## You talked me into it, so what now?
146​
147- Learn TanStack Form at your own pace with our thorough [Walkthrough Guide](../installation) and [API Reference](../reference/classes/formapi)