--- id: formApi title: 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. ```tsx const formApi: FormApi = new FormApi(formOptions: FormOptions) ``` ### `FormOptions` An object representing the options for a form. - ```tsx defaultValues?: TData ``` - Set initial values for yonu form. - ```tsx defaultState?: Partial> ``` - The default state for the form. - ```tsx asyncDebounceMs?: number ``` - Optional time in milliseconds if you want to introduce a delay before firing off an async action. - ```tsx onMount?: (values: TData, formApi: FormApi) => ValidationError ``` - Optional function that fires as soon as the component mounts. - ```tsx onMountAsync?: ( values: TData, formApi: FormApi) => ValidationError | Promise ``` - Optional async function that fires when the component mounts - ```tsx 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. - ```tsx onChange?: (values: TData, formApi: FormApi) => ValidationError ``` - Optional function that checks the validity of your data whenever a value changes - ```tsx onChangeAsync?: (values: TData, formApi: FormApi) => ValidationError | Promise ``` - Optional onChange asynchronous counterpart to onChange. Useful for more complex validation logic that might involve server requests. - ```tsx 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. - ```tsx onBlur?: (values: TData, formApi: FormApi) => ValidationError ``` - Optional function that validates the form data when a field loses focus, returns a `ValidationError` - ```tsx onBlurAsync?: (values: TData,formApi: FormApi) => ValidationError | Promise ``` - Optional onBlur asynchronous validation method for when a field loses focus return a `ValidationError` or a promise of `Promise` - ```tsx 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. - ```tsx onSubmit?: (values: TData, formApi: FormApi) => any | Promise ``` - 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` - ```tsx onSubmitInvalid?: (values: TData, formApi: FormApi) => void ``` - Specify an action for scenarios where the user tries to submit an invalid form. ### `FormApi` A class representing the Form API. It handles the logic and interactions with the form state. #### Properties - ```tsx options: FormOptions = {} ``` - The options for the form. - ```tsx store: Store> ``` - An internal mechanism that keeps track of the form's state. - ```tsx state: FormState ``` - The current state of the form. - ```tsx fieldInfo: Record, FieldInfo> ={} as any ``` - A record of field information for each field in the form. - ```tsx fieldName?: string ``` - An optional string representing the name of the field. - ```tsx validationMeta: ValidationMeta ``` - The validation metadata for the form. #### Methods - ```tsx constructor(opts?: FormOptions) ``` - Constructs a new `FormApi` instance with the given form options. - ```tsx update(options: FormOptions) ``` - Updates the form options and form state. - ```tsx reset() ``` - Resets the form state to the default values. - ```tsx validateAllFields() ``` - Validates all fields in the form. - ```tsx handleSubmit() ``` - Handles the form submission, performs validation, and calls the appropriate onSubmit or onInvalidSubmit callbacks. - ```tsx getFieldValue>(field: TField) ``` - Gets the value of the specified field. - ```tsx getFieldMeta>(field: TField) ``` - Gets the metadata of the specified field. - ```tsx getFieldInfo>(field: TField) ``` - Gets the field info of the specified field. - ```tsx setFieldMeta>(field: TField, updater: Updater) ``` - Updates the metadata of the specified field. - ```tsx setFieldValue>(field: TField, updater: Updater>, opts?: { touch?: boolean }) ``` - Sets the value of the specified field and optionally updates the touched state. - ```tsx pushFieldValue>(field: TField, value: DeepValue, opts?: { touch?: boolean }) ``` - Pushes a value into an array field. - ```tsx insertFieldValue>(field: TField, index: number, value: DeepValue, opts?: { touch?: boolean }) ``` - Inserts a value into an array field at the specified index. - ```tsx removeFieldValue>(field: TField, index: number, opts?: { touch?: boolean }) ``` - Removes a value from an array field at the specified index. - ```tsx swapFieldValues>(field: TField, index1: number, index2: number) ``` - Swaps the values at the specified indices within an array field. ### `FormState` An object representing the current state of the form. - ```tsx values: TData ``` - The current values of the form fields. - ```tsx isFormValidating: boolean ``` - A boolean indicating if the form is currently validating. - ```tsx formValidationCount: number ``` - A counter for tracking the number of validations performed on the form. - ```tsx isFormValid: boolean ``` - A boolean indicating if the form is valid. - ```tsx formError?: ValidationError ``` - A possible validation error for the form. - ```tsx fieldMeta: Record, FieldMeta> ``` - A record of field metadata for each field in the form. - ```tsx isFieldsValidating: boolean ``` - A boolean indicating if any of the form fields are currently validating. - ```tsx isFieldsValid: boolean ``` - A boolean indicating if all the form fields are valid. - ```tsx isSubmitting: boolean ``` - A boolean indicating if the form is currently submitting. - ```tsx isTouched: boolean ``` - A boolean indicating if any of the form fields have been touched. - ```tsx isSubmitted: boolean ``` - A boolean indicating if the form has been submitted. - ```tsx isValidating: boolean ``` - A boolean indicating if the form or any of its fields are currently validating. - ```tsx isValid: boolean ``` - A boolean indicating if the form and all its fields are valid. - ```tsx canSubmit: boolean ``` - A boolean indicating if the form can be submitted based on its current state. - ```tsx submissionAttempts: number ``` - A counter for tracking the number of submission attempts. ### `FieldInfo` An object representing the field information for a specific field within the form. - ```tsx instances: Record> ``` - A record of field instances with unique identifiers as keys. - Check below for `ValidationMeta` ### `ValidationMeta` An object representing the validation metadata for a field. - ```tsx validationCount?: number ``` - A counter for tracking the number of validations performed on the field. - ```tsx validationAsyncCount?: number ``` - A counter for tracking the number of validations performed on the field async. - ```tsx validationPromise?: Promise ``` - A promise representing the current validation state of the field. - ```tsx validationResolve?: (error: ValidationError) => void ``` - A function to resolve the validation promise with a possible validation error. - ```tsx 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}` ### `ValidationErrorMap` A type that represents a map with the keys as `ValidationErrorMapKeys` and the values as `ValidationError`