📄 tanstack/form/latest/docs/reference/classes/fieldapi

File: fieldapi.md | Updated: 11/15/2025

Source: https://tanstack.com/form/latest/docs/reference/classes/fieldapi



TanStack

Form v1v1

Search...

+ K

Auto

Log In

TanStack StartRC

Docs Examples GitHub Contributors

TanStack Router

Docs Examples GitHub Contributors

TanStack Query

Docs Examples GitHub Contributors

TanStack Table

Docs Examples Github Contributors

TanStack Formnew

Docs Examples Github Contributors

TanStack DBbeta

Docs Github Contributors

TanStack Virtual

Docs Examples Github Contributors

TanStack Paceralpha

Docs Examples Github Contributors

TanStack Storealpha

Docs Examples Github Contributors

TanStack Devtoolsalpha

Docs Github Contributors

More Libraries

Maintainers Partners Support Learn StatsBETA Discord Merch Blog GitHub Ethos Brand Guide

Documentation

Framework

React logo

React

Version

Latest

Search...

+ K

Menu

Getting Started

Guides

API Reference

Examples

Framework

React logo

React

Version

Latest

Menu

Getting Started

Guides

API Reference

Examples

On this page

FieldApi

Copy Markdown

Class: FieldApi<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync, TFormOnServer, TParentSubmitMeta>
========================================================================================================================================================================================================================================================================================================================================================

Defined in: packages/form-core/src/FieldApi.ts:973

A class representing the API for managing a form field.

Normally, 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 uses your framework's reactivity model. However, if you need to create a new instance manually, you can do so by calling the new FieldApi constructor.

Type Parameters
---------------

• TParentData

• TName extends DeepKeys <TParentData>

• TData extends DeepValue <TParentData, TName>

• TOnMount extends undefined | FieldValidateOrFn<TParentData, TName, TData>

• TOnChange extends undefined | FieldValidateOrFn<TParentData, TName, TData>

• TOnChangeAsync extends undefined | FieldAsyncValidateOrFn<TParentData, TName, TData>

• TOnBlur extends undefined | FieldValidateOrFn<TParentData, TName, TData>

• TOnBlurAsync extends undefined | FieldAsyncValidateOrFn<TParentData, TName, TData>

• TOnSubmit extends undefined | FieldValidateOrFn<TParentData, TName, TData>

• TOnSubmitAsync extends undefined | FieldAsyncValidateOrFn<TParentData, TName, TData>

• TOnDynamic extends undefined | FieldValidateOrFn<TParentData, TName, TData>

• TOnDynamicAsync extends undefined | FieldAsyncValidateOrFn<TParentData, TName, TData>

• TFormOnMount extends undefined | FormValidateOrFn<TParentData>

• TFormOnChange extends undefined | FormValidateOrFn<TParentData>

• TFormOnChangeAsync extends undefined | FormAsyncValidateOrFn<TParentData>

• TFormOnBlur extends undefined | FormValidateOrFn<TParentData>

• TFormOnBlurAsync extends undefined | FormAsyncValidateOrFn<TParentData>

• TFormOnSubmit extends undefined | FormValidateOrFn<TParentData>

• TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TParentData>

• TFormOnDynamic extends undefined | FormValidateOrFn<TParentData>

• TFormOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TParentData>

• TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>

• TParentSubmitMeta

Constructors
------------ ### new FieldApi()

ts

new FieldApi<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync, TFormOnServer, TParentSubmitMeta>(opts): FieldApi<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync, TFormOnServer, TParentSubmitMeta>


new FieldApi<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync, TFormOnServer, TParentSubmitMeta>(opts): FieldApi<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync, TFormOnServer, TParentSubmitMeta>

Defined in: packages/form-core/src/FieldApi.ts:1127

Initializes a new FieldApi instance.

#### Parameters ##### opts

FieldApiOptions <TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync, TFormOnServer, TParentSubmitMeta>

#### Returns

FieldApi <TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync, TFormOnServer, TParentSubmitMeta>

Properties
---------- ### form

ts

form: FormApi<TParentData, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync, TFormOnServer, TParentSubmitMeta>;


form: FormApi<TParentData, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync, TFormOnServer, TParentSubmitMeta>;

Defined in: packages/form-core/src/FieldApi.ts:1027

A reference to the form API instance.

### name

ts

name: DeepKeys<TParentData>;


name: DeepKeys<TParentData>;

Defined in: packages/form-core/src/FieldApi.ts:1055

The field name.

### options

ts

options: FieldApiOptions<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync, TFormOnServer, TParentSubmitMeta>;


options: FieldApiOptions<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync, TFormOnServer, TParentSubmitMeta>;

Defined in: packages/form-core/src/FieldApi.ts:1059

The field options.

### store

ts

store: Derived<FieldState<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync>>;


store: Derived<FieldState<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync>>;

Defined in: packages/form-core/src/FieldApi.ts:1087

The field state store.

### timeoutIds

ts

timeoutIds: object;


timeoutIds: object;

Defined in: packages/form-core/src/FieldApi.ts:1118

#### formListeners

ts

formListeners: Record<ListenerCause, null | Timeout>;


formListeners: Record<ListenerCause, null | Timeout>;

#### listeners

ts

listeners: Record<ListenerCause, null | Timeout>;


listeners: Record<ListenerCause, null | Timeout>;

#### validations

ts

validations: Record<ValidationCause, null | Timeout>;


validations: Record<ValidationCause, null | Timeout>;

Accessors
--------- ### state #### Get Signature

ts

get state(): FieldState<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync>


get state(): FieldState<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync>

Defined in: packages/form-core/src/FieldApi.ts:1115

The current field state.

##### Returns

FieldState <TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync>

Methods
------- ### clearValues()

ts

clearValues(options?): void


clearValues(options?): void

Defined in: packages/form-core/src/FieldApi.ts:1519

Clear all values from the array.

#### Parameters ##### options?

UpdateMetaOptions

#### Returns

void

### getInfo()

ts

getInfo(): FieldInfo<TParentData>


getInfo(): FieldInfo<TParentData>

Defined in: packages/form-core/src/FieldApi.ts:1405

Gets the field information object.

#### Returns

FieldInfo <TParentData>

### getMeta()

ts

getMeta(): FieldMeta<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync>


getMeta(): FieldMeta<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync>

Defined in: packages/form-core/src/FieldApi.ts:1369

#### Returns

FieldMeta <TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync>

### ~getValue()~

ts

getValue(): TData


getValue(): TData

Defined in: packages/form-core/src/FieldApi.ts:1346

Gets the current field value.

#### Returns

TData

#### Deprecated

Use field.state.value instead.

### handleBlur()

ts

handleBlur(): void


handleBlur(): void

Defined in: packages/form-core/src/FieldApi.ts:1895

Handles the blur event.

#### Returns

void

### handleChange()

ts

handleChange(updater): void


handleChange(updater): void

Defined in: packages/form-core/src/FieldApi.ts:1888

Handles the change event.

#### Parameters ##### updater

Updater <TData>

#### Returns

void

### insertValue()

ts

insertValue(
   index, 
   value, 
   options?): void


insertValue(
   index, 
   value, 
   options?): void

Defined in: packages/form-core/src/FieldApi.ts:1428

Inserts a value at the specified index, shifting the subsequent values to the right.

#### Parameters ##### index

number

##### value

TData extends any[] ? TData<TData>[number] : never

##### options?

UpdateMetaOptions

#### Returns

void

### mount()

ts

mount(): () => void


mount(): () => void

Defined in: packages/form-core/src/FieldApi.ts:1232

Mounts the field instance to the form.

#### Returns

Function

##### Returns

void

### moveValue()

ts

moveValue(
   aIndex, 
   bIndex, 
   options?): void


moveValue(
   aIndex, 
   bIndex, 
   options?): void

Defined in: packages/form-core/src/FieldApi.ts:1503

Moves the value at the first specified index to the second specified index.

#### Parameters ##### aIndex

number

##### bIndex

number

##### options?

UpdateMetaOptions

#### Returns

void

### parseValueWithSchema()

ts

parseValueWithSchema(schema): 
  | undefined
  | StandardSchemaV1Issue[]


parseValueWithSchema(schema): 
  | undefined
  | StandardSchemaV1Issue[]

Defined in: packages/form-core/src/FieldApi.ts:1938

Parses the field's value with the given schema and returns issues (if any). This method does NOT set any internal errors.

#### Parameters ##### schema

StandardSchemaV1 <TData, unknown>

The standard schema to parse this field's value with.

#### Returns

| undefined | StandardSchemaV1Issue []

### parseValueWithSchemaAsync()

ts

parseValueWithSchemaAsync(schema): Promise<
  | undefined
| StandardSchemaV1Issue[]>


parseValueWithSchemaAsync(schema): Promise<
  | undefined
| StandardSchemaV1Issue[]>

Defined in: packages/form-core/src/FieldApi.ts:1950

Parses the field's value with the given schema and returns issues (if any). This method does NOT set any internal errors.

#### Parameters ##### schema

StandardSchemaV1 <TData, unknown>

The standard schema to parse this field's value with.

#### Returns

Promise< | undefined | StandardSchemaV1Issue []>

### pushValue()

ts

pushValue(value, options?): void


pushValue(value, options?): void

Defined in: packages/form-core/src/FieldApi.ts:1410

Pushes a new value to the field.

#### Parameters ##### value

TData extends any[] ? TData<TData>[number] : never

##### options?

UpdateMetaOptions

#### Returns

void

### removeValue()

ts

removeValue(index, options?): void


removeValue(index, options?): void

Defined in: packages/form-core/src/FieldApi.ts:1468

Removes a value at the specified index.

#### Parameters ##### index

number

##### options?

UpdateMetaOptions

#### Returns

void

### replaceValue()

ts

replaceValue(
   index, 
   value, 
   options?): void


replaceValue(
   index, 
   value, 
   options?): void

Defined in: packages/form-core/src/FieldApi.ts:1448

Replaces a value at the specified index.

#### Parameters ##### index

number

##### value

TData extends any[] ? TData<TData>[number] : never

##### options?

UpdateMetaOptions

#### Returns

void

### setErrorMap()

ts

setErrorMap(errorMap): void


setErrorMap(errorMap): void

Defined in: packages/form-core/src/FieldApi.ts:1911

Updates the field's errorMap

#### Parameters ##### errorMap

ValidationErrorMap<UnwrapFieldValidateOrFn <TName, TOnMount, TFormOnMount>, UnwrapFieldValidateOrFn <TName, TOnChange, TFormOnChange>, UnwrapFieldAsyncValidateOrFn <TName, TOnChangeAsync, TFormOnChangeAsync>, UnwrapFieldValidateOrFn <TName, TOnBlur, TFormOnBlur>, UnwrapFieldAsyncValidateOrFn <TName, TOnBlurAsync, TFormOnBlurAsync>, UnwrapFieldValidateOrFn <TName, TOnSubmit, TFormOnSubmit>, UnwrapFieldAsyncValidateOrFn <TName, TOnSubmitAsync, TFormOnSubmitAsync>, UnwrapFieldValidateOrFn <TName, TOnDynamic, TFormOnDynamic>, UnwrapFieldAsyncValidateOrFn <TName, TOnDynamicAsync, TFormOnDynamicAsync>>

#### Returns

void

### setMeta()

ts

setMeta(updater): void


setMeta(updater): void

Defined in: packages/form-core/src/FieldApi.ts:1374

Sets the field metadata.

#### Parameters ##### updater

Updater <FieldMetaBase <TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync>>

#### Returns

void

### setValue()

ts

setValue(updater, options?): void


setValue(updater, options?): void

Defined in: packages/form-core/src/FieldApi.ts:1353

Sets the field value and run the change validator.

#### Parameters ##### updater

Updater <TData>

##### options?

UpdateMetaOptions

#### Returns

void

### swapValues()

ts

swapValues(
   aIndex, 
   bIndex, 
   options?): void


swapValues(
   aIndex, 
   bIndex, 
   options?): void

Defined in: packages/form-core/src/FieldApi.ts:1483

Swaps the values at the specified indices.

#### Parameters ##### aIndex

number

##### bIndex

number

##### options?

UpdateMetaOptions

#### Returns

void

### update()

ts

update(opts): void


update(opts): void

Defined in: packages/form-core/src/FieldApi.ts:1285

Updates the field instance with new options.

#### Parameters ##### opts

FieldApiOptions <TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync, TFormOnServer, TParentSubmitMeta>

#### Returns

void

### validate()

ts

validate(cause, opts?): unknown[] | Promise<unknown[]>


validate(cause, opts?): unknown[] | Promise<unknown[]>

Defined in: packages/form-core/src/FieldApi.ts:1855

Validates the field value.

#### Parameters ##### cause

ValidationCause

##### opts? ###### skipFormValidation?

boolean

#### Returns

unknown[] | Promise<unknown[]>

Edit on GitHub

JavaScript Reference

Classes / FormApi

Partners Become a Partner

Code RabbitCode Rabbit CloudflareCloudflare AG GridAG Grid NetlifyNetlify NeonNeon WorkOSWorkOS ClerkClerk ConvexConvex ElectricElectric SentrySentry PrismaPrisma StrapiStrapi UnkeyUnkey

scarf analytics