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

useForm.tsx

99 lines4.1 KB

1import { FormApi, functionalUpdate } from '@tanstack/form-core'
2import { useStore } from '@tanstack/react-store'
3import React, { useState } from 'react'
4import { Field, useField } from './useField'
5import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect'
6import type { FieldComponent, UseField } from './useField'
7import type { NoInfer } from '@tanstack/react-store'
8import type { FormOptions, FormState, Validator } from '@tanstack/form-core'
9import type { NodeType } from './types'
10​
11/**
12 * Fields that are added onto the `FormAPI` from `@tanstack/form-core` and returned from `useForm`
13 */
14export interface ReactFormApi<
15 TFormData,
16 TFormValidator extends Validator<TFormData, unknown> | undefined = undefined,
17> {
18 /**
19 * A React component to render form fields. With this, you can render and manage individual form fields.
20 */
21 Field: FieldComponent<TFormData, TFormValidator>
22 /**
23 * A custom React hook that provides functionalities related to individual form fields. It gives you access to field values, errors, and allows you to set or update field values.
24 */
25 useField: UseField<TFormData, TFormValidator>
26 /**
27 * A `useStore` hook that connects to the internal store of the form. It can be used to access the form's current state or any other related state information. You can optionally pass in a selector function to cherry-pick specific parts of the state
28 */
29 useStore: <TSelected = NoInfer<FormState<TFormData>>>(
30 selector?: (state: NoInfer<FormState<TFormData>>) => TSelected,
31 ) => TSelected
32 /**
33 * 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.
34 */
35 Subscribe: <TSelected = NoInfer<FormState<TFormData>>>(props: {
36 /**
37 TypeScript versions <=5.0.4 have a bug that prevents
38 the type of the `TSelected` generic from being inferred
39 from the return type of this method.
40​
41 In these versions, `TSelected` will fall back to the default
42 type (or `unknown` if that's not defined).
43​
44 @see {@link https://github.com/TanStack/form/pull/606/files#r1506715714 | This discussion on GitHub for the details}
45 @see {@link https://github.com/microsoft/TypeScript/issues/52786 | The bug report in `microsoft/TypeScript`}
46 */
47 selector?: (state: NoInfer<FormState<TFormData>>) => TSelected
48 children: ((state: NoInfer<TSelected>) => NodeType) | NodeType
49 }) => NodeType
51​
52/**
53 * A custom React Hook that returns an extended instance of the `FormApi` class.
54 *
55 * 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
56 */
57export function useForm<
58 TFormData,
59 TFormValidator extends Validator<TFormData, unknown> | undefined = undefined,
60>(opts?: FormOptions<TFormData, TFormValidator>) {
61 const [formApi] = useState(() => {
62 const api = new FormApi<TFormData, TFormValidator>(opts)
63​
64 const extendedApi: typeof api & ReactFormApi<TFormData, TFormValidator> =
65 api as never
66 extendedApi.Field = function APIField(props) {
67 return (<Field {...props} form={api} />) as never
68 }
69 // eslint-disable-next-line react-hooks/rules-of-hooks
70 extendedApi.useField = (props) => useField({ ...props, form: api })
71 extendedApi.useStore = (selector) => {
72 // eslint-disable-next-line react-hooks/rules-of-hooks
73 return useStore(api.store as any, selector as any) as any
74 }
75 extendedApi.Subscribe = (props) => {
76 return functionalUpdate(
77 props.children,
78 // eslint-disable-next-line react-hooks/rules-of-hooks
79 useStore(api.store as any, props.selector as any),
80 ) as any
81 }
82​
83 return extendedApi
84 })
85​
86 useIsomorphicLayoutEffect(formApi.mount, [])
87​
88 formApi.useStore((state) => state.isSubmitting)
89​
90 /**
91 * formApi.update should not have any side effects. Think of it like a `useRef`
92 * that we need to keep updated every render with the most up-to-date information.
93 */
94 useIsomorphicLayoutEffect(() => {
95 formApi.update(opts)
96 })
97​
98 return formApi