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

fieldapi.md

578 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
41​
42[`FieldApiOptions`](../interfaces/fieldapioptions.md)\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\>
43​
44#### Returns
45​
46[`FieldApi`](fieldapi.md)\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\>
47​
48#### Defined in
49​
50[packages/form-core/src/FieldApi.ts:477](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L477)
51​
52## Properties
53​
54### form
55​
56```ts
57form: FormApi<TParentData, TFormValidator>;
58```
59​
60A reference to the form API instance.
61​
62#### Defined in
63​
64[packages/form-core/src/FieldApi.ts:441](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L441)
65​
66***
67​
68### name
69​
70```ts
71name: 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;
72```
73​
74The field name.
75​
76#### Defined in
77​
78[packages/form-core/src/FieldApi.ts:451](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L451)
79​
80***
81​
82### options
83​
84```ts
85options: FieldApiOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>;
86```
87​
88The field options.
89​
90#### Defined in
91​
92[packages/form-core/src/FieldApi.ts:455](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L455)
93​
94***
95​
96### store
97​
98```ts
99store: Derived<FieldState<TData>, readonly any[]>;
100```
101​
102The field state store.
103​
104#### Defined in
105​
106[packages/form-core/src/FieldApi.ts:465](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L465)
107​
108***
109​
110### timeoutIds
111​
112```ts
113timeoutIds: Record<ValidationCause, null | Timeout>;
114```
115​
116#### Defined in
117​
118[packages/form-core/src/FieldApi.ts:472](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L472)
119​
120## Accessors
121​
122### state
123​
124#### Get Signature
125​
126```ts
127get state(): FieldState<TData>
128```
129​
130The current field state.
131​
132##### Returns
133​
134[`FieldState`](../type-aliases/fieldstate.md)\<`TData`\>
135​
136#### Defined in
137​
138[packages/form-core/src/FieldApi.ts:469](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L469)
139​
140## Methods
141​
142### getInfo()
143​
144```ts
145getInfo(): FieldInfo<TParentData, TFormValidator>
146```
147​
148Gets the field information object.
149​
150#### Returns
151​
152[`FieldInfo`](../type-aliases/fieldinfo.md)\<`TParentData`, `TFormValidator`\>
153​
154#### Defined in
155​
156[packages/form-core/src/FieldApi.ts:672](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L672)
157​
158***
159​
160### getMeta()
161​
162```ts
163getMeta(): FieldMeta
164```
165​
166#### Returns
167​
168[`FieldMeta`](../type-aliases/fieldmeta.md)
169​
170#### Defined in
171​
172[packages/form-core/src/FieldApi.ts:661](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L661)
173​
174***
175​
176### ~~getValue()~~
177​
178```ts
179getValue(): TData
180```
181​
182Gets the current field value.
183​
184#### Returns
185​
186`TData`
187​
188#### Deprecated
189​
190Use `field.state.value` instead.
191​
192#### Defined in
193​
194[packages/form-core/src/FieldApi.ts:643](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L643)
195​
196***
197​
198### handleBlur()
199​
200```ts
201handleBlur(): void
202```
203​
204Handles the blur event.
205​
206#### Returns
207​
208`void`
209​
210#### Defined in
211​
212[packages/form-core/src/FieldApi.ts:1024](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1024)
213​
214***
215​
216### handleChange()
217​
218```ts
219handleChange(updater): void
220```
221​
222Handles the change event.
223​
224#### Parameters
225​
226##### updater
227​
228[`Updater`](../type-aliases/updater.md)\<`TData`\>
229​
230#### Returns
231​
232`void`
233​
234#### Defined in
235​
236[packages/form-core/src/FieldApi.ts:1017](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1017)
237​
238***
239​
240### insertValue()
241​
242```ts
243insertValue(
244 index,
245 value,
246opts?): Promise<void>
247```
248​
249Inserts a value at the specified index, shifting the subsequent values to the right.
250​
251#### Parameters
252​
253##### index
254​
255`number`
256​
257##### value
258​
259`TData` *extends* `any`[] ? `TData`\<`TData`\>\[`number`\] : `never`
260​
261##### opts?
262​
263`UpdateMetaOptions`
264​
265#### Returns
266​
267`Promise`\<`void`\>
268​
269#### Defined in
270​
271[packages/form-core/src/FieldApi.ts:685](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L685)
272​
273***
274​
275### mount()
276​
277```ts
278mount(): () => void
279```
280​
281Mounts the field instance to the form.
282​
283#### Returns
284​
285`Function`
286​
287##### Returns
288​
289`void`
290​
291#### Defined in
292​
293[packages/form-core/src/FieldApi.ts:567](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L567)
294​
295***
296​
297### moveValue()
298​
299```ts
300moveValue(
301 aIndex,
302 bIndex,
303 opts?): void
304```
305​
306Moves the value at the first specified index to the second specified index.
307​
308#### Parameters
309​
310##### aIndex
311​
312`number`
313​
314##### bIndex
315​
316`number`
317​
318##### opts?
319​
320`UpdateMetaOptions`
321​
322#### Returns
323​
324`void`
325​
326#### Defined in
327​
328[packages/form-core/src/FieldApi.ts:715](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L715)
329​
330***
331​
332### pushValue()
333​
334```ts
335pushValue(value, opts?): void
336```
337​
338Pushes a new value to the field.
339​
340#### Parameters
341​
342##### value
343​
344`TData` *extends* `any`[] ? `TData`\<`TData`\>\[`number`\] : `never`
345​
346##### opts?
347​
348`UpdateMetaOptions`
349​
350#### Returns
351​
352`void`
353​
354#### Defined in
355​
356[packages/form-core/src/FieldApi.ts:677](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L677)
357​
358***
359​
360### removeValue()
361​
362```ts
363removeValue(index, opts?): Promise<void>
364```
365​
366Removes a value at the specified index.
367​
368#### Parameters
369​
370##### index
371​
372`number`
373​
374##### opts?
375​
376`UpdateMetaOptions`
377​
378#### Returns
379​
380`Promise`\<`void`\>
381​
382#### Defined in
383​
384[packages/form-core/src/FieldApi.ts:703](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L703)
385​
386***
387​
388### replaceValue()
389​
390```ts
391replaceValue(
392 index,
393 value,
394opts?): Promise<void>
395```
396​
397Replaces a value at the specified index.
398​
399#### Parameters
400​
401##### index
402​
403`number`
404​
405##### value
406​
407`TData` *extends* `any`[] ? `TData`\<`TData`\>\[`number`\] : `never`
408​
409##### opts?
410​
411`UpdateMetaOptions`
412​
413#### Returns
414​
415`Promise`\<`void`\>
416​
417#### Defined in
418​
419[packages/form-core/src/FieldApi.ts:694](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L694)
420​
421***
422​
423### setErrorMap()
424​
425```ts
426setErrorMap(errorMap): void
427```
428​
429Updates the field's errorMap
430​
431#### Parameters
432​
433##### errorMap
434​
435`ValidationErrorMap`
436​
437#### Returns
438​
439`void`
440​
441#### Defined in
442​
443[packages/form-core/src/FieldApi.ts:1044](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1044)
444​
445***
446​
447### setMeta()
448​
449```ts
450setMeta(updater): void
451```
452​
453Sets the field metadata.
454​
455#### Parameters
456​
457##### updater
458​
459[`Updater`](../type-aliases/updater.md)\<[`FieldMeta`](../type-aliases/fieldmeta.md)\>
460​
461#### Returns
462​
463`void`
464​
465#### Defined in
466​
467[packages/form-core/src/FieldApi.ts:666](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L666)
468​
469***
470​
471### setValue()
472​
473```ts
474setValue(updater, options?): void
475```
476​
477Sets the field value and run the `change` validator.
478​
479#### Parameters
480​
481##### updater
482​
483[`Updater`](../type-aliases/updater.md)\<`TData`\>
484​
485##### options?
486​
487`UpdateMetaOptions`
488​
489#### Returns
490​
491`void`
492​
493#### Defined in
494​
495[packages/form-core/src/FieldApi.ts:650](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L650)
496​
497***
498​
499### swapValues()
500​
501```ts
502swapValues(
503 aIndex,
504 bIndex,
505 opts?): void
506```
507​
508Swaps the values at the specified indices.
509​
510#### Parameters
511​
512##### aIndex
513​
514`number`
515​
516##### bIndex
517​
518`number`
519​
520##### opts?
521​
522`UpdateMetaOptions`
523​
524#### Returns
525​
526`void`
527​
528#### Defined in
529​
530[packages/form-core/src/FieldApi.ts:709](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L709)
531​
532***
533​
534### update()
535​
536```ts
537update(opts): void
538```
539​
540Updates the field instance with new options.
541​
542#### Parameters
543​
544##### opts
545​
546[`FieldApiOptions`](../interfaces/fieldapioptions.md)\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\>
547​
548#### Returns
549​
550`void`
551​
552#### Defined in
553​
554[packages/form-core/src/FieldApi.ts:606](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L606)
555​
556***
557​
558### validate()
559​
560```ts
561validate(cause): ValidationError[] | Promise<ValidationError[]>
562```
563​
564Validates the field value.
565​
566#### Parameters
567​
568##### cause
569​
570`ValidationCause`
571​
572#### Returns
573​
574[`ValidationError`](../type-aliases/validationerror.md)[] \| `Promise`\<[`ValidationError`](../type-aliases/validationerror.md)[]\>
575​
576#### Defined in
577​
578[packages/form-core/src/FieldApi.ts:989](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L989)