form/docs/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, ValidatorType>

An object representing the options for a form.

•   defaultValues?: TData
  

  • Set initial values for yonu form.

•   defaultState?: Partial<FormState<TData>>
  

  • The default state for the form.

•   asyncDebounceMs?: number
  

  • Optional time in milliseconds if you want to introduce a delay before firing off an async action.

• onMount?: (values: TData, formApi: FormApi<TData>) => ValidationError
  

  • Optional function that fires as soon as the component mounts.

•   onMountAsync?: ( values: TData, formApi: FormApi<TData>) => ValidationError | Promise<ValidationError>
  

  • Optional async function that fires when the component mounts

•   onMountAsyncDebounceMs?: number
  

  • The default time in milliseconds that if set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds.

•    onChange?: (values: TData, formApi: FormApi<TData>) => ValidationError
  

  • Optional function that checks the validity of your data whenever a value changes

•   onChangeAsync?: (values: TData, formApi: FormApi<TData>) => ValidationError | Promise<ValidationError>
  

  • Optional onChange asynchronous counterpart to onChange. Useful for more complex validation logic that might involve server requests.

•   onChangeAsyncDebounceMs?: number
  

  • The default time in milliseconds that if set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds.

•   onBlur?: (values: TData, formApi: FormApi<TData>) => ValidationError
  

  • Optional function that validates the form data when a field loses focus, returns a ValidationError

•   onBlurAsync?:  (values: TData,formApi: FormApi<TData>) => ValidationError | Promise<ValidationError>
  

  • Optional onBlur asynchronous validation method for when a field loses focus return a ValidationError or a promise of Promise<ValidationError>

•   onBlurAsyncDebounceMs?: number
  

  • The default time in milliseconds that if set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds.

• onSubmit?: (values: TData, formApi: FormApi<TData>) => any | Promise<any>
  

  • A function to be called when the form is submitted, what should happen once the user submits a valid form returns any or a promise Promise<any>

•   onSubmitInvalid?: (values: TData, formApi: FormApi<TData>) => void
  

  • Specify an action for scenarios where the user tries to submit an invalid form.

FormApi<TFormData, ValidatorType>

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

  • An internal mechanism that keeps track of the form's state.

• state: FormState<TFormData>
  

  • The current state of the form.

• fieldInfo: Record<DeepKeys<TFormData>, FieldInfo<TFormData>> ={} as any
  

  • 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.

•   handleSubmit()
  

  • Handles the form submission, 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<TFormData>>(field: TField, updater: Updater<FieldMeta>)
  

  • Updates the metadata of the specified field.

•   setFieldValue<TField extends DeepKeys<TFormData>>(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<TFormData>>(field: TField, value: DeepValue<TFormData, TField>, opts?: { touch?: boolean })
  

  • Pushes a value into an array field.

•   insertFieldValue<TField extends DeepKeys<TFormData>>(field: TField, index: number, value: DeepValue<TFormData, TField>, opts?: { touch?: boolean })
  

  • Inserts a value into an array field at the specified index.

•   removeFieldValue<TField extends DeepKeys<TFormData>>(field: TField, index: number, opts?: { touch?: boolean })
  

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

•   swapFieldValues<TField extends DeepKeys<TFormData>>(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.
  • Check below for ValidationMeta

ValidationMeta

An object representing the validation metadata for a field.

•   validationCount?: number
  

  • A counter for tracking the number of validations performed on the field.

•   validationAsyncCount?: number
  

  • A counter for tracking the number of validations performed on the field async.

•   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.

ValidationErrorMapKeys

A type representing the keys used to map to ValidationError in ValidationErrorMap. It is defined with on${Capitalize<ValidationCause>}

ValidationErrorMap

A type that represents a map with the keys as ValidationErrorMapKeys and the values as ValidationError