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

FieldApi.md

492 lines9.8 KB

Class: FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>

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

• TName extends DeepKeys<TParentData>

• TFieldValidator extends Validator<DeepValue<TParentData, TName>, unknown> | undefined = undefined

• TFormValidator extends Validator<TParentData, unknown> | undefined = undefined

• TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>

Constructors

new FieldApi()

new FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>(opts): FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>

Initializes a new FieldApi instance.

Parameters

• opts: FieldApiOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>

Returns

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

Defined in

packages/form-core/src/FieldApi.ts:432

Properties

form

form: FormApi<TParentData, TFormValidator>;

A reference to the form API instance.

Defined in

packages/form-core/src/FieldApi.ts:395


name

name: unknown extends TParentData ? string : TParentData extends readonly any[] & IsTuple<TParentData> ? PrefixTupleAccessor<TParentData<TParentData>, AllowedIndexes<TParentData<TParentData>, never>, []> : TParentData extends any[] ? PrefixArrayAccessor<TParentData<TParentData>, [any]> : TParentData extends Date ? never : TParentData extends object ? PrefixObjectAccessor<TParentData<TParentData>, []> : TParentData extends string | number | bigint | boolean ? "" : never;

The field name.

Defined in

packages/form-core/src/FieldApi.ts:405


options

options: FieldApiOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>;

The field options.

Defined in

packages/form-core/src/FieldApi.ts:409


state

state: FieldState<TData>;

The current field state.

Defined in

packages/form-core/src/FieldApi.ts:423


store

store: Store<FieldState<TData>, (cb) => FieldState<TData>>;

The field state store.

Defined in

packages/form-core/src/FieldApi.ts:419

Methods

getInfo()

getInfo(): FieldInfo<TParentData, TFormValidator>

Gets the field information object.

Returns

FieldInfo<TParentData, TFormValidator>

Defined in

packages/form-core/src/FieldApi.ts:642


getMeta()

getMeta(): FieldMeta

Gets the current field metadata.

Returns

FieldMeta

Defined in

packages/form-core/src/FieldApi.ts:621


getValue()

getValue(): TData

Gets the current field value.

Returns

TData

Deprecated

Use field.state.value instead.

Defined in

packages/form-core/src/FieldApi.ts:601


handleBlur()

handleBlur(): void

Handles the blur event.

Returns

void

Defined in

packages/form-core/src/FieldApi.ts:956


handleChange()

handleChange(updater): void

Handles the change event.

Parameters

• updater: Updater<TData>

Returns

void

Defined in

packages/form-core/src/FieldApi.ts:949


insertValue()

insertValue(
   index, 
   value, 
opts?): Promise<void>

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

• opts?: UpdateMetaOptions

Returns

Promise<void>

Defined in

packages/form-core/src/FieldApi.ts:655


mount()

mount(): () => void

Mounts the field instance to the form.

Returns

Function

Returns

void

Defined in

packages/form-core/src/FieldApi.ts:517


moveValue()

moveValue(
   aIndex, 
   bIndex, 
   opts?): void

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

Parameters

• aIndex: number

• bIndex: number

• opts?: UpdateMetaOptions

Returns

void

Defined in

packages/form-core/src/FieldApi.ts:685


pushValue()

pushValue(value, opts?): void

Pushes a new value to the field.

Parameters

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

• opts?: UpdateMetaOptions

Returns

void

Defined in

packages/form-core/src/FieldApi.ts:647


removeValue()

removeValue(index, opts?): Promise<void>

Removes a value at the specified index.

Parameters

• index: number

• opts?: UpdateMetaOptions

Returns

Promise<void>

Defined in

packages/form-core/src/FieldApi.ts:673


replaceValue()

replaceValue(
   index, 
   value, 
opts?): Promise<void>

Replaces a value at the specified index.

Parameters

• index: number

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

• opts?: UpdateMetaOptions

Returns

Promise<void>

Defined in

packages/form-core/src/FieldApi.ts:664


setMeta()

setMeta(updater): void

Sets the field metadata.

Parameters

• updater: Updater<FieldMeta>

Returns

void

Defined in

packages/form-core/src/FieldApi.ts:636


setValue()

setValue(updater, options?): void

Sets the field value and run the change validator.

Parameters

• updater: Updater<TData>

• options?: UpdateMetaOptions

Returns

void

Defined in

packages/form-core/src/FieldApi.ts:608


swapValues()

swapValues(
   aIndex, 
   bIndex, 
   opts?): void

Swaps the values at the specified indices.

Parameters

• aIndex: number

• bIndex: number

• opts?: UpdateMetaOptions

Returns

void

Defined in

packages/form-core/src/FieldApi.ts:679


update()

update(opts): void

Updates the field instance with new options.

Parameters

• opts: FieldApiOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>

Returns

void

Defined in

packages/form-core/src/FieldApi.ts:564


validate()

validate(cause): ValidationError[] | Promise<ValidationError[]>

Validates the field value.

Parameters

• cause: ValidationCause

Returns

ValidationError[] | Promise<ValidationError[]>

Defined in

packages/form-core/src/FieldApi.ts:923