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

formapi.md

676 lines13.4 KB

Class: FormApi<TFormData, TFormValidator>

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

• TFormValidator extends Validator<TFormData, unknown> | undefined = undefined

Constructors

new FormApi()

new FormApi<TFormData, TFormValidator>(opts?): FormApi<TFormData, TFormValidator>

Constructs a new FormApi instance with the given form options.

Parameters

• opts?: FormOptions<TFormData, TFormValidator>

Returns

FormApi<TFormData, TFormValidator>

Defined in

packages/form-core/src/FormApi.ts:386

Properties

fieldInfo

fieldInfo: Record<unknown extends TFormData ? string : TFormData extends readonly any[] & IsTuple<TFormData> ? PrefixTupleAccessor<TFormData<TFormData>, AllowedIndexes<TFormData<TFormData>, never>, []> : TFormData extends any[] ? PrefixArrayAccessor<TFormData<TFormData>, [any]> : TFormData extends Date ? never : TFormData extends object ? PrefixObjectAccessor<TFormData<TFormData>, []> : TFormData extends string | number | bigint | boolean ? "" : never, FieldInfo<TFormData, TFormValidator>>;

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

Defined in

packages/form-core/src/FormApi.ts:375


options

options: FormOptions<TFormData, TFormValidator> = {};

The options for the form.

Defined in

packages/form-core/src/FormApi.ts:359


state

state: FormState<TFormData>;

The current state of the form.

Note: Do not use state directly, as it is not reactive. Please use form.useStore() utility to subscribe to state

Defined in

packages/form-core/src/FormApi.ts:371


store

store: Store<FormState<TFormData>, (cb) => FormState<TFormData>>;

A TanStack Store instance that keeps track of the form's state.

Defined in

packages/form-core/src/FormApi.ts:363

Methods

deleteField()

deleteField<TField>(field): void

Type Parameters

• TField extends string | number

Parameters

• field: TField

Returns

void

Defined in

packages/form-core/src/FormApi.ts:1102


getFieldInfo()

getFieldInfo<TField>(field): FieldInfo<TFormData, TFormValidator>

Gets the field info of the specified field.

Type Parameters

• TField extends string | number

Parameters

• field: TField

Returns

FieldInfo<TFormData, TFormValidator>

Defined in

packages/form-core/src/FormApi.ts:1013


getFieldMeta()

getFieldMeta<TField>(field): undefined | FieldMeta

Gets the metadata of the specified field.

Type Parameters

• TField extends string | number

Parameters

• field: TField

Returns

undefined | FieldMeta

Defined in

packages/form-core/src/FormApi.ts:1004


getFieldValue()

getFieldValue<TField>(field): DeepValue<TFormData, TField, IsNullable<TFormData>>

Gets the value of the specified field.

Type Parameters

• TField extends string | number

Parameters

• field: TField

Returns

DeepValue<TFormData, TField, IsNullable<TFormData>>

Defined in

packages/form-core/src/FormApi.ts:997


handleSubmit()

handleSubmit(): Promise<void>

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

Returns

Promise<void>

Defined in

packages/form-core/src/FormApi.ts:937


insertFieldValue()

insertFieldValue<TField>(
   field, 
   index, 
   value, 
opts?): Promise<void>

Inserts a value into an array field at the specified index, shifting the subsequent values to the right.

Type Parameters

• TField extends string | number

Parameters

• field: TField

• index: number

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

• opts?: UpdateMetaOptions

Returns

Promise<void>

Defined in

packages/form-core/src/FormApi.ts:1134


mount()

mount(): void

Returns

void

Defined in

packages/form-core/src/FormApi.ts:513


moveFieldValues()

moveFieldValues<TField>(
   field, 
   index1, 
   index2, 
   opts?): void

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

Type Parameters

• TField extends string | number

Parameters

• field: TField

• index1: number

• index2: number

• opts?: UpdateMetaOptions

Returns

void

Defined in

packages/form-core/src/FormApi.ts:1252


pushFieldValue()

pushFieldValue<TField>(
   field, 
   value, 
   opts?): void

Pushes a value into an array field.

Type Parameters

• TField extends string | number

Parameters

• field: TField

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

• opts?: UpdateMetaOptions

Returns

void

Defined in

packages/form-core/src/FormApi.ts:1116


removeFieldValue()

removeFieldValue<TField>(
   field, 
   index, 
opts?): Promise<void>

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

Type Parameters

• TField extends string | number

Parameters

• field: TField

• index: number

• opts?: UpdateMetaOptions

Returns

Promise<void>

Defined in

packages/form-core/src/FormApi.ts:1187


replaceFieldValue()

replaceFieldValue<TField>(
   field, 
   index, 
   value, 
opts?): Promise<void>

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

Type Parameters

• TField extends string | number

Parameters

• field: TField

• index: number

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

• opts?: UpdateMetaOptions

Returns

Promise<void>

Defined in

packages/form-core/src/FormApi.ts:1161


reset()

reset(): void

Resets the form state to the default values.

Returns

void

Defined in

packages/form-core/src/FormApi.ts:576


resetFieldMeta()

resetFieldMeta<TField>(fieldMeta): Record<TField, FieldMeta>

Type Parameters

• TField extends string | number

Parameters

• fieldMeta: Record<TField, FieldMeta>

Returns

Record<TField, FieldMeta>

Defined in

packages/form-core/src/FormApi.ts:1047


setErrorMap()

setErrorMap(errorMap): void

Updates the form's errorMap

Parameters

• errorMap: ValidationErrorMap

Returns

void

Defined in

packages/form-core/src/FormApi.ts:1276


setFieldMeta()

setFieldMeta<TField>(field, updater): void

Updates the metadata of the specified field.

Type Parameters

• TField extends string | number

Parameters

• field: TField

• updater: Updater<FieldMeta>

Returns

void

Defined in

packages/form-core/src/FormApi.ts:1032


setFieldValue()

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

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

Type Parameters

• TField extends string | number

Parameters

• field: TField

• updater: Updater<DeepValue<TFormData, TField, IsNullable<TFormData>>>

• opts?: UpdateMetaOptions

Returns

void

Defined in

packages/form-core/src/FormApi.ts:1071


swapFieldValues()

swapFieldValues<TField>(
   field, 
   index1, 
   index2, 
   opts?): void

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

Type Parameters

• TField extends string | number

Parameters

• field: TField

• index1: number

• index2: number

• opts?: UpdateMetaOptions

Returns

void

Defined in

packages/form-core/src/FormApi.ts:1226


update()

update(options?): void

Updates the form options and form state.

Parameters

• options?: FormOptions<TFormData, TFormValidator>

Returns

void

Defined in

packages/form-core/src/FormApi.ts:536


validateAllFields()

validateAllFields(cause): Promise<ValidationError[]>

Validates all fields in the form using the correct handlers for a given validation type.

Parameters

• cause: ValidationCause

Returns

Promise<ValidationError[]>

Defined in

packages/form-core/src/FormApi.ts:591


validateArrayFieldsStartingFrom()

validateArrayFieldsStartingFrom<TField>(
   field, 
   index, 
cause): Promise<ValidationError[]>

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 extends string | number

Parameters

• field: TField

• index: number

• cause: ValidationCause

Returns

Promise<ValidationError[]>

Defined in

packages/form-core/src/FormApi.ts:625


validateField()

validateField<TField>(field, cause): ValidationError[] | Promise<ValidationError[]>

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

Type Parameters

• TField extends string | number

Parameters

• field: TField

• cause: ValidationCause

Returns

ValidationError[] | Promise<ValidationError[]>

Defined in

packages/form-core/src/FormApi.ts:664