Open History to see the last commit
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.
- The field name. The type will be
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.
- If
validatorAdapter?: ValidatorType- A validator provided by an extension, like
yupValidatorfrom@tanstack/yup-form-adapter
- A validator provided by an extension, like
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
formApiwhich is a generic type ofTDataandTParentData
- An optional function that takes a param of
onChange?: ValidateFn<TData, TParentData>- An optional property that takes a
ValidateFnwhich is a generic ofTDataandTParentData. Ifvalidatoris passed, this may also accept a property from the respective validator (IE:z.string().min(1)ifzodAdapteris passed)
- An optional property that takes a
onChangeAsync?: ValidateAsyncFn<TData, TParentData>- An optional property similar to
onChangebut async validation. Ifvalidatoris passed, this may also accept a property from the respective validator (IE:z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' })ifzodAdapteris passed)
- An optional property similar to
onChangeAsyncDebounceMs?: number- An optional number to represent how long the
onChangeAsyncshould wait before running - If set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds
- An optional number to represent how long the
onBlur?: ValidateFn<TData, TParentData>- An optional function, when that run when subscribing to blur event of input. If
validatoris passed, this may also accept a property from the respective validator (IE:z.string().min(1)ifzodAdapteris passed)
- An optional function, when that run when subscribing to blur event of input. If
onBlurAsync?: ValidateAsyncFn<TData, TParentData>- An optional function that takes a
ValidateFnwhich is a generic ofTDataandTParentDatahappens async. Ifvalidatoris passed, this may also accept a property from the respective validator (IE:z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' })ifzodAdapteris passed)
onBlurAsyncDebounceMs?: number- An optional number to represent how long the
onBlurAsyncDebounceMsshould wait before running - If set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds
- An optional function that takes a
onSubmit?: ValidateFn<TData, TParentData>- An optional function, when that run when subscribing to submit event of input. If
validatoris passed, this may also accept a property from the respective validator (IE:z.string().min(1)ifzodAdapteris passed)
- An optional function, when that run when subscribing to submit event of input. If
onSubmitAsync?: ValidateAsyncFn<TData, TParentData>- An optional function that takes a
ValidateFnwhich is a generic ofTDataandTParentDatahappens async. Ifvalidatoris passed, this may also accept a property from the respective validator (IE:z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' })ifzodAdapteris passed)
onSubmitAsyncDebounceMs?: number- An optional number to represent how long the
onSubmitAsyncDebounceMsshould wait before running - If set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds
- An optional function that takes a
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 theformproperty 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
validateOnproperty set as required.
- The field options with the
Methods#
constructor(opts: FieldApiOptions<TData, TParentData>)- Initializes a new
FieldApiinstance.
- Initializes a new
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
changevalidator.
- Sets the field value and run the
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.