TanStack
Form v1v1
Docs
CodeRabbit
Cloudflare
AG Grid
SerpAPI
Netlify
OpenRouter
WorkOS
Clerk
Electric
PowerSync
Sentry
Railway
Prisma
Strapi
Unkey
CodeRabbit
Cloudflare
AG Grid
SerpAPI
Netlify
OpenRouter
WorkOS
Clerk
Electric
PowerSync
Sentry
Railway
Prisma
Strapi
Unkey
Menu
Getting Started
Guides
API Reference
Examples
API Reference

FormApi

Class: FormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>

Defined in: packages/form-core/src/FormApi.ts:873

A class representing the Form API. It handles the logic and interactions with the form state.

Normally, you will not need to create a new FormApi instance directly. Instead, you will use a framework hook/function like useForm or createForm 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 FormApi constructor.

Type Parameters

TFormData

TFormData

TOnMount

TOnMount extends undefined | FormValidateOrFn<TFormData>

TOnChange

TOnChange extends undefined | FormValidateOrFn<TFormData>

TOnChangeAsync

TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>

TOnBlur

TOnBlur extends undefined | FormValidateOrFn<TFormData>

TOnBlurAsync

TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>

TOnSubmit

TOnSubmit extends undefined | FormValidateOrFn<TFormData>

TOnSubmitAsync

TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>

TOnDynamic

TOnDynamic extends undefined | FormValidateOrFn<TFormData>

TOnDynamicAsync

TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>

TOnServer

TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>

TSubmitMeta

TSubmitMeta = never

Constructors

Constructor

ts
new FormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>(opts?): FormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>;
new FormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>(opts?): FormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>;

Defined in: packages/form-core/src/FormApi.ts:979

Constructs a new FormApi instance with the given form options.

Parameters

opts?

FormOptions<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>

Returns

FormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>

Properties

baseStore

ts
baseStore: Store<BaseFormState<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer>>;
baseStore: Store<BaseFormState<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer>>;

Defined in: packages/form-core/src/FormApi.ts:905

fieldInfo

ts
fieldInfo: Partial<Record<DeepKeys<TFormData>, FieldInfo<TFormData>>> = {};
fieldInfo: Partial<Record<DeepKeys<TFormData>, FieldInfo<TFormData>>> = {};

Defined in: packages/form-core/src/FormApi.ts:953

A record of field information for each field in the form.

fieldMetaDerived

ts
fieldMetaDerived: Store<Partial<Record<DeepKeys<TFormData>, AnyFieldMeta>>>;
fieldMetaDerived: Store<Partial<Record<DeepKeys<TFormData>, AnyFieldMeta>>>;

Defined in: packages/form-core/src/FormApi.ts:920

options

ts
options: FormOptions<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta> = {};
options: FormOptions<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta> = {};

Defined in: packages/form-core/src/FormApi.ts:890

The options for the form.

store

ts
store: ReadonlyStore<FormState<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer>>;
store: ReadonlyStore<FormState<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer>>;

Defined in: packages/form-core/src/FormApi.ts:935

Accessors

formId

Get Signature

ts
get formId(): string;
get formId(): string;

Defined in: packages/form-core/src/FormApi.ts:1359

Returns

string

state

Get Signature

ts
get state(): FormState<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer>;
get state(): FormState<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer>;

Defined in: packages/form-core/src/FormApi.ts:955

Returns

FormState<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer>

Methods

_handleSubmit()

ts
_handleSubmit(submitMeta?): Promise<void>;
_handleSubmit(submitMeta?): Promise<void>;

Defined in: packages/form-core/src/FormApi.ts:2106

Handles the form submission, performs validation, and calls the appropriate onSubmit or onSubmitInvalid callbacks.

Parameters

submitMeta?

TSubmitMeta

Returns

Promise<void>

clearFieldValues()

ts
clearFieldValues<TField>(field, options?): void;
clearFieldValues<TField>(field, options?): void;

Defined in: packages/form-core/src/FormApi.ts:2576

Clear all values within an array field.

Type Parameters

TField

TField extends string

Parameters

field

TField

options?

UpdateMetaOptions

Returns

void

Implementation of

ts
FieldManipulator.clearFieldValues
FieldManipulator.clearFieldValues

deleteField()

ts
deleteField<TField>(field): void;
deleteField<TField>(field): void;

Defined in: packages/form-core/src/FormApi.ts:2364

Type Parameters

TField

TField extends string

Parameters

field

TField

Returns

void

Implementation of

ts
FieldManipulator.deleteField
FieldManipulator.deleteField

getAllErrors()

ts
getAllErrors(): object;
getAllErrors(): object;

Defined in: packages/form-core/src/FormApi.ts:2699

Returns form and field level errors

Returns

object

fields
ts
fields: Record<DeepKeys<TFormData>, {
  errorMap: ValidationErrorMap;
  errors: ValidationError[];
}>;
fields: Record<DeepKeys<TFormData>, {
  errorMap: ValidationErrorMap;
  errors: ValidationError[];
}>;
form
ts
form: object;
form: object;
form.errorMap
ts
errorMap: ValidationErrorMap<UnwrapFormValidateOrFn<TOnMount>, UnwrapFormValidateOrFn<TOnChange>, UnwrapFormAsyncValidateOrFn<TOnChangeAsync>, UnwrapFormValidateOrFn<TOnBlur>, UnwrapFormAsyncValidateOrFn<TOnBlurAsync>, UnwrapFormValidateOrFn<TOnSubmit>, UnwrapFormAsyncValidateOrFn<TOnSubmitAsync>, UnwrapFormValidateOrFn<TOnDynamic>, UnwrapFormAsyncValidateOrFn<TOnDynamicAsync>, UnwrapFormAsyncValidateOrFn<TOnServer>>;
errorMap: ValidationErrorMap<UnwrapFormValidateOrFn<TOnMount>, UnwrapFormValidateOrFn<TOnChange>, UnwrapFormAsyncValidateOrFn<TOnChangeAsync>, UnwrapFormValidateOrFn<TOnBlur>, UnwrapFormAsyncValidateOrFn<TOnBlurAsync>, UnwrapFormValidateOrFn<TOnSubmit>, UnwrapFormAsyncValidateOrFn<TOnSubmitAsync>, UnwrapFormValidateOrFn<TOnDynamic>, UnwrapFormAsyncValidateOrFn<TOnDynamicAsync>, UnwrapFormAsyncValidateOrFn<TOnServer>>;
form.errors
ts
errors: NonNullable<
  | UnwrapFormValidateOrFn<TOnMount>
  | UnwrapFormValidateOrFn<TOnChange>
  | UnwrapFormAsyncValidateOrFn<TOnChangeAsync>
  | UnwrapFormValidateOrFn<TOnBlur>
  | UnwrapFormAsyncValidateOrFn<TOnBlurAsync>
  | UnwrapFormValidateOrFn<TOnSubmit>
  | UnwrapFormAsyncValidateOrFn<TOnSubmitAsync>
  | UnwrapFormValidateOrFn<TOnDynamic>
  | UnwrapFormAsyncValidateOrFn<TOnDynamicAsync>
  | UnwrapFormAsyncValidateOrFn<TOnServer>>[];
errors: NonNullable<
  | UnwrapFormValidateOrFn<TOnMount>
  | UnwrapFormValidateOrFn<TOnChange>
  | UnwrapFormAsyncValidateOrFn<TOnChangeAsync>
  | UnwrapFormValidateOrFn<TOnBlur>
  | UnwrapFormAsyncValidateOrFn<TOnBlurAsync>
  | UnwrapFormValidateOrFn<TOnSubmit>
  | UnwrapFormAsyncValidateOrFn<TOnSubmitAsync>
  | UnwrapFormValidateOrFn<TOnDynamic>
  | UnwrapFormAsyncValidateOrFn<TOnDynamicAsync>
  | UnwrapFormAsyncValidateOrFn<TOnServer>>[];

getFieldInfo()

ts
getFieldInfo<TField>(field): FieldInfo<TFormData>;
getFieldInfo<TField>(field): FieldInfo<TFormData>;

Defined in: packages/form-core/src/FormApi.ts:2268

Gets the field info of the specified field.

Type Parameters

TField

TField extends string

Parameters

field

TField

Returns

FieldInfo<TFormData>

getFieldMeta()

ts
getFieldMeta<TField>(field): AnyFieldMeta | undefined;
getFieldMeta<TField>(field): AnyFieldMeta | undefined;

Defined in: packages/form-core/src/FormApi.ts:2259

Gets the metadata of the specified field.

Type Parameters

TField

TField extends string

Parameters

field

TField

Returns

AnyFieldMeta | undefined

Implementation of

ts
FieldManipulator.getFieldMeta
FieldManipulator.getFieldMeta

getFieldValue()

ts
getFieldValue<TField>(field): DeepValue<TFormData, TField>;
getFieldValue<TField>(field): DeepValue<TFormData, TField>;

Defined in: packages/form-core/src/FormApi.ts:2252

Gets the value of the specified field.

Type Parameters

TField

TField extends string

Parameters

field

TField

Returns

DeepValue<TFormData, TField>

Implementation of

ts
FieldManipulator.getFieldValue
FieldManipulator.getFieldValue

handleSubmit()

Call Signature

ts
handleSubmit(): Promise<void>;
handleSubmit(): Promise<void>;

Defined in: packages/form-core/src/FormApi.ts:2097

Handles the form submission, performs validation, and calls the appropriate onSubmit or onSubmitInvalid callbacks.

Returns

Promise<void>

Implementation of
ts
FieldManipulator.handleSubmit
FieldManipulator.handleSubmit

Call Signature

ts
handleSubmit(submitMeta): Promise<void>;
handleSubmit(submitMeta): Promise<void>;

Defined in: packages/form-core/src/FormApi.ts:2098

Parameters
submitMeta

TSubmitMeta

Returns

Promise<void>

Implementation of
ts
FieldManipulator.handleSubmit
FieldManipulator.handleSubmit

insertFieldValue()

ts
insertFieldValue<TField>(
   field, 
   index, 
   value, 
options?): Promise<void>;
insertFieldValue<TField>(
   field, 
   index, 
   value, 
options?): Promise<void>;

Defined in: packages/form-core/src/FormApi.ts:2404

Type Parameters

TField

TField extends string

Parameters

field

TField

index

number

value

DeepValue<TFormData, TField> extends any[] ? any[] & DeepValue<TFormData, TField>[number] : never

options?

UpdateMetaOptions

Returns

Promise<void>

Implementation of

ts
FieldManipulator.insertFieldValue
FieldManipulator.insertFieldValue

mount()

ts
mount(): () => void;
mount(): () => void;

Defined in: packages/form-core/src/FormApi.ts:1388

Returns

ts
(): void;
(): void;
Returns

void

moveFieldValues()

ts
moveFieldValues<TField>(
   field, 
   index1, 
   index2, 
   options?): void;
moveFieldValues<TField>(
   field, 
   index1, 
   index2, 
   options?): void;

Defined in: packages/form-core/src/FormApi.ts:2544

Moves the value at the first specified index to the second specified index within an array field.

Type Parameters

TField

TField extends string

Parameters

field

TField

index1

number

index2

number

options?

UpdateMetaOptions

Returns

void

Implementation of

ts
FieldManipulator.moveFieldValues
FieldManipulator.moveFieldValues

parseValuesWithSchema()

ts
parseValuesWithSchema(schema): 
  | {
  fields: Record<string, StandardSchemaV1Issue[]>;
  form: Record<string, StandardSchemaV1Issue[]>;
}
  | undefined;
parseValuesWithSchema(schema): 
  | {
  fields: Record<string, StandardSchemaV1Issue[]>;
  form: Record<string, StandardSchemaV1Issue[]>;
}
  | undefined;

Defined in: packages/form-core/src/FormApi.ts:2765

Parses the form's values with a given standard schema and returns issues (if any). This method does NOT set any internal errors.

Parameters

schema

StandardSchemaV1<TFormData, unknown>

The standard schema to parse the form values with.

Returns

| { fields: Record<string, StandardSchemaV1Issue[]>; form: Record<string, StandardSchemaV1Issue[]>; } | undefined

parseValuesWithSchemaAsync()

ts
parseValuesWithSchemaAsync(schema): Promise<
  | {
  fields: Record<string, StandardSchemaV1Issue[]>;
  form: Record<string, StandardSchemaV1Issue[]>;
}
| undefined>;
parseValuesWithSchemaAsync(schema): Promise<
  | {
  fields: Record<string, StandardSchemaV1Issue[]>;
  form: Record<string, StandardSchemaV1Issue[]>;
}
| undefined>;

Defined in: packages/form-core/src/FormApi.ts:2777

Parses the form's values with a given standard schema and returns issues (if any). This method does NOT set any internal errors.

Parameters

schema

StandardSchemaV1<TFormData, unknown>

The standard schema to parse the form values with.

Returns

Promise< | { fields: Record<string, StandardSchemaV1Issue[]>; form: Record<string, StandardSchemaV1Issue[]>; } | undefined>

pushFieldValue()

ts
pushFieldValue<TField>(
   field, 
   value, 
   options?): void;
pushFieldValue<TField>(
   field, 
   value, 
   options?): void;

Defined in: packages/form-core/src/FormApi.ts:2388

Pushes a value into an array field.

Type Parameters

TField

TField extends string

Parameters

field

TField

value

DeepValue<TFormData, TField> extends any[] ? any[] & DeepValue<TFormData, TField>[number] : never

options?

UpdateMetaOptions

Returns

void

Implementation of

ts
FieldManipulator.pushFieldValue
FieldManipulator.pushFieldValue

removeFieldValue()

ts
removeFieldValue<TField>(
   field, 
   index, 
options?): Promise<void>;
removeFieldValue<TField>(
   field, 
   index, 
options?): Promise<void>;

Defined in: packages/form-core/src/FormApi.ts:2472

Removes a value from an array field at the specified index.

Type Parameters

TField

TField extends string

Parameters

field

TField

index

number

options?

UpdateMetaOptions

Returns

Promise<void>

Implementation of

ts
FieldManipulator.removeFieldValue
FieldManipulator.removeFieldValue

replaceFieldValue()

ts
replaceFieldValue<TField>(
   field, 
   index, 
   value, 
options?): Promise<void>;
replaceFieldValue<TField>(
   field, 
   index, 
   value, 
options?): Promise<void>;

Defined in: packages/form-core/src/FormApi.ts:2441

Replaces a value into an array field at the specified index.

Type Parameters

TField

TField extends string

Parameters

field

TField

index

number

value

DeepValue<TFormData, TField> extends any[] ? any[] & DeepValue<TFormData, TField>[number] : never

options?

UpdateMetaOptions

Returns

Promise<void>

Implementation of

ts
FieldManipulator.replaceFieldValue
FieldManipulator.replaceFieldValue

reset()

ts
reset(values?, opts?): void;
reset(values?, opts?): void;

Defined in: packages/form-core/src/FormApi.ts:1529

Resets the form state to the default values. If values are provided, the form will be reset to those values instead and the default values will be updated.

Parameters

values?

TFormData

Optional values to reset the form to.

opts?

Optional options to control the reset behavior.

keepDefaultValues?

boolean

Returns

void

resetField()

ts
resetField<TField>(field): void;
resetField<TField>(field): void;

Defined in: packages/form-core/src/FormApi.ts:2611

Resets the field value and meta to default state

Type Parameters

TField

TField extends string

Parameters

field

TField

Returns

void

Implementation of

ts
FieldManipulator.resetField
FieldManipulator.resetField

resetFieldMeta()

ts
resetFieldMeta<TField>(fieldMeta): Partial<Record<TField, AnyFieldMeta>>;
resetFieldMeta<TField>(fieldMeta): Partial<Record<TField, AnyFieldMeta>>;

Defined in: packages/form-core/src/FormApi.ts:2308

resets every field's meta

Type Parameters

TField

TField extends string

Parameters

fieldMeta

Partial<Record<TField, AnyFieldMeta>>

Returns

Partial<Record<TField, AnyFieldMeta>>

setErrorMap()

ts
setErrorMap(errorMap): void;
setErrorMap(errorMap): void;

Defined in: packages/form-core/src/FormApi.ts:2635

Updates the form's errorMap

Parameters

errorMap

FormValidationErrorMap<TFormData, UnwrapFormValidateOrFn<TOnMount>, UnwrapFormValidateOrFn<TOnChange>, UnwrapFormAsyncValidateOrFn<TOnChangeAsync>, UnwrapFormValidateOrFn<TOnBlur>, UnwrapFormAsyncValidateOrFn<TOnBlurAsync>, UnwrapFormValidateOrFn<TOnSubmit>, UnwrapFormAsyncValidateOrFn<TOnSubmitAsync>, UnwrapFormValidateOrFn<TOnDynamic>, UnwrapFormAsyncValidateOrFn<TOnDynamicAsync>, UnwrapFormAsyncValidateOrFn<TOnServer>>

Returns

void

setFieldMeta()

ts
setFieldMeta<TField>(field, updater): void;
setFieldMeta<TField>(field, updater): void;

Defined in: packages/form-core/src/FormApi.ts:2287

Updates the metadata of the specified field.

Type Parameters

TField

TField extends string

Parameters

field

TField

updater

Updater<AnyFieldMetaBase>

Returns

void

Implementation of

ts
FieldManipulator.setFieldMeta
FieldManipulator.setFieldMeta

setFieldValue()

ts
setFieldValue<TField>(
   field, 
   updater, 
   opts?): void;
setFieldValue<TField>(
   field, 
   updater, 
   opts?): void;

Defined in: packages/form-core/src/FormApi.ts:2324

Sets the value of the specified field and optionally updates the touched state.

Type Parameters

TField

TField extends string

Parameters

field

TField

updater

Updater<DeepValue<TFormData, TField>>

opts?

UpdateMetaOptions

Returns

void

Implementation of

ts
FieldManipulator.setFieldValue
FieldManipulator.setFieldValue

swapFieldValues()

ts
swapFieldValues<TField>(
   field, 
   index1, 
   index2, 
   options?): void;
swapFieldValues<TField>(
   field, 
   index1, 
   index2, 
   options?): void;

Defined in: packages/form-core/src/FormApi.ts:2512

Swaps the values at the specified indices within an array field.

Type Parameters

TField

TField extends string

Parameters

field

TField

index1

number

index2

number

options?

UpdateMetaOptions

Returns

void

Implementation of

ts
FieldManipulator.swapFieldValues
FieldManipulator.swapFieldValues

update()

ts
update(options?): void;
update(options?): void;

Defined in: packages/form-core/src/FormApi.ts:1462

Updates the form options and form state.

Parameters

options?

FormOptions<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>

Returns

void

validateAllFields()

ts
validateAllFields(cause): Promise<unknown[]>;
validateAllFields(cause): Promise<unknown[]>;

Defined in: packages/form-core/src/FormApi.ts:1575

Validates all fields according to the FIELD level validators. This will ignore FORM level validators, use form.validate({ValidationCause}) for a complete validation

Parameters

cause

ValidationCause

Returns

Promise<unknown[]>

Implementation of

ts
FieldManipulator.validateAllFields
FieldManipulator.validateAllFields

validateArrayFieldsStartingFrom()

ts
validateArrayFieldsStartingFrom<TField>(
   field, 
   index, 
cause): Promise<unknown[]>;
validateArrayFieldsStartingFrom<TField>(
   field, 
   index, 
cause): Promise<unknown[]>;

Defined in: packages/form-core/src/FormApi.ts:1608

Validates the children of a specified array in the form starting from a given index until the end using the correct handlers for a given validation type.

Type Parameters

TField

TField extends string

Parameters

field

TField

index

number

cause

ValidationCause

Returns

Promise<unknown[]>

Implementation of

ts
FieldManipulator.validateArrayFieldsStartingFrom
FieldManipulator.validateArrayFieldsStartingFrom

validateField()

ts
validateField<TField>(field, cause): any[] | Promise<any[]>;
validateField<TField>(field, cause): any[] | Promise<any[]>;

Defined in: packages/form-core/src/FormApi.ts:1649

Validates a specified field in the form using the correct handlers for a given validation type.

Type Parameters

TField

TField extends string

Parameters

field

TField

cause

ValidationCause

Returns

any[] | Promise<any[]>

Implementation of

ts
FieldManipulator.validateField
FieldManipulator.validateField
Edit on GitHub
Classes / FieldApi
Functions / formOptions
© 2026 TanStack LLC