Documentation
Framework
Version
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:862

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>

TOnDynamic extends undefined | FormValidateOrFn<TFormData>

TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>

TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>

TSubmitMeta = never

Implements

  • FieldManipulator<TFormData, TSubmitMeta>

Constructors

new FormApi()

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

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


fieldInfo

ts
fieldInfo: Record<DeepKeys<TFormData>, FieldInfo<TFormData>>;
fieldInfo: Record<DeepKeys<TFormData>, FieldInfo<TFormData>>;

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

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


fieldMetaDerived

ts
fieldMetaDerived: Derived<Record<DeepKeys<TFormData>, AnyFieldMeta>>;
fieldMetaDerived: Derived<Record<DeepKeys<TFormData>, AnyFieldMeta>>;

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


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

The options for the form.


store

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

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


timeoutIds

ts
timeoutIds: object;
timeoutIds: object;

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

formListeners

ts
formListeners: Record<ListenerCause, null | Timeout>;
formListeners: Record<ListenerCause, null | Timeout>;

listeners

ts
listeners: Record<ListenerCause, null | Timeout>;
listeners: Record<ListenerCause, null | Timeout>;

validations

ts
validations: Record<ValidationCause, null | Timeout>;
validations: Record<ValidationCause, null | Timeout>;

Accessors

formId

Get Signature

ts
get formId(): undefined | string
get formId(): undefined | string

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

Returns

undefined | 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:930

Returns

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

Methods

clearFieldValues()

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

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

Clear all values within an array field.

Type Parameters

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

Type Parameters

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

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: 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: (
  | UnwrapFormValidateOrFn<TOnMount>
  | UnwrapFormValidateOrFn<TOnChange>
  | UnwrapFormAsyncValidateOrFn<TOnChangeAsync>
  | UnwrapFormValidateOrFn<TOnBlur>
  | UnwrapFormAsyncValidateOrFn<TOnBlurAsync>
  | UnwrapFormValidateOrFn<TOnSubmit>
  | UnwrapFormAsyncValidateOrFn<TOnSubmitAsync>
  | UnwrapFormValidateOrFn<TOnDynamic>
  | UnwrapFormAsyncValidateOrFn<TOnDynamicAsync>
  | UnwrapFormAsyncValidateOrFn<TOnServer>)[];
errors: (
  | 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:2029

Gets the field info of the specified field.

Type Parameters

TField extends string

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

Gets the metadata of the specified field.

Type Parameters

TField extends string

Parameters

field

TField

Returns

undefined | AnyFieldMeta

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

Gets the value of the specified field.

Type Parameters

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

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

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

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

Type Parameters

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

Returns

Function

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

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

Type Parameters

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

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

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

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


parseValuesWithSchemaAsync()

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

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

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< | undefined | { fields: Record<string, StandardSchemaV1Issue[]>; form: Record<string, StandardSchemaV1Issue[]>; }>


pushFieldValue()

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

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

Pushes a value into an array field.

Type Parameters

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

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

Type Parameters

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

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

Type Parameters

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

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

Resets the field value and meta to default state

Type Parameters

TField extends string

Parameters

field

TField

Returns

void

Implementation of

ts
FieldManipulator.resetField
FieldManipulator.resetField

resetFieldMeta()

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

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

resets every field's meta

Type Parameters

TField extends string

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

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

Updates the metadata of the specified field.

Type Parameters

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

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

Type Parameters

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

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

Type Parameters

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

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

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

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

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

Parameters

field

TField

index

number

cause

ValidationCause

Returns

Promise<unknown[]>

Implementation of

ts
FieldManipulator.validateArrayFieldsStartingFrom
FieldManipulator.validateArrayFieldsStartingFrom

validateField()

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

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

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

Type Parameters

TField extends string

Parameters

field

TField

cause

ValidationCause

Returns

unknown[] | Promise<unknown[]>

Implementation of

ts
FieldManipulator.validateField
FieldManipulator.validateField
Our Partners
Code Rabbit
Cloudflare
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.

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.