form/docs/core/reference/formApi.md

id, title

id	title
formApi	Form API

Creating a new FormApi Instance

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 utilizes your frameworks reactivity model. However, if you need to create a new instance manually, you can do so by calling the new FormApi constructor.

const formApi: FormApi<TData> = new FormApi(formOptions: FormOptions<TData>)

FormOptions<TData>

An object representing the options for a form.

• defaultValues?: TData
  • The default values for the form fields.
• defaultState?: Partial<FormState<TData>>
  • The default state for the form.
• onSubmit?: (values: TData, formApi: FormApi<TData>) => Promise<any>
  • A function to be called when the form is submitted and valid.
• onInvalidSubmit?: (values: TData, formApi: FormApi<TData>) => void
  • A function to be called when the form is submitted but invalid.
• validate?: (values: TData, formApi: FormApi<TData>) => Promise<any>
  • A function for custom validation logic for the form.
• debugForm?: boolean
  • A boolean flag to enable or disable form debugging.
• validatePristine?: boolean
  • A boolean flag to enable or disable validation for pristine fields.

FormApi<TFormData>

A class representing the Form API. It handles the logic and interactions with the form state.

Properties

• options: FormOptions<TFormData>
  • The options for the form.
• store: Store<FormState<TFormData>>
  • The internal store for the form state.
• state: FormState<TFormData>
  • The current state of the form.
• fieldInfo: Record<DeepKeys<TFormData>, FieldInfo<TFormData>>
  • A record of field information for each field in the form.
• fieldName?: string
  • An optional string representing the name of the field.
• validationMeta: ValidationMeta
  • The validation metadata for the form.

Methods

• constructor(opts?: FormOptions<TFormData>)
  • Constructs a new FormApi instance with the given form options.
• update(options: FormOptions<TFormData>)
  • Updates the form options and form state.
• reset()
  • Resets the form state to the default values.
• validateAllFields()
  • Validates all fields in the form.
• validateForm()
  • Validates the form itself.
• handleSubmit(e: FormEvent & { __handled?: boolean })
  • Handles the form submission event, performs validation, and calls the appropriate onSubmit or onInvalidSubmit callbacks.
• getFieldValue<TField extends DeepKeys<TFormData>>(field: TField)
  • Gets the value of the specified field.
• getFieldMeta<TField extends DeepKeys<TFormData>>(field: TField)
  • Gets the metadata of the specified field.
• getFieldInfo<TField extends DeepKeys<TFormData>>(field: TField)
  • Gets the field info of the specified field.
• `setFieldMeta<TField extends DeepKeys>(field: TField, updater: Updater)
  • Updates the metadata of the specified field.
• `setFieldValue<TField extends DeepKeys>(field: TField, updater: Updater<DeepValue<TFormData, TField>>, opts?: { touch?: boolean })
  • Sets the value of the specified field and optionally updates the touched state.
• `pushFieldValue<TField extends DeepKeys>(field: TField, value: DeepValue<TFormData, TField>, opts?: { touch?: boolean })
  • Pushes a value into an array field.
• `insertFieldValue<TField extends DeepKeys>(field: TField, index: number, value: DeepValue<TFormData, TField>, opts?: { touch?: boolean })
  • Inserts a value into an array field at the specified index.
• `spliceFieldValue<TField extends DeepKeys>(field: TField, index: number, opts?: { touch?: boolean })
  • Removes a value from an array field at the specified index.
• `swapFieldValues<TField extends DeepKeys>(field: TField, index1: number, index2: number)
  • Swaps the values at the specified indices within an array field.

FormState<TData>

An object representing the current state of the form.

• values: TData
  • The current values of the form fields.
• isFormValidating: boolean
  • A boolean indicating if the form is currently validating.
• formValidationCount: number
  • A counter for tracking the number of validations performed on the form.
• isFormValid: boolean
  • A boolean indicating if the form is valid.
• formError?: ValidationError
  • A possible validation error for the form.
• fieldMeta: Record<DeepKeys<TData>, FieldMeta>
  • A record of field metadata for each field in the form.
• isFieldsValidating: boolean
  • A boolean indicating if any of the form fields are currently validating.
• isFieldsValid: boolean
  • A boolean indicating if all the form fields are valid.
• isSubmitting: boolean
  • A boolean indicating if the form is currently submitting.
• isTouched: boolean
  • A boolean indicating if any of the form fields have been touched.
• isSubmitted: boolean
  • A boolean indicating if the form has been submitted.
• isValidating: boolean
  • A boolean indicating if the form or any of its fields are currently validating.
• isValid: boolean
  • A boolean indicating if the form and all its fields are valid.
• canSubmit: boolean
  • A boolean indicating if the form can be submitted based on its current state.
• submissionAttempts: number
  • A counter for tracking the number of submission attempts.

FieldInfo<TFormData>

An object representing the field information for a specific field within the form.

• instances: Record<string, FieldApi<any, TFormData>>
  • A record of field instances with unique identifiers as keys.
• validationCount?: number
  • A counter for tracking the number of validations performed on the field.
• validationPromise?: Promise<ValidationError>
  • A promise representing the current validation state of the field.
• validationResolve?: (error: ValidationError) => void
  • A function to resolve the validation promise with a possible validation error.
• validationReject?: (error: unknown) => void
  • A function to reject the validation promise with an error.

ValidationMeta

An object representing the validation metadata for a field.

• validationCount?: number
  • A counter for tracking the number of validations performed on the field.
• validationPromise?: Promise<ValidationError>
  • A promise representing the current validation state of the field.
• validationResolve?: (error: ValidationError) => void
  • A function to resolve the validation promise with a possible validation error.
• validationReject?: (error: unknown) => void
  • A function to reject the validation promise with an error.

ValidationError

A type representing a validation error. Possible values are undefined, false, null, or a string with an error message.