FormApi

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#

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>;

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>>;

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

fieldInfo#

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>>>;

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

formGroupApis#

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>>;

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> = {};

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>>;

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

Accessors#

formId#

Get Signature#

get formId(): string;

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

Returns#

string

state#

Get Signature#

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>;

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

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;

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

Clear all values within an array field.

Type Parameters#

TField#

TField extends string

Parameters#

field#

TField

options?#

UpdateMetaOptions

Returns#

void

Implementation of#

FormLikeAPI.clearFieldValues

deleteField()#

deleteField<TField>(field): void;

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

Type Parameters#

TField#

TField extends string

Parameters#

field#

TField

Returns#

void

Implementation of#

FormLikeAPI.deleteField

getAllErrors()#

getAllErrors(): object;

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

Returns form and field level errors

Returns#

object

fields#

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

form#

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>>;

form.errors#

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>;

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

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;

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

Gets the metadata of the specified field.

Type Parameters#

TField#

TField extends string

Parameters#

field#

TField

Returns#

AnyFieldLikeMeta | undefined

Implementation of#

FormLikeAPI.getFieldMeta

getFieldValue()#

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

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

Gets the value of the specified field.

Type Parameters#

TField#

TField extends string

Parameters#

field#

TField

Returns#

DeepValue<TFormData, TField>

Implementation of#

FormLikeAPI.getFieldValue

getFormGroupMeta()#

getFormGroupMeta(name): AnyFormGroupMeta | undefined;

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

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>;

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

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

Returns#

Promise<void>

Implementation of#

FormLikeAPI.handleSubmit

Call Signature#

handleSubmit(submitMeta): Promise<void>;

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

Parameters#

submitMeta#

TSubmitMeta

Returns#

Promise<void>

Implementation of#

FormLikeAPI.handleSubmit

insertFieldValue()#

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

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

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

mount()#

mount(): () => void;

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

Returns#

(): void;

Returns#

void

moveFieldValues()#

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

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

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

parseValuesWithSchema()#

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

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

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>;

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

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;

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

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

removeFieldValue()#

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

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

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

replaceFieldValue()#

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

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

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

reset()#

reset(values?, opts?): void;

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

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;

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

Resets the field value and meta to default state

Type Parameters#

TField#

TField extends string

Parameters#

field#

TField

Returns#

void

Implementation of#

FormLikeAPI.resetField

resetFieldMeta()#

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

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

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;

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

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;

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

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

setFieldValue()#

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

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

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

swapFieldValues()#

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

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

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

update()#

update(options?): void;

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

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[]>;

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

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#

FormLikeAPI.validateAllFields

validateArrayFieldsStartingFrom()#

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

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

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#

FormLikeAPI.validateArrayFieldsStartingFrom

validateField()#

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

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

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#

FormLikeAPI.validateField