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

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

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

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

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

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

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

fieldInfo

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

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

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

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

fieldMetaDerived

fieldMetaDerived: Store<Partial<Record<DeepKeys<TFormData>, AnyFieldLikeMeta>>>;

fieldMetaDerived: Store<Partial<Record<DeepKeys<TFormData>, AnyFieldLikeMeta>>>;

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

formGroupApis

formGroupApis: Set<AnyFormGroupApi>;

formGroupApis: Set<AnyFormGroupApi>;

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

The set of currently-mounted FormGroupApi instances belonging to this form. Used by FieldApi.validate to cascade field-level changes into the validators of any group that encompasses the field.

formGroupMetaDerived

formGroupMetaDerived: ReadonlyStore<Record<string, AnyFormGroupMeta>>;

formGroupMetaDerived: ReadonlyStore<Record<string, AnyFormGroupMeta>>;

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

A derived store of every mounted FormGroupApi's meta, keyed by group name. Mirrors fieldMetaDerived for fields: per-group meta is computed once on the form (from baseStore.formGroupStateBase, fieldMetaDerived, and the registered formGroupApis) so reads from a FormGroupApi.store instance stay minimal.

options

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

The options for the form.

store

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

Accessors

formId

Get Signature

get formId(): string;

get formId(): string;

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

Returns

string

state

Get Signature

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

Returns

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

Methods

_handleSubmit()

_handleSubmit(submitMeta?): Promise<void>;

_handleSubmit(submitMeta?): Promise<void>;

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

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

Parameters

submitMeta?

TSubmitMeta

Returns

Promise<void>

clearFieldValues()

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

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

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

Clear all values within an array field.

Type Parameters

TField

TField extends string

Parameters

field

TField

options?

UpdateMetaOptions

Returns

void

Implementation of

FormLikeAPI.clearFieldValues

FormLikeAPI.clearFieldValues

deleteField()

deleteField<TField>(field): void;

deleteField<TField>(field): void;

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

Type Parameters

TField

TField extends string

Parameters

field

TField

Returns

void

Implementation of

FormLikeAPI.deleteField

FormLikeAPI.deleteField

getAllErrors()

getAllErrors(): object;

getAllErrors(): object;

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

Returns form and field level errors

Returns

object

fields

fields: Record<DeepKeys<TFormData>, {
  errorMap: ValidationErrorMap;
  errors: ValidationError[];
}>;

fields: Record<DeepKeys<TFormData>, {
  errorMap: ValidationErrorMap;
  errors: ValidationError[];
}>;

form

form: object;

form: object;

form.errorMap

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

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()

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

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

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

Gets the field info of the specified field.

Type Parameters

TField

TField extends string

Parameters

field

TField

Returns

FieldInfo<TFormData>

getFieldMeta()

getFieldMeta<TField>(field): AnyFieldLikeMeta | undefined;

getFieldMeta<TField>(field): AnyFieldLikeMeta | undefined;

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

Gets the metadata of the specified field.

Type Parameters

TField

TField extends string

Parameters

field

TField

Returns

AnyFieldLikeMeta | undefined

Implementation of

FormLikeAPI.getFieldMeta

FormLikeAPI.getFieldMeta

getFieldValue()

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

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

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

Gets the value of the specified field.

Type Parameters

TField

TField extends string

Parameters

field

TField

Returns

DeepValue<TFormData, TField>

Implementation of

FormLikeAPI.getFieldValue

FormLikeAPI.getFieldValue

getFormGroupMeta()

getFormGroupMeta(name): AnyFormGroupMeta | undefined;

getFormGroupMeta(name): AnyFormGroupMeta | undefined;

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

Gets the derived meta of the form group registered at the given name. Mirrors getFieldMeta for fields. Returns undefined if no FormGroupApi with that name is currently mounted.

Parameters

name

string

Returns

AnyFormGroupMeta | undefined

handleSubmit()

Call Signature

handleSubmit(): Promise<void>;

handleSubmit(): Promise<void>;

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

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

Returns

Promise<void>

Implementation of

FormLikeAPI.handleSubmit

FormLikeAPI.handleSubmit

Call Signature

handleSubmit(submitMeta): Promise<void>;

handleSubmit(submitMeta): Promise<void>;

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

Parameters

submitMeta

TSubmitMeta

Returns

Promise<void>

Implementation of

FormLikeAPI.handleSubmit

FormLikeAPI.handleSubmit

insertFieldValue()

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

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

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

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

FormLikeAPI.insertFieldValue

FormLikeAPI.insertFieldValue

mount()

mount(): () => void;

mount(): () => void;

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

Returns

(): void;

(): void;

Returns

void

moveFieldValues()

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

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

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

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

FormLikeAPI.moveFieldValues

FormLikeAPI.moveFieldValues

parseValuesWithSchema()

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

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()

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

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()

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

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

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

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

FormLikeAPI.pushFieldValue

FormLikeAPI.pushFieldValue

removeFieldValue()

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

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

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

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

FormLikeAPI.removeFieldValue

FormLikeAPI.removeFieldValue

replaceFieldValue()

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

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

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

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

FormLikeAPI.replaceFieldValue

FormLikeAPI.replaceFieldValue

reset()

reset(values?, opts?): void;

reset(values?, opts?): void;

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

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()

resetField<TField>(field): void;

resetField<TField>(field): void;

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

Resets the field value and meta to default state

Type Parameters

TField

TField extends string

Parameters

field

TField

Returns

void

Implementation of

FormLikeAPI.resetField

FormLikeAPI.resetField

resetFieldMeta()

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

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

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

resets every field's meta

Type Parameters

TField

TField extends string

Parameters

fieldMeta

Partial<Record<TField, AnyFieldLikeMeta>>

Returns

Partial<Record<TField, AnyFieldLikeMeta>>

setErrorMap()

setErrorMap(errorMap): void;

setErrorMap(errorMap): void;

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

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()

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

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

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

Updates the metadata of the specified field.

Type Parameters

TField

TField extends string

Parameters

field

TField

updater

Updater<AnyFieldLikeMetaBase>

Returns

void

Implementation of

FormLikeAPI.setFieldMeta

FormLikeAPI.setFieldMeta

setFieldValue()

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

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

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

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

FormLikeAPI.setFieldValue

FormLikeAPI.setFieldValue

swapFieldValues()

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

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

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

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

FormLikeAPI.swapFieldValues

FormLikeAPI.swapFieldValues

update()

update(options?): void;

update(options?): void;

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

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()

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

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

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

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

FormLikeAPI.validateAllFields

FormLikeAPI.validateAllFields

validateArrayFieldsStartingFrom()

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

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

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

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.

FormLikeAPI.validateArrayFieldsStartingFrom

FormLikeAPI.validateArrayFieldsStartingFrom

validateField()

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

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

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

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

FormLikeAPI.validateField

FormLikeAPI.validateField