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

fieldapi.md

526 lines9.8 KB

1---
2id: FieldApi
3title: FieldApi
4---
5​
6# Class: FieldApi\<TParentData, TName, TFieldValidator, TFormValidator, TData\>
7​
8A class representing the API for managing a form field.
9​
10Normally, you will not need to create a new `FieldApi` instance directly.
11Instead, you will use a framework hook/function like `useField` or `createField`
12to create a new instance for you that uses your framework's reactivity model.
13However, if you need to create a new instance manually, you can do so by calling
14the `new FieldApi` constructor.
15​
16## Type Parameters
17​
18• **TParentData**
19​
20• **TName** *extends* [`DeepKeys`](../type-aliases/deepkeys.md)\<`TParentData`\>
21​
22• **TFieldValidator** *extends* `Validator`\<[`DeepValue`](../type-aliases/deepvalue.md)\<`TParentData`, `TName`\>, `unknown`\> \| `undefined` = `undefined`
23​
24• **TFormValidator** *extends* `Validator`\<`TParentData`, `unknown`\> \| `undefined` = `undefined`
25​
26• **TData** *extends* [`DeepValue`](../type-aliases/deepvalue.md)\<`TParentData`, `TName`\> = [`DeepValue`](../type-aliases/deepvalue.md)\<`TParentData`, `TName`\>
27​
28## Constructors
29​
30### new FieldApi()
31​
32```ts
33new FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>(opts): FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>
34```
35​
36Initializes a new `FieldApi` instance.
37​
38#### Parameters
39​
40• **opts**: [`FieldApiOptions`](../interfaces/fieldapioptions.md)\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\>
41​
42#### Returns
43​
44[`FieldApi`](fieldapi.md)\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\>
45​
46#### Defined in
47​
48[packages/form-core/src/FieldApi.ts:440](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L440)
49​
50## Properties
51​
52### form
53​
54```ts
55form: FormApi<TParentData, TFormValidator>;
56```
57​
58A reference to the form API instance.
59​
60#### Defined in
61​
62[packages/form-core/src/FieldApi.ts:402](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L402)
63​
64***
65​
66### name
67​
68```ts
69name: unknown extends TParentData ? string : TParentData extends readonly any[] & IsTuple<TParentData> ? PrefixTupleAccessor<TParentData<TParentData>, AllowedIndexes<TParentData<TParentData>, never>, []> : TParentData extends any[] ? PrefixArrayAccessor<TParentData<TParentData>, [any]> : TParentData extends Date ? never : TParentData extends object ? PrefixObjectAccessor<TParentData<TParentData>, []> : TParentData extends string | number | bigint | boolean ? "" : never;
70```
71​
72The field name.
73​
74#### Defined in
75​
76[packages/form-core/src/FieldApi.ts:412](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L412)
77​
78***
79​
80### options
81​
82```ts
83options: FieldApiOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>;
84```
85​
86The field options.
87​
88#### Defined in
89​
90[packages/form-core/src/FieldApi.ts:416](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L416)
91​
92***
93​
94### state
95​
96```ts
97state: FieldState<TData>;
98```
99​
100The current field state.
101​
102#### Defined in
103​
104[packages/form-core/src/FieldApi.ts:430](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L430)
105​
106***
107​
108### store
109​
110```ts
111store: Store<FieldState<TData>, (cb) => FieldState<TData>>;
112```
113​
114The field state store.
115​
116#### Defined in
117​
118[packages/form-core/src/FieldApi.ts:426](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L426)
119​
120***
121​
122### timeoutIds
123​
124```ts
125timeoutIds: Record<ValidationCause, null | Timeout>;
126```
127​
128#### Defined in
129​
130[packages/form-core/src/FieldApi.ts:435](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L435)
131​
132## Methods
133​
134### getInfo()
135​
136```ts
137getInfo(): FieldInfo<TParentData, TFormValidator>
138```
139​
140Gets the field information object.
141​
142#### Returns
143​
144[`FieldInfo`](../type-aliases/fieldinfo.md)\<`TParentData`, `TFormValidator`\>
145​
146#### Defined in
147​
148[packages/form-core/src/FieldApi.ts:658](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L658)
149​
150***
151​
152### getMeta()
153​
154```ts
155getMeta(): FieldMeta
156```
157​
158Gets the current field metadata.
159​
160#### Returns
161​
162[`FieldMeta`](../type-aliases/fieldmeta.md)
163​
164#### Defined in
165​
166[packages/form-core/src/FieldApi.ts:636](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L636)
167​
168***
169​
170### ~~getValue()~~
171​
172```ts
173getValue(): TData
174```
175​
176Gets the current field value.
177​
178#### Returns
179​
180`TData`
181​
182#### Deprecated
183​
184Use `field.state.value` instead.
185​
186#### Defined in
187​
188[packages/form-core/src/FieldApi.ts:616](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L616)
189​
190***
191​
192### handleBlur()
193​
194```ts
195handleBlur(): void
196```
197​
198Handles the blur event.
199​
200#### Returns
201​
202`void`
203​
204#### Defined in
205​
206[packages/form-core/src/FieldApi.ts:1021](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1021)
207​
208***
209​
210### handleChange()
211​
212```ts
213handleChange(updater): void
214```
215​
216Handles the change event.
217​
218#### Parameters
219​
220• **updater**: [`Updater`](../type-aliases/updater.md)\<`TData`\>
221​
222#### Returns
223​
224`void`
225​
226#### Defined in
227​
228[packages/form-core/src/FieldApi.ts:1014](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1014)
229​
230***
231​
232### insertValue()
233​
234```ts
235insertValue(
236 index,
237 value,
238opts?): Promise<void>
239```
240​
241Inserts a value at the specified index, shifting the subsequent values to the right.
242​
243#### Parameters
244​
245• **index**: `number`
246​
247• **value**: `TData` *extends* `any`[] ? `TData`\<`TData`\>\[`number`\] : `never`
248​
249• **opts?**: `UpdateMetaOptions`
250​
251#### Returns
252​
253`Promise`\<`void`\>
254​
255#### Defined in
256​
257[packages/form-core/src/FieldApi.ts:671](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L671)
258​
259***
260​
261### mount()
262​
263```ts
264mount(): () => void
265```
266​
267Mounts the field instance to the form.
268​
269#### Returns
270​
271`Function`
272​
273##### Returns
274​
275`void`
276​
277#### Defined in
278​
279[packages/form-core/src/FieldApi.ts:531](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L531)
280​
281***
282​
283### moveValue()
284​
285```ts
286moveValue(
287 aIndex,
288 bIndex,
289 opts?): void
290```
291​
292Moves the value at the first specified index to the second specified index.
293​
294#### Parameters
295​
296• **aIndex**: `number`
297​
298• **bIndex**: `number`
299​
300• **opts?**: `UpdateMetaOptions`
301​
302#### Returns
303​
304`void`
305​
306#### Defined in
307​
308[packages/form-core/src/FieldApi.ts:701](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L701)
309​
310***
311​
312### pushValue()
313​
314```ts
315pushValue(value, opts?): void
316```
317​
318Pushes a new value to the field.
319​
320#### Parameters
321​
322• **value**: `TData` *extends* `any`[] ? `TData`\<`TData`\>\[`number`\] : `never`
323​
324• **opts?**: `UpdateMetaOptions`
325​
326#### Returns
327​
328`void`
329​
330#### Defined in
331​
332[packages/form-core/src/FieldApi.ts:663](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L663)
333​
334***
335​
336### removeValue()
337​
338```ts
339removeValue(index, opts?): Promise<void>
340```
341​
342Removes a value at the specified index.
343​
344#### Parameters
345​
346• **index**: `number`
347​
348• **opts?**: `UpdateMetaOptions`
349​
350#### Returns
351​
352`Promise`\<`void`\>
353​
354#### Defined in
355​
356[packages/form-core/src/FieldApi.ts:689](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L689)
357​
358***
359​
360### replaceValue()
361​
362```ts
363replaceValue(
364 index,
365 value,
366opts?): Promise<void>
367```
368​
369Replaces a value at the specified index.
370​
371#### Parameters
372​
373• **index**: `number`
374​
375• **value**: `TData` *extends* `any`[] ? `TData`\<`TData`\>\[`number`\] : `never`
376​
377• **opts?**: `UpdateMetaOptions`
378​
379#### Returns
380​
381`Promise`\<`void`\>
382​
383#### Defined in
384​
385[packages/form-core/src/FieldApi.ts:680](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L680)
386​
387***
388​
389### setErrorMap()
390​
391```ts
392setErrorMap(errorMap): void
393```
394​
395Updates the field's errorMap
396​
397#### Parameters
398​
399• **errorMap**: `ValidationErrorMap`
400​
401#### Returns
402​
403`void`
404​
405#### Defined in
406​
407[packages/form-core/src/FieldApi.ts:1036](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1036)
408​
409***
410​
411### setMeta()
412​
413```ts
414setMeta(updater): void
415```
416​
417Sets the field metadata.
418​
419#### Parameters
420​
421• **updater**: [`Updater`](../type-aliases/updater.md)\<[`FieldMeta`](../type-aliases/fieldmeta.md)\>
422​
423#### Returns
424​
425`void`
426​
427#### Defined in
428​
429[packages/form-core/src/FieldApi.ts:652](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L652)
430​
431***
432​
433### setValue()
434​
435```ts
436setValue(updater, options?): void
437```
438​
439Sets the field value and run the `change` validator.
440​
441#### Parameters
442​
443• **updater**: [`Updater`](../type-aliases/updater.md)\<`TData`\>
444​
445• **options?**: `UpdateMetaOptions`
446​
447#### Returns
448​
449`void`
450​
451#### Defined in
452​
453[packages/form-core/src/FieldApi.ts:623](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L623)
454​
455***
456​
457### swapValues()
458​
459```ts
460swapValues(
461 aIndex,
462 bIndex,
463 opts?): void
464```
465​
466Swaps the values at the specified indices.
467​
468#### Parameters
469​
470• **aIndex**: `number`
471​
472• **bIndex**: `number`
473​
474• **opts?**: `UpdateMetaOptions`
475​
476#### Returns
477​
478`void`
479​
480#### Defined in
481​
482[packages/form-core/src/FieldApi.ts:695](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L695)
483​
484***
485​
486### update()
487​
488```ts
489update(opts): void
490```
491​
492Updates the field instance with new options.
493​
494#### Parameters
495​
496• **opts**: [`FieldApiOptions`](../interfaces/fieldapioptions.md)\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\>
497​
498#### Returns
499​
500`void`
501​
502#### Defined in
503​
504[packages/form-core/src/FieldApi.ts:579](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L579)
505​
506***
507​
508### validate()
509​
510```ts
511validate(cause): ValidationError[] | Promise<ValidationError[]>
512```
513​
514Validates the field value.
515​
516#### Parameters
517​
518• **cause**: `ValidationCause`
519​
520#### Returns
521​
522[`ValidationError`](../type-aliases/validationerror.md)[] \| `Promise`\<[`ValidationError`](../type-aliases/validationerror.md)[]\>
523​
524#### Defined in
525​
526[packages/form-core/src/FieldApi.ts:975](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L975)