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

useForm.tsx

222 lines5.8 KB

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