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

FieldApi.md

492 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`](DeepKeys.md)\<`TParentData`\>
21​
22• **TFieldValidator** *extends* `Validator`\<[`DeepValue`](DeepValue.md)\<`TParentData`, `TName`\>, `unknown`\> \| `undefined` = `undefined`
23​
24• **TFormValidator** *extends* `Validator`\<`TParentData`, `unknown`\> \| `undefined` = `undefined`
25​
26• **TData** *extends* [`DeepValue`](DeepValue.md)\<`TParentData`, `TName`\> = [`DeepValue`](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`](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:432](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L432)
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:395](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L395)
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:405](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L405)
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:409](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L409)
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:423](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L423)
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:419](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L419)
119​
120## Methods
121​
122### getInfo()
123​
124```ts
125getInfo(): FieldInfo<TParentData, TFormValidator>
126```
127​
128Gets the field information object.
129​
130#### Returns
131​
132[`FieldInfo`](FieldInfo.md)\<`TParentData`, `TFormValidator`\>
133​
134#### Defined in
135​
136[packages/form-core/src/FieldApi.ts:642](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L642)
137​
138***
139​
140### getMeta()
141​
142```ts
143getMeta(): FieldMeta
144```
145​
146Gets the current field metadata.
147​
148#### Returns
149​
150[`FieldMeta`](FieldMeta.md)
151​
152#### Defined in
153​
154[packages/form-core/src/FieldApi.ts:621](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L621)
155​
156***
157​
158### ~~getValue()~~
159​
160```ts
161getValue(): TData
162```
163​
164Gets the current field value.
165​
166#### Returns
167​
168`TData`
169​
170#### Deprecated
171​
172Use `field.state.value` instead.
173​
174#### Defined in
175​
176[packages/form-core/src/FieldApi.ts:601](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L601)
177​
178***
179​
180### handleBlur()
181​
182```ts
183handleBlur(): void
184```
185​
186Handles the blur event.
187​
188#### Returns
189​
190`void`
191​
192#### Defined in
193​
194[packages/form-core/src/FieldApi.ts:956](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L956)
195​
196***
197​
198### handleChange()
199​
200```ts
201handleChange(updater): void
202```
203​
204Handles the change event.
205​
206#### Parameters
207​
208• **updater**: [`Updater`](Updater.md)\<`TData`\>
209​
210#### Returns
211​
212`void`
213​
214#### Defined in
215​
216[packages/form-core/src/FieldApi.ts:949](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L949)
217​
218***
219​
220### insertValue()
221​
222```ts
223insertValue(
224 index,
225 value,
226opts?): Promise<void>
227```
228​
229Inserts a value at the specified index, shifting the subsequent values to the right.
230​
231#### Parameters
232​
233• **index**: `number`
234​
235• **value**: `TData` *extends* `any`[] ? `TData`\<`TData`\>\[`number`\] : `never`
236​
237• **opts?**: `UpdateMetaOptions`
238​
239#### Returns
240​
241`Promise`\<`void`\>
242​
243#### Defined in
244​
245[packages/form-core/src/FieldApi.ts:655](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L655)
246​
247***
248​
249### mount()
250​
251```ts
252mount(): () => void
253```
254​
255Mounts the field instance to the form.
256​
257#### Returns
258​
259`Function`
260​
261##### Returns
262​
263`void`
264​
265#### Defined in
266​
267[packages/form-core/src/FieldApi.ts:517](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L517)
268​
269***
270​
271### moveValue()
272​
273```ts
274moveValue(
275 aIndex,
276 bIndex,
277 opts?): void
278```
279​
280Moves the value at the first specified index to the second specified index.
281​
282#### Parameters
283​
284• **aIndex**: `number`
285​
286• **bIndex**: `number`
287​
288• **opts?**: `UpdateMetaOptions`
289​
290#### Returns
291​
292`void`
293​
294#### Defined in
295​
296[packages/form-core/src/FieldApi.ts:685](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L685)
297​
298***
299​
300### pushValue()
301​
302```ts
303pushValue(value, opts?): void
304```
305​
306Pushes a new value to the field.
307​
308#### Parameters
309​
310• **value**: `TData` *extends* `any`[] ? `TData`\<`TData`\>\[`number`\] : `never`
311​
312• **opts?**: `UpdateMetaOptions`
313​
314#### Returns
315​
316`void`
317​
318#### Defined in
319​
320[packages/form-core/src/FieldApi.ts:647](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L647)
321​
322***
323​
324### removeValue()
325​
326```ts
327removeValue(index, opts?): Promise<void>
328```
329​
330Removes a value at the specified index.
331​
332#### Parameters
333​
334• **index**: `number`
335​
336• **opts?**: `UpdateMetaOptions`
337​
338#### Returns
339​
340`Promise`\<`void`\>
341​
342#### Defined in
343​
344[packages/form-core/src/FieldApi.ts:673](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L673)
345​
346***
347​
348### replaceValue()
349​
350```ts
351replaceValue(
352 index,
353 value,
354opts?): Promise<void>
355```
356​
357Replaces a value at the specified index.
358​
359#### Parameters
360​
361• **index**: `number`
362​
363• **value**: `TData` *extends* `any`[] ? `TData`\<`TData`\>\[`number`\] : `never`
364​
365• **opts?**: `UpdateMetaOptions`
366​
367#### Returns
368​
369`Promise`\<`void`\>
370​
371#### Defined in
372​
373[packages/form-core/src/FieldApi.ts:664](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L664)
374​
375***
376​
377### setMeta()
378​
379```ts
380setMeta(updater): void
381```
382​
383Sets the field metadata.
384​
385#### Parameters
386​
387• **updater**: [`Updater`](Updater.md)\<[`FieldMeta`](FieldMeta.md)\>
388​
389#### Returns
390​
391`void`
392​
393#### Defined in
394​
395[packages/form-core/src/FieldApi.ts:636](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L636)
396​
397***
398​
399### setValue()
400​
401```ts
402setValue(updater, options?): void
403```
404​
405Sets the field value and run the `change` validator.
406​
407#### Parameters
408​
409• **updater**: [`Updater`](Updater.md)\<`TData`\>
410​
411• **options?**: `UpdateMetaOptions`
412​
413#### Returns
414​
415`void`
416​
417#### Defined in
418​
419[packages/form-core/src/FieldApi.ts:608](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L608)
420​
421***
422​
423### swapValues()
424​
425```ts
426swapValues(
427 aIndex,
428 bIndex,
429 opts?): void
430```
431​
432Swaps the values at the specified indices.
433​
434#### Parameters
435​
436• **aIndex**: `number`
437​
438• **bIndex**: `number`
439​
440• **opts?**: `UpdateMetaOptions`
441​
442#### Returns
443​
444`void`
445​
446#### Defined in
447​
448[packages/form-core/src/FieldApi.ts:679](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L679)
449​
450***
451​
452### update()
453​
454```ts
455update(opts): void
456```
457​
458Updates the field instance with new options.
459​
460#### Parameters
461​
462• **opts**: [`FieldApiOptions`](FieldApiOptions.md)\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\>
463​
464#### Returns
465​
466`void`
467​
468#### Defined in
469​
470[packages/form-core/src/FieldApi.ts:564](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L564)
471​
472***
473​
474### validate()
475​
476```ts
477validate(cause): ValidationError[] | Promise<ValidationError[]>
478```
479​
480Validates the field value.
481​
482#### Parameters
483​
484• **cause**: `ValidationCause`
485​
486#### Returns
487​
488[`ValidationError`](ValidationError.md)[] \| `Promise`\<[`ValidationError`](ValidationError.md)[]\>
489​
490#### Defined in
491​
492[packages/form-core/src/FieldApi.ts:923](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L923)