form/docs/reference/fieldApi.md

id, title

id	title
fieldApi	Field API

Creating a new FieldApi Instance

Normally, you will not need to create a new FieldApi instance directly. Instead, you will use a framework hook/function like useField or createField 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 FieldApi constructor.

const fieldApi: FieldApi<TData> = new FieldApi(formOptions: Field Options<TData>)

FieldOptions<TData, TParentData>

An object type representing the options for a field in a form.

• name
  

  • The field name. If TParentData is unknown, the type will be string. Otherwise, it will be DeepKeys<TParentData>.

• defaultValue?: TData
  

  • An optional default value for the field.

• defaultMeta?: Partial<FieldMeta>
  

  • An optional object with default metadata for the field.

• onMount?: (formApi: FieldApi<TData, TParentData>) => void
  

  • An optional function that takes a param of formApi which is a generic type of TData and TParentData

•  onChange?: ValidateFn<TData, TParentData>
  

  • An optional property that takes a ValidateFn which is a generic of TData and TParentData

•   onChangeAsync?: ValidateAsyncFn<TData, TParentData>
  

  • An optional property similar to onChange but async validation

•    onChangeAsyncDebounceMs?: number
  

  • An optional number to represent how long the onChangeAsync should wait before running
  • If set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds

•   onBlur?: ValidateFn<TData, TParentData>
  

  • An optional function, when that run when subscribing to blur event of input

•  onBlurAsync?: ValidateAsyncFn<TData, TParentData>
  

  • An optional function that takes a ValidateFn which is a generic of TData and TParentData happens async

  onBlurAsyncDebounceMs?: number
  

  • An optional number to represent how long the onBlurAsyncDebounceMs should wait before running
  • If set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds

  onSubmitAsync?: number
  

  • If set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds

ValidationCause

A type representing the cause of a validation event.

• 'change' | 'blur' | 'submit' | 'mount'

FieldMeta

An object type representing the metadata of a field in a form.

• isTouched: boolean
  

  • A flag indicating whether the field has been touched.

• touchedErrors: ValidationError[]
  

  • An array of errors related to the touched state of the field.

• errors: ValidationError[]
  

  • An array of errors related related to the field value.

• errorMap: ValidationErrorMap
  

  • A map of errors related related to the field value.

• isValidating: boolean
  

  • A flag indicating whether the field is currently being validated.

FieldApiOptions<TData, TParentData>

An object type representing the required options for the FieldApi class.

• Inherits from FieldOptions<TData, TParentData> with the form property set as required.

FieldApi<TData, TParentData>

A class representing the API for managing a form field.

Properties

• uid: number
  

  • A unique identifier for the field instance.

• form: FormApi<TParentData>
  

  • A reference to the form API instance.

• name: DeepKeys<TParentData>
  

  • The field name.

• store: Store<FieldState<TData>>
  

  • The field state store.

• state: FieldState<TData>
  

  • The current field state.

• options: RequiredByKey<FieldOptions<TData, TParentData>, 'validateOn'>
  

  • The field options with the validateOn property set as required.

Methods

• constructor(opts: FieldApiOptions<TData, TParentData>)
  

  • Initializes a new FieldApi instance.

• mount(): () => void
  

  • Mounts the field instance to the form.

• updateStore(): void
  

  • Updates the field store with the latest form state.

• update(opts: FieldApiOptions<TData, TParentData>): void
  

  • Updates the field instance with new options.

• getValue(): TData
  

  • Gets the current field value.

• setValue(updater: Updater<TData>, options?: { touch?: boolean; notify?: boolean }): void
  

  • Sets the field value.

• getMeta(): FieldMeta
  

  • Gets the current field metadata.

• setMeta(updater: Updater<FieldMeta>): void
  

  • Sets the field metadata.

• getInfo(): any
  

  • Gets the field information object.

• pushValue(value: TData): void
  

  • Pushes a new value to the field.

• insertValue(index: number, value: TData): void
  

  • Inserts a value at the specified index.

• removeValue(index: number): void
  

  • Removes a value at the specified index.

• swapValues(aIndex: number, bIndex: number): void
  

  • Swaps the values at the specified indices.

• getSubField<TName extends DeepKeys<TData>>(name: TName): FieldApi<DeepValue<TData, TName>, TParentData>
  

  • Gets a subfield instance.

• validate(): Promise<any>
  

  • Validates the field value.

• handleBlur(): void;
  

  • Handles the blur event.

• handleChange(value: TData): void
  

  • Handles the change event.

FieldState<TData>

An object type representing the state of a field.

• value: TData
  

  • The current value of the field.

• meta: FieldMeta
  

  • The current metadata of the field.

UserChangeProps<TData>

An object type representing the change and blur event handlers for a field.

• onChange?: (value: TData) => void
  

  • An optional function to further handle the change event.

• onBlur?: (event: any) => void
  

  • An optional function to further handle the blur event.

UserInputProps

An object type representing the input event handlers for a field.

• onChange?: (event: any) => void
  

  • An optional function to further handle the change event.

• onBlur?: (event: any) => void
  

  • An optional function to further handle the blur event.

ChangeProps<TData>

An object type representing the change and blur event handlers for a field.

• value: TData
  

  • The current value of the field.

• onChange: (value: TData) => void
  

  • A function to handle the change event.

• onBlur: (event: any) => void
  

  • A function to handle the blur event.

InputProps

An object type representing the input event handlers for a field.

• value: string
  

  • The current value of the field, coerced to a string.

• onChange: (event: any) => void
  

  • A function to handle the change event.

• onBlur: (event: any) => void
  

  • A function to handle the blur event.