TanStack
Form v1v1
Documentation
Framework
Version
Menu
Getting Started
Guides
API Reference
Examples

FieldApi

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:979

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

TParentData

TName

TName extends DeepKeys<TParentData>

TData

TData extends DeepValue<TParentData, TName>

TOnMount

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

TOnChange

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

TOnChangeAsync

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

TOnBlur

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

TOnBlurAsync

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

TOnSubmit

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

TOnSubmitAsync

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

TOnDynamic

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

TOnDynamicAsync

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

TFormOnMount

TFormOnMount extends undefined | FormValidateOrFn<TParentData>

TFormOnChange

TFormOnChange extends undefined | FormValidateOrFn<TParentData>

TFormOnChangeAsync

TFormOnChangeAsync extends undefined | FormAsyncValidateOrFn<TParentData>

TFormOnBlur

TFormOnBlur extends undefined | FormValidateOrFn<TParentData>

TFormOnBlurAsync

TFormOnBlurAsync extends undefined | FormAsyncValidateOrFn<TParentData>

TFormOnSubmit

TFormOnSubmit extends undefined | FormValidateOrFn<TParentData>

TFormOnSubmitAsync

TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TParentData>

TFormOnDynamic

TFormOnDynamic extends undefined | FormValidateOrFn<TParentData>

TFormOnDynamicAsync

TFormOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TParentData>

TFormOnServer

TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>

TParentSubmitMeta

TParentSubmitMeta

Constructors

Constructor
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:1133

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:1033

A reference to the form API instance.

name
ts
name: TName;

name: TName;

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

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:1065

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:1093

The field state store.

timeoutIds
ts
timeoutIds: object;

timeoutIds: object;

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

formListeners
ts
formListeners: Record<ListenerCause, ReturnType<typeof setTimeout> | null>;

formListeners: Record<ListenerCause, ReturnType<typeof setTimeout> | null>;

listeners
ts
listeners: Record<ListenerCause, ReturnType<typeof setTimeout> | null>;

listeners: Record<ListenerCause, ReturnType<typeof setTimeout> | null>;

validations
ts
validations: Record<ValidationCause, ReturnType<typeof setTimeout> | null>;

validations: Record<ValidationCause, ReturnType<typeof setTimeout> | null>;

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:1121

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:1555

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:1441

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:1405

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:1382

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:1943

Handles the blur event.

Returns

void

handleChange()
ts
handleChange(updater): void;

handleChange(updater): void;

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

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:1464

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:1277

Mounts the field instance to the form.

Returns
ts
(): void;

(): void;
Returns

void

moveValue()
ts
moveValue(
   aIndex, 
   bIndex, 
   options?): void;

moveValue(
   aIndex, 
   bIndex, 
   options?): void;

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

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): 
  | StandardSchemaV1Issue[]
  | undefined;

parseValueWithSchema(schema): 
  | StandardSchemaV1Issue[]
  | undefined;

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

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

| StandardSchemaV1Issue[] | undefined

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

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

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

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< | StandardSchemaV1Issue[] | undefined>

pushValue()
ts
pushValue(value, options?): void;

pushValue(value, options?): void;

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

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:1504

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:1484

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:1959

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:1410

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:1389

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:1519

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:1331

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:1903

Validates the field value.

Parameters
cause

ValidationCause

opts?
skipFormValidation?

boolean

Returns

unknown[] | Promise<unknown[]>

Edit on GitHub
JavaScript Reference
Classes / FormApi
Partners
Code Rabbit
Cloudflare
AG Grid
Netlify
Neon
WorkOS
Clerk
Convex
Electric
Sentry
Prisma
Strapi
Unkey
Subscribe to Bytes

Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.

Bytes

No spam. Unsubscribe at any time.

Subscribe to Bytes

Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.

Bytes

No spam. Unsubscribe at any time.