FormApi

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

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

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 extends undefined | FormValidateOrFn<TFormData>

TOnChange extends undefined | FormValidateOrFn<TFormData>

TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>

TOnBlur extends undefined | FormValidateOrFn<TFormData>

TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>

TOnSubmit extends undefined | FormValidateOrFn<TFormData>

TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>

TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>

TSubmitMeta = never

Constructors

new FormApi()

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

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

Constructs a new FormApi instance with the given form options.

Parameters

opts?

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

Returns

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

Properties

baseStore

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

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


fieldInfo

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

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

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


fieldMetaDerived

ts
fieldMetaDerived: Derived<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, AnyFieldMeta>>;
fieldMetaDerived: Derived<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, AnyFieldMeta>>;

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


options

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

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

The options for the form.


store

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

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

Accessors

state

Get Signature

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

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

Returns

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

Methods

deleteField()

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

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

Type Parameters

TField extends string | number

Parameters

field

TField

Returns

void


getAllErrors()

ts
getAllErrors(): object
getAllErrors(): object

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

Returns form and field level errors

Returns

object

fields
ts
fields: Record<DeepKeys<TFormData>, {
  errorMap: ValidationErrorMap;
  errors: unknown[];
}>;
fields: Record<DeepKeys<TFormData>, {
  errorMap: ValidationErrorMap;
  errors: unknown[];
}>;
form
ts
form: object;
form: object;
form.errorMap
ts
errorMap: FormValidationErrorMap<UnwrapFormValidateOrFn<TOnMount>, UnwrapFormValidateOrFn<TOnChange>, UnwrapFormAsyncValidateOrFn<TOnChangeAsync>, UnwrapFormValidateOrFn<TOnBlur>, UnwrapFormAsyncValidateOrFn<TOnBlurAsync>, UnwrapFormValidateOrFn<TOnSubmit>, UnwrapFormAsyncValidateOrFn<TOnSubmitAsync>, UnwrapFormAsyncValidateOrFn<TOnServer>>;
errorMap: FormValidationErrorMap<UnwrapFormValidateOrFn<TOnMount>, UnwrapFormValidateOrFn<TOnChange>, UnwrapFormAsyncValidateOrFn<TOnChangeAsync>, UnwrapFormValidateOrFn<TOnBlur>, UnwrapFormAsyncValidateOrFn<TOnBlurAsync>, UnwrapFormValidateOrFn<TOnSubmit>, UnwrapFormAsyncValidateOrFn<TOnSubmitAsync>, UnwrapFormAsyncValidateOrFn<TOnServer>>;
form.errors
ts
errors: (
  | UnwrapFormValidateOrFn<TOnMount>
  | UnwrapFormValidateOrFn<TOnChange>
  | UnwrapFormAsyncValidateOrFn<TOnChangeAsync>
  | UnwrapFormValidateOrFn<TOnBlur>
  | UnwrapFormAsyncValidateOrFn<TOnBlurAsync>
  | UnwrapFormValidateOrFn<TOnSubmit>
  | UnwrapFormAsyncValidateOrFn<TOnSubmitAsync>
  | UnwrapFormAsyncValidateOrFn<TOnServer>)[];
errors: (
  | UnwrapFormValidateOrFn<TOnMount>
  | UnwrapFormValidateOrFn<TOnChange>
  | UnwrapFormAsyncValidateOrFn<TOnChangeAsync>
  | UnwrapFormValidateOrFn<TOnBlur>
  | UnwrapFormAsyncValidateOrFn<TOnBlurAsync>
  | UnwrapFormValidateOrFn<TOnSubmit>
  | UnwrapFormAsyncValidateOrFn<TOnSubmitAsync>
  | UnwrapFormAsyncValidateOrFn<TOnServer>)[];

getFieldInfo()

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

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

Gets the field info of the specified field.

Type Parameters

TField extends string | number

Parameters

field

TField

Returns

FieldInfo<TFormData>


getFieldMeta()

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

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

Gets the metadata of the specified field.

Type Parameters

TField extends string | number

Parameters

field

TField

Returns

undefined | AnyFieldMeta


getFieldValue()

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

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

Gets the value of the specified field.

Type Parameters

TField extends string | number

Parameters

field

TField

Returns

DeepValue<TFormData, TField>


handleSubmit()

Call Signature

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

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

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

Returns

Promise<void>

Call Signature

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

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

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

Parameters
submitMeta

TSubmitMeta

Returns

Promise<void>


insertFieldValue()

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

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

Type Parameters

TField extends string | number

Parameters

field

TField

index

number

value

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

opts?

UpdateMetaOptions

Returns

Promise<void>


mount()

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

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

Returns

Function

Returns

void


moveFieldValues()

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

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

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


pushFieldValue()

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

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

Pushes a value into an array field.

Type Parameters

TField extends string | number

Parameters

field

TField

value

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

opts?

UpdateMetaOptions

Returns

void


removeFieldValue()

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

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

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>


replaceFieldValue()

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

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

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, []> extends any[] ? any[] & DeepValue<TFormData, TField, []>[number] : never

opts?

UpdateMetaOptions

Returns

Promise<void>


reset()

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

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

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

Resets the field value and meta to default state

Type Parameters

TField extends string | number

Parameters

field

TField

Returns

void


resetFieldMeta()

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

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

resets every field's meta

Type Parameters

TField extends string | number

Parameters

fieldMeta

Record<TField, AnyFieldMeta>

Returns

Record<TField, AnyFieldMeta>


setErrorMap()

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

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

Updates the form's errorMap

Parameters

errorMap

ValidationErrorMap<TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync>

Returns

void


setFieldMeta()

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

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

Updates the metadata of the specified field.

Type Parameters

TField extends string | number

Parameters

field

TField

updater

Updater<AnyFieldMeta>

Returns

void


setFieldValue()

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

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

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

opts?

UpdateMetaOptions

Returns

void


swapFieldValues()

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

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

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


update()

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

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

Updates the form options and form state.

Parameters

options?

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

Returns

void


validateAllFields()

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

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

Validates all fields using the correct handlers for a given validation cause.

Parameters

cause

ValidationCause

Returns

Promise<unknown[]>


validateArrayFieldsStartingFrom()

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

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

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


validateField()

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

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

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

unknown[] | Promise<unknown[]>

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.