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

fieldApi.md

300 lines7.8 KB

1---
2id: fieldApi
3title: Field API
4---
5​
6### Creating a new FieldApi Instance
7​
8Normally, you will not need to create a new `FieldApi` instance directly. Instead, you will use a framework hook/function like `useField` or `createField` to create a new instance for you that utilizes your frameworks reactivity model. However, if you need to create a new instance manually, you can do so by calling the `new FieldApi` constructor.
9​
10```tsx
11const fieldApi: FieldApi<TData> = new FieldApi(formOptions: FieldOptions<TData>)
12```
13​
14### `FieldOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>`
15​
16An object type representing the options for a field in a form.
17​
18- ```tsx
19 name: TName
20 ```
21​
22 - The field name. The type will be `DeepKeys<TParentData>` to ensure your name is a deep key of the parent dataset.
23​
24- ```tsx
25 defaultValue?: TData
26 ```
27​
28 - An optional default value for the field.
29​
30- ```tsx
31 defaultMeta?: Partial<FieldMeta>
32 ```
33​
34 - An optional object with default metadata for the field.
35​
36- ```tsx
37 asyncDebounceMs?: number
38 ```
39​
40 - The default time to debounce async validation if there is not a more specific debounce time passed.
41​
42- ```tsx
43 asyncAlways?: boolean
44 ```
45​
46 - If `true`, always run async validation, even if there are errors emitted during synchronous validation.
47​
48- ```typescript
49 validatorAdapter?: ValidatorType
50 ```
51​
52 - A validator provided by an extension, like `yupValidator` from `@tanstack/yup-form-adapter`
53​
54- ```tsx
55 validators?: FieldValidators<
56 TParentData,
57 TName,
58 TFieldValidator,
59 TFormValidator,
60 TData
61 >
62 ```
63 - A list of validators to pass to the field
64​
65### `FieldValidators<TParentData, TName, TFieldValidator, TFormValidator, TData>`
66​
67- ```tsx
68 onMount?: (formApi: FieldApi<TData, TParentData>) => void
69 ```
70​
71 - An optional function that takes a param of `formApi` which is a generic type of `TData` and `TParentData`
72​
73- ```tsx
74 onChange?: ValidateFn<TData, TParentData>
75 ```
76​
77 - An optional property that takes a `ValidateFn` which is a generic of `TData` and `TParentData`. If `validator` is passed, this may also accept a property from the respective validator (IE: `z.string().min(1)` if `zodAdapter` is passed)
78​
79- ```tsx
80 onChangeAsync?: ValidateAsyncFn<TData, TParentData>
81 ```
82​
83 - An optional property similar to `onChange` but async validation. If `validator` is passed, this may also accept a property from the respective validator (IE: `z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' })` if `zodAdapter` is passed)
84​
85- ```tsx
86 onChangeAsyncDebounceMs?: number
87 ```
88​
89 - An optional number to represent how long the `onChangeAsync` should wait before running
90 - If set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds
91​
92- ```tsx
93 onBlur?: ValidateFn<TData, TParentData>
94 ```
95​
96 - An optional function, when that run when subscribing to blur event of input. If `validator` is passed, this may also accept a property from the respective validator (IE: `z.string().min(1)` if `zodAdapter` is passed)
97​
98- ```tsx
99 onBlurAsync?: ValidateAsyncFn<TData, TParentData>
100 ```
101​
102 - An optional function that takes a `ValidateFn` which is a generic of `TData` and `TParentData` happens async. If `validator` is passed, this may also accept a property from the respective validator (IE: `z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' })` if `zodAdapter` is passed)
103​
104 ```tsx
105 onBlurAsyncDebounceMs?: number
106 ```
107​
108 - An optional number to represent how long the `onBlurAsyncDebounceMs` should wait before running
109 - If set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds
110​
111- ```tsx
112 onSubmit?: ValidateFn<TData, TParentData>
113 ```
114​
115 - An optional function, when that run when subscribing to submit event of input. If `validator` is passed, this may also accept a property from the respective validator (IE: `z.string().min(1)` if `zodAdapter` is passed)
116​
117- ```tsx
118 onSubmitAsync?: ValidateAsyncFn<TData, TParentData>
119 ```
120​
121 - An optional function that takes a `ValidateFn` which is a generic of `TData` and `TParentData` happens async. If `validator` is passed, this may also accept a property from the respective validator (IE: `z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' })` if `zodAdapter` is passed)
122​
123 ```tsx
124 onSubmitAsyncDebounceMs?: number
125 ```
126​
127 - An optional number to represent how long the `onSubmitAsyncDebounceMs` should wait before running
128 - If set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds
129​
130### `FieldMeta`
131​
132An object type representing the metadata of a field in a form.
133​
134- ```tsx
135 isTouched: boolean
136 ```
137 - A flag indicating whether the field has been touched.
138- ```tsx
139 touchedErrors: ValidationError[]
140 ```
141 - An array of errors related to the touched state of the field.
142- ```tsx
143 errors: ValidationError[]
144 ```
145 - An array of errors related related to the field value.
146- ```tsx
147 errorMap: ValidationErrorMap
148 ```
149 - A map of errors related related to the field value.
150- ```tsx
151 isValidating: boolean
152 ```
153 - A flag indicating whether the field is currently being validated.
154​
155### `FieldApiOptions<TData, TParentData>`
156​
157An object type representing the required options for the `FieldApi` class.
158​
159- Inherits from `FieldOptions<TData, TParentData>` with the `form` property set as required.
160​
161### `FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>`
162​
163A class representing the API for managing a form field.
164​
165#### Properties
166​
167- ```tsx
168 uid: number
169 ```
170 - A unique identifier for the field instance.
171- ```tsx
172 form: FormApi<TParentData, TData>
173 ```
174 - A reference to the form API instance.
175- ```tsx
176 name: DeepKeys<TParentData>
177 ```
178 - The field name.
179- ```tsx
180 store: Store<FieldState<TData>>
181 ```
182 - The field state store.
183- ```tsx
184 state: FieldState<TData>
185 ```
186 - The current field state.
187- ```tsx
188 options: RequiredByKey<FieldOptions<TData, TParentData>, 'validateOn'>
189 ```
190 - The field options with the `validateOn` property set as required.
191​
192#### Methods
193​
194- ```tsx
195 constructor(opts: FieldApiOptions<TData, TParentData>)
196 ```
197​
198 - Initializes a new `FieldApi` instance.
199​
200- ```tsx
201 mount(): () => void
202 ```
203​
204 - Mounts the field instance to the form.
205​
206- ```tsx
207 update(opts: FieldApiOptions<TData, TParentData>): void
208 ```
209​
210 - Updates the field instance with new options.
211​
212- ```tsx
213 getValue(): TData
214 ```
215​
216 - Gets the current field value.
217​
218- ```tsx
219 setValue(updater: Updater<TData>, options?: { touch?: boolean; notify?: boolean }): void
220 ```
221​
222 - Sets the field value and run the `change` validator.
223​
224- ```tsx
225 getMeta(): FieldMeta
226 ```
227​
228 - Gets the current field metadata.
229​
230- ```tsx
231 setMeta(updater: Updater<FieldMeta>): void
232 ```
233​
234 - Sets the field metadata.
235​
236- ```tsx
237 getInfo(): any
238 ```
239​
240 - Gets the field information object.
241​
242- ```tsx
243 pushValue(value: TData): void
244 ```
245​
246 - Pushes a new value to the field.
247​
248- ```tsx
249 insertValue(index: number, value: TData): void
250 ```
251​
252 - Inserts a value at the specified index.
253​
254- ```tsx
255 removeValue(index: number): void
256 ```
257​
258 - Removes a value at the specified index.
259​
260- ```tsx
261 swapValues(aIndex: number, bIndex: number): void
262 ```
263​
264 - Swaps the values at the specified indices.
265​
266- ```tsx
267 getSubField<TSubName, TSubData>(name: TName): FieldApi<TData, TSubName, ValidatorType, TSubData>
268 ```
269​
270 - Gets a subfield instance.
271​
272- ```tsx
273 validate(): Promise<any>
274 ```
275​
276 - Validates the field value.
277​
278- ```tsx
279 handleBlur(): void;
280 ```
281​
282 - Handles the blur event.
283​
284- ```tsx
285 handleChange(value: TData): void
286 ```
287 - Handles the change event.
288​
289### `FieldState<TData>`
290​
291An object type representing the state of a field.
292​
293- ```tsx
294 value: TData
295 ```
296 - The current value of the field.
297- ```tsx
298 meta: FieldMeta
299 ```
300 - The current metadata of the field.