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

FieldApi.md

721 lines18.0 KB

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

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

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

A reference to the form API instance.


name

name: TName;

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

The field 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:1066

The field options.


store

store: ReadonlyStore<FieldState<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:1094

The field state store.


timeoutIds

timeoutIds: object;

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

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(): FieldState<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:1122

The current field state.

Returns

FieldState<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:1636

Clear all values from the array.

Parameters

options?

UpdateMetaOptions

Returns

void


getInfo()

getInfo(): FieldInfo<TParentData>;

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

Gets the field information object.

Returns

FieldInfo<TParentData>


getMeta()

getMeta(): FieldMeta<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:1486

Returns

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


getValue()

getValue(): TData;

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

Gets the current field value.

Returns

TData

Deprecated

Use field.state.value instead.


handleBlur()

handleBlur(): void;

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

Handles the blur event.

Returns

void


handleChange()

handleChange(updater): void;

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

Handles the change event.

Parameters

updater

Updater<TData>

Returns

void


insertValue()

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

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

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

Mounts the field instance to the form.

Returns

A function to unmount the field instance.

(): void;
Returns

void


moveValue()

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

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

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

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

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

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

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

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

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

Sets the field metadata.

Parameters

updater

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

Returns

void


setValue()

setValue(updater, options?): void;

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

Sets the field value and run the change validator.

Parameters

updater

Updater<TData>

options?

UpdateMetaOptions

Returns

void


swapValues()

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

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

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

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

Validates the field value.

Parameters

cause

ValidationCause

opts?
skipFormValidation?

boolean

Returns

unknown[] | Promise<unknown[]>