Class: 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:1701

Handles the blur event.

Returns#

void

handleChange()#

handleChange(updater): void;

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

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:1744

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:1756

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`](../interfaces/StandardSchemaV1Issue.md)[] \| `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:1717

Updates the field's errorMap

Parameters#

errorMap#

ValidationErrorMap\<[`UnwrapFieldValidateOrFn`](../type-aliases/UnwrapFieldValidateOrFn.md)\<`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:1577

Validates the field value.

Parameters#

cause#

ValidationCause

opts?#

skipFormValidation?#

boolean

skipGroupValidation?#

boolean

Returns#

unknown[] | Promise\<`unknown`[]\>

Implementation of#

FieldLikeAPI.validate