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

useForm.tsx

244 lines6.6 KB

1import { FormApi, functionalUpdate } from '@tanstack/form-core'
2import { useStore } from '@tanstack/react-store'
3import { useState } from 'react'
4import { Field } from './useField'
5import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect'
6import type {
7 AnyFormApi,
8 AnyFormState,
9 FormAsyncValidateOrFn,
10 FormOptions,
11 FormState,
12 FormValidateOrFn,
13} from '@tanstack/form-core'
14import type { PropsWithChildren, ReactNode } from 'react'
15import type { FieldComponent } from './useField'
16import type { NoInfer } from '@tanstack/react-store'
17​
18/**
19 * Fields that are added onto the `FormAPI` from `@tanstack/form-core` and returned from `useForm`
20 */
21export interface ReactFormApi<
22 in out TFormData,
23 in out TOnMount extends undefined | FormValidateOrFn<TFormData>,
24 in out TOnChange extends undefined | FormValidateOrFn<TFormData>,
25 in out TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
26 in out TOnBlur extends undefined | FormValidateOrFn<TFormData>,
27 in out TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
28 in out TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
29 in out TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
30 in out TOnDynamic extends undefined | FormValidateOrFn<TFormData>,
31 in out TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
32 in out TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
33 in out TSubmitMeta,
34> {
35 /**
36 * A React component to render form fields. With this, you can render and manage individual form fields.
37 */
38 Field: FieldComponent<
39 TFormData,
40 TOnMount,
41 TOnChange,
42 TOnChangeAsync,
43 TOnBlur,
44 TOnBlurAsync,
45 TOnSubmit,
46 TOnSubmitAsync,
47 TOnDynamic,
48 TOnDynamicAsync,
49 TOnServer,
50 TSubmitMeta
51 >
52 /**
53 * A `Subscribe` function that allows you to listen and react to changes in the form's state. It's especially useful when you need to execute side effects or render specific components in response to state updates.
54 */
55 Subscribe: <
56 TSelected = NoInfer<
57 FormState<
58 TFormData,
59 TOnMount,
60 TOnChange,
61 TOnChangeAsync,
62 TOnBlur,
63 TOnBlurAsync,
64 TOnSubmit,
65 TOnSubmitAsync,
66 TOnDynamic,
67 TOnDynamicAsync,
68 TOnServer
69 >
70 >,
71 >(props: {
72 selector?: (
73 state: NoInfer<
74 FormState<
75 TFormData,
76 TOnMount,
77 TOnChange,
78 TOnChangeAsync,
79 TOnBlur,
80 TOnBlurAsync,
81 TOnSubmit,
82 TOnSubmitAsync,
83 TOnDynamic,
84 TOnDynamicAsync,
85 TOnServer
86 >
87 >,
88 ) => TSelected
89 children: ((state: NoInfer<TSelected>) => ReactNode) | ReactNode
90 }) => ReactNode
92​
93/**
94 * An extended version of the `FormApi` class that includes React-specific functionalities from `ReactFormApi`
95 */
96export type ReactFormExtendedApi<
97 TFormData,
98 TOnMount extends undefined | FormValidateOrFn<TFormData>,
99 TOnChange extends undefined | FormValidateOrFn<TFormData>,
100 TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
101 TOnBlur extends undefined | FormValidateOrFn<TFormData>,
102 TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
103 TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
104 TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
105 TOnDynamic extends undefined | FormValidateOrFn<TFormData>,
106 TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
107 TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
108 TSubmitMeta,
109> = FormApi<
110 TFormData,
111 TOnMount,
112 TOnChange,
113 TOnChangeAsync,
114 TOnBlur,
115 TOnBlurAsync,
116 TOnSubmit,
117 TOnSubmitAsync,
118 TOnDynamic,
119 TOnDynamicAsync,
120 TOnServer,
121 TSubmitMeta
122> &
123 ReactFormApi<
124 TFormData,
125 TOnMount,
126 TOnChange,
127 TOnChangeAsync,
128 TOnBlur,
129 TOnBlurAsync,
130 TOnSubmit,
131 TOnSubmitAsync,
132 TOnDynamic,
133 TOnDynamicAsync,
134 TOnServer,
135 TSubmitMeta
136 >
137​
138function LocalSubscribe({
139 form,
140 selector,
141 children,
142}: PropsWithChildren<{
143 form: AnyFormApi
144 selector: (state: AnyFormState) => AnyFormState
145}>) {
146 const data = useStore(form.store, selector)
147​
148 return functionalUpdate(children, data)
150​
151/**
152 * A custom React Hook that returns an extended instance of the `FormApi` class.
153 *
154 * This API encapsulates all the necessary functionalities related to the form. It allows you to manage form state, handle submissions, and interact with form fields
155 */
156export function useForm<
157 TFormData,
158 TOnMount extends undefined | FormValidateOrFn<TFormData>,
159 TOnChange extends undefined | FormValidateOrFn<TFormData>,
160 TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
161 TOnBlur extends undefined | FormValidateOrFn<TFormData>,
162 TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
163 TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
164 TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
165 TOnDynamic extends undefined | FormValidateOrFn<TFormData>,
166 TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
167 TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
168 TSubmitMeta,
169>(
170 opts?: FormOptions<
171 TFormData,
172 TOnMount,
173 TOnChange,
174 TOnChangeAsync,
175 TOnBlur,
176 TOnBlurAsync,
177 TOnSubmit,
178 TOnSubmitAsync,
179 TOnDynamic,
180 TOnDynamicAsync,
181 TOnServer,
182 TSubmitMeta
183 >,
184) {
185 const [formApi] = useState(() => {
186 const api = new FormApi<
187 TFormData,
188 TOnMount,
189 TOnChange,
190 TOnChangeAsync,
191 TOnBlur,
192 TOnBlurAsync,
193 TOnSubmit,
194 TOnSubmitAsync,
195 TOnDynamic,
196 TOnDynamicAsync,
197 TOnServer,
198 TSubmitMeta
199 >(opts)
200​
201 const extendedApi: ReactFormExtendedApi<
202 TFormData,
203 TOnMount,
204 TOnChange,
205 TOnChangeAsync,
206 TOnBlur,
207 TOnBlurAsync,
208 TOnSubmit,
209 TOnSubmitAsync,
210 TOnDynamic,
211 TOnDynamicAsync,
212 TOnServer,
213 TSubmitMeta
214 > = api as never
215​
216 extendedApi.Field = function APIField(props) {
217 return <Field {...props} form={api} />
218 }
219​
220 extendedApi.Subscribe = function Subscribe(props: any) {
221 return (
222 <LocalSubscribe
223 form={api}
224 selector={props.selector}
225 children={props.children}
226 />
227 )
228 }
229​
230 return extendedApi
231 })
232​
233 useIsomorphicLayoutEffect(formApi.mount, [])
234​
235 /**
236 * formApi.update should not have any side effects. Think of it like a `useRef`
237 * that we need to keep updated every render with the most up-to-date information.
238 */
239 useIsomorphicLayoutEffect(() => {
240 formApi.update(opts)
241 })
242​
243 return formApi