Skip to content
Source
Sign inSign up
TanStack/form
Open History to see the last commit

fieldApi.md

300 lines7.8 KB

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: FieldOptions<TData>)

FieldOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>

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

  • name: TName
    • The field name. The type will be DeepKeys<TParentData> to ensure your name is a deep key of the parent dataset.
  • defaultValue?: TData
    • An optional default value for the field.
  • defaultMeta?: Partial<FieldMeta>
    • An optional object with default metadata for the field.
  • asyncDebounceMs?: number
    • The default time to debounce async validation if there is not a more specific debounce time passed.
  • asyncAlways?: boolean
    • If true, always run async validation, even if there are errors emitted during synchronous validation.
  • validatorAdapter?: ValidatorType
    • A validator provided by an extension, like yupValidator from @tanstack/yup-form-adapter
  • validators?: FieldValidators<
        TParentData,
        TName,
        TFieldValidator,
        TFormValidator,
        TData
    >
    • A list of validators to pass to the field

FieldValidators<TParentData, TName, TFieldValidator, TFormValidator, TData>

  • 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. If validator is passed, this may also accept a property from the respective validator (IE: z.string().min(1) if zodAdapter is passed)
  • onChangeAsync?: ValidateAsyncFn<TData, TParentData>
    • An optional property similar to onChange but async validation. If validator is passed, this may also accept a property from the respective validator (IE: z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' }) if zodAdapter is passed)
  • 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. If validator is passed, this may also accept a property from the respective validator (IE: z.string().min(1) if zodAdapter is passed)
  • onBlurAsync?: ValidateAsyncFn<TData, TParentData>
    • An optional function that takes a ValidateFn which is a generic of TData and TParentData happens async. If validator is passed, this may also accept a property from the respective validator (IE: z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' }) if zodAdapter is passed)
    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
  • onSubmit?: ValidateFn<TData, TParentData>
    • An optional function, when that run when subscribing to submit event of input. If validator is passed, this may also accept a property from the respective validator (IE: z.string().min(1) if zodAdapter is passed)
  • onSubmitAsync?: ValidateAsyncFn<TData, TParentData>
    • An optional function that takes a ValidateFn which is a generic of TData and TParentData happens async. If validator is passed, this may also accept a property from the respective validator (IE: z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' }) if zodAdapter is passed)
    onSubmitAsyncDebounceMs?: number
    • An optional number to represent how long the onSubmitAsyncDebounceMs 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

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<TParentData, TName, TFieldValidator, TFormValidator, TData>

A class representing the API for managing a form field.

Properties

  • uid: number
    • A unique identifier for the field instance.
  • form: FormApi<TParentData, TData>
    • 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.
  • 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 and run the change validator.
  • 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<TSubName, TSubData>(name: TName): FieldApi<TData, TSubName, ValidatorType, TSubData>
    • 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.