FieldApi

Defined in: packages/form-core/src/FieldApi.ts:520

A class representing the API for managing a form field.

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 uses your framework's reactivity model. However, if you need to create a new instance manually, you can do so by calling the new FieldApi constructor.

Type Parameters#

TParentData#

TParentData

TName#

TName extends DeepKeys<TParentData>

TData#

TData extends DeepValue<TParentData, TName>

TOnMount#

TOnMount extends undefined | FieldValidateOrFn<TParentData, TName, TData>

TOnChange#

TOnChange extends undefined | FieldValidateOrFn<TParentData, TName, TData>

TOnChangeAsync#

TOnChangeAsync extends undefined | FieldAsyncValidateOrFn<TParentData, TName, TData>

TOnBlur#

TOnBlur extends undefined | FieldValidateOrFn<TParentData, TName, TData>

TOnBlurAsync#

TOnBlurAsync extends undefined | FieldAsyncValidateOrFn<TParentData, TName, TData>

TOnSubmit#

TOnSubmit extends undefined | FieldValidateOrFn<TParentData, TName, TData>

TOnSubmitAsync#

TOnSubmitAsync extends undefined | FieldAsyncValidateOrFn<TParentData, TName, TData>

TOnDynamic#

TOnDynamic extends undefined | FieldValidateOrFn<TParentData, TName, TData>

TOnDynamicAsync#

TOnDynamicAsync extends undefined | FieldAsyncValidateOrFn<TParentData, TName, TData>

TFormOnMount#

TFormOnMount extends undefined | FormValidateOrFn<TParentData>

TFormOnChange#

TFormOnChange extends undefined | FormValidateOrFn<TParentData>

TFormOnChangeAsync#

TFormOnChangeAsync extends undefined | FormAsyncValidateOrFn<TParentData>

TFormOnBlur#

TFormOnBlur extends undefined | FormValidateOrFn<TParentData>

TFormOnBlurAsync#

TFormOnBlurAsync extends undefined | FormAsyncValidateOrFn<TParentData>

TFormOnSubmit#

TFormOnSubmit extends undefined | FormValidateOrFn<TParentData>

TFormOnSubmitAsync#

TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TParentData>

TFormOnDynamic#

TFormOnDynamic extends undefined | FormValidateOrFn<TParentData>

TFormOnDynamicAsync#

TFormOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TParentData>

TFormOnServer#

TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>

TParentSubmitMeta#

TParentSubmitMeta

Constructors#

Constructor#

new FieldApi<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync, TFormOnServer, TParentSubmitMeta>(opts): FieldApi<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync, TFormOnServer, TParentSubmitMeta>;

Defined in: packages/form-core/src/FieldApi.ts:712

Initializes a new FieldApi instance.

Parameters#

opts#

FieldApiOptions<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync, TFormOnServer, TParentSubmitMeta>

Returns#

FieldApi<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync, TFormOnServer, TParentSubmitMeta>

Properties#

form#

form: FormApi<TParentData, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync, TFormOnServer, TParentSubmitMeta>;

Defined in: packages/form-core/src/FieldApi.ts:612

A reference to the form API instance.

Implementation of#

FieldLikeAPI.form

name#

name: TName;

Defined in: packages/form-core/src/FieldApi.ts:640

The field name.

Implementation of#

FieldLikeAPI.name

options#

options: FieldApiOptions<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync, TFormOnServer, TParentSubmitMeta>;

Defined in: packages/form-core/src/FieldApi.ts:644

The field options.

Implementation of#

FieldLikeAPI.options

store#

store: ReadonlyStore<FieldLikeState<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync>>;

Defined in: packages/form-core/src/FieldApi.ts:672

The field state store.

Implementation of#

FieldLikeAPI.store

timeoutIds#

timeoutIds: object;

Defined in: packages/form-core/src/FieldApi.ts:703

formListeners#

formListeners: Record<ListenerCause, ReturnType<typeof setTimeout> | null>;

listeners#

listeners: Record<ListenerCause, ReturnType<typeof setTimeout> | null>;

validations#

validations: Record<ValidationCause, ReturnType<typeof setTimeout> | null>;

Accessors#

state#

Get Signature#

get state(): FieldLikeState<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync>;

Defined in: packages/form-core/src/FieldApi.ts:700

The current field state.

Returns#

FieldLikeState<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync>

Methods#

clearValues()#

clearValues(options?): void;

Defined in: packages/form-core/src/FieldApi.ts:1214

Clear all values from the array.

Parameters#

options?#

UpdateMetaOptions

Returns#

void

getInfo()#

getInfo(): FieldInfo<TParentData>;

Defined in: packages/form-core/src/FieldApi.ts:1100

Gets the field information object.

Returns#

FieldInfo<TParentData>

Implementation of#

FieldLikeAPI.getInfo

getMeta()#

getMeta(): FieldLikeMeta<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync>;

Defined in: packages/form-core/src/FieldApi.ts:1064

Returns#

FieldLikeMeta<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync>

Implementation of#

FieldLikeAPI.getMeta

getValue()#

getValue(): TData;

Defined in: packages/form-core/src/FieldApi.ts:1041

Gets the current field value.

Returns#

TData

Deprecated#

Use field.state.value instead.

handleBlur()#

handleBlur(): void;

Defined in: packages/form-core/src/FieldApi.ts:1739

Handles the blur event.

Returns#

void

handleChange()#

handleChange(updater): void;

Defined in: packages/form-core/src/FieldApi.ts:1732

Handles the change event.

Parameters#

updater#

Updater<TData>

Returns#

void

insertValue()#

insertValue(
   index, 
   value, 
   options?): void;

Defined in: packages/form-core/src/FieldApi.ts:1123

Inserts a value at the specified index, shifting the subsequent values to the right.

Parameters#

index#

number

value#

TData extends any[] ? TData<TData>[number] : never

options?#

UpdateMetaOptions

Returns#

void

mount()#

mount(): () => void;

Defined in: packages/form-core/src/FieldApi.ts:859

Mounts the field instance to the form.

Returns#

A function to unmount the field instance.

(): void;

Returns#

void

Implementation of#

FieldLikeAPI.mount

moveValue()#

moveValue(
   aIndex, 
   bIndex, 
   options?): void;

Defined in: packages/form-core/src/FieldApi.ts:1198

Moves the value at the first specified index to the second specified index.

Parameters#

aIndex#

number

bIndex#

number

options?#

UpdateMetaOptions

Returns#

void

parseValueWithSchema()#

parseValueWithSchema(schema): 
  | StandardSchemaV1Issue[]
  | undefined;

Defined in: packages/form-core/src/FieldApi.ts:1782

Parses the field's value with the given schema and returns issues (if any). This method does NOT set any internal errors.

Parameters#

schema#

StandardSchemaV1<TData, unknown>

The standard schema to parse this field's value with.

Returns#

| StandardSchemaV1Issue[] | undefined

parseValueWithSchemaAsync()#

parseValueWithSchemaAsync(schema): Promise<
  | StandardSchemaV1Issue[]
| undefined>;

Defined in: packages/form-core/src/FieldApi.ts:1794

Parses the field's value with the given schema and returns issues (if any). This method does NOT set any internal errors.

Parameters#

schema#

StandardSchemaV1<TData, unknown>

The standard schema to parse this field's value with.

Returns#

Promise< | StandardSchemaV1Issue[] | undefined>

pushValue()#

pushValue(value, options?): void;

Defined in: packages/form-core/src/FieldApi.ts:1105

Pushes a new value to the field.

Parameters#

value#

TData extends any[] ? TData<TData>[number] : never

options?#

UpdateMetaOptions

Returns#

void

removeValue()#

removeValue(index, options?): void;

Defined in: packages/form-core/src/FieldApi.ts:1163

Removes a value at the specified index.

Parameters#

index#

number

options?#

UpdateMetaOptions

Returns#

void

replaceValue()#

replaceValue(
   index, 
   value, 
   options?): void;

Defined in: packages/form-core/src/FieldApi.ts:1143

Replaces a value at the specified index.

Parameters#

index#

number

value#

TData extends any[] ? TData<TData>[number] : never

options?#

UpdateMetaOptions

Returns#

void

setErrorMap()#

setErrorMap(errorMap): void;

Defined in: packages/form-core/src/FieldApi.ts:1755

Updates the field's errorMap

Parameters#

errorMap#

ValidationErrorMap<UnwrapFieldValidateOrFn<TName, TOnMount, TFormOnMount>, UnwrapFieldValidateOrFn<TName, TOnChange, TFormOnChange>, UnwrapFieldAsyncValidateOrFn<TName, TOnChangeAsync, TFormOnChangeAsync>, UnwrapFieldValidateOrFn<TName, TOnBlur, TFormOnBlur>, UnwrapFieldAsyncValidateOrFn<TName, TOnBlurAsync, TFormOnBlurAsync>, UnwrapFieldValidateOrFn<TName, TOnSubmit, TFormOnSubmit>, UnwrapFieldAsyncValidateOrFn<TName, TOnSubmitAsync, TFormOnSubmitAsync>, UnwrapFieldValidateOrFn<TName, TOnDynamic, TFormOnDynamic>, UnwrapFieldAsyncValidateOrFn<TName, TOnDynamicAsync, TFormOnDynamicAsync>>

Returns#

void

setMeta()#

setMeta(updater): void;

Defined in: packages/form-core/src/FieldApi.ts:1069

Sets the field metadata.

Parameters#

updater#

Updater<FieldLikeMetaBase<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync>>

Returns#

void

Implementation of#

FieldLikeAPI.setMeta

setValue()#

setValue(updater, options?): void;

Defined in: packages/form-core/src/FieldApi.ts:1048

Sets the field value and run the change validator.

Parameters#

updater#

Updater<TData>

options?#

UpdateMetaOptions

Returns#

void

Implementation of#

FieldLikeAPI.setValue

swapValues()#

swapValues(
   aIndex, 
   bIndex, 
   options?): void;

Defined in: packages/form-core/src/FieldApi.ts:1178

Swaps the values at the specified indices.

Parameters#

aIndex#

number

bIndex#

number

options?#

UpdateMetaOptions

Returns#

void

update()#

update(opts): void;

Defined in: packages/form-core/src/FieldApi.ts:990

Updates the field instance with new options.

Parameters#

opts#

FieldApiOptions<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync, TFormOnServer, TParentSubmitMeta>

Returns#

void

validate()#

validate(cause, opts?): unknown[] | Promise<unknown[]>;

Defined in: packages/form-core/src/FieldApi.ts:1615

Validates the field value.

Parameters#

cause#

ValidationCause

opts?#

skipFormValidation?#

boolean

skipGroupValidation?#

boolean

Returns#

unknown[] | Promise<unknown[]>

Implementation of#

FieldLikeAPI.validate