Interface: FormApi<TFormData, TFormErrorTypes>#

Defined in: FormApi/FormApi.public.ts:610

Core API for reading and updating state, validating values, and handling submission.

Framework adapters compose this interface with framework-specific helpers.

Extends#

• FormApiFieldMethods<TFormData>.FormApiArrayMethods<TFormData>

Type Parameters#

TFormData#

TFormData

Library-managed. Do not specify explicitly.

TFormErrorTypes#

TFormErrorTypes extends FormErrorTypes

Library-managed. Do not specify explicitly.

Properties#

atom#

atom: ReadonlyAtom<FormState<TFormData, TFormErrorTypes>>;

Defined in: FormApi/FormApi.public.ts:621

Read-only atom containing reactive FormState snapshots.

Subscribe to this atom to observe state changes. For an imperative read, use state.

clearFieldValues#

clearFieldValues: ClearFieldValuesFn<TFormData>;

Defined in: FormApi/FormApiArrayMethods.types.public.ts:378

Removes every element from an array field.

A runtime value that is not an array produces a warning and is left unchanged. By default, the update marks the array field as touched and dirty, notifies change listeners, and runs change validation.

Example#

// items: ['first', 'second']
formApi.clearFieldValues('items')
// items: []

Inherited from#

FormApiArrayMethods.clearFieldValues

defaultValues#

readonly defaultValues: TFormData;

Defined in: FormApi/FormApi.public.ts:625

The current baseline values used by reset() and isDefaultValue.

filterFieldValues#

filterFieldValues: FilterFieldValuesFn<TFormData>;

Defined in: FormApi/FormApiArrayMethods.types.public.ts:414

Keeps the elements that satisfy a predicate.

options.thisArg sets the predicate's this value. A runtime value that is not an array produces a warning and is left unchanged. By default, the update marks the array field as touched and dirty, notifies change listeners, and runs change validation.

Example#

// items: [1, 2, 3, 4]
formApi.filterFieldValues('items', (item) => item % 2 === 0)
// items: [2, 4]

Inherited from#

FormApiArrayMethods.filterFieldValues

formId#

readonly formId: string;

Defined in: FormApi/FormApi.public.ts:632

Stable identifier supplied by FormOptions.formId or generated at creation.

It is preserved across option updates until a new formId is supplied.

getFieldValue#

getFieldValue: GetFieldValueFn<TFormData>;

Defined in: FormApi/FormApiFieldMethods.types.public.ts:114

Reads the current value at a field path.

This is a read-only operation and does not create a FieldApi for the path.

Example#

const name = formApi.getFieldValue('profile.name')

Returns#

The current value at the path, or undefined when the path cannot be resolved at runtime.

Inherited from#

FormApiFieldMethods.getFieldValue

handleSubmit#

handleSubmit: HandleSubmitFn<TFormData>;

Defined in: FormApi/FormApi.public.ts:670

Runs submission validation and submits current values when validation succeeds.

Registered fields are marked touched, field validators run before form validators, and onSubmit is awaited only when validation succeeds. Validation error results and errors returned by onSubmit through createValidationError are stored as error state. onSubmitInvalid is awaited after a failed attempt.

Calls made while an attempt is in progress return the same promise instead of starting another attempt.

The returned promise resolves to the error results produced by field and form validation, plus any validation error returned by onSubmit through createValidationError. The array is empty if none are produced.

insertFieldValue#

insertFieldValue: InsertFieldValueFn<TFormData>;

Defined in: FormApi/FormApiArrayMethods.types.public.ts:362

Inserts an element at an index in an array field.

The index must be between 0 and array.length; passing array.length appends the element. An out-of-range index or a runtime value that is not an array produces a warning and leaves the value unchanged.

By default, the update marks the array field as touched and dirty, notifies change listeners, and runs change validation.

Example#

// items: ['first', 'second']
formApi.insertFieldValue('items', 1, 'new item')
// items: ['first', 'new item', 'second']

Inherited from#

FormApiArrayMethods.insertFieldValue

moveFieldValue#

moveFieldValue: MoveFieldValueFn<TFormData>;

Defined in: FormApi/FormApiArrayMethods.types.public.ts:327

Moves an element to another index in an array field.

Both indices must be between 0 and array.length - 1. Passing equal indices does nothing. Out-of-range indices or a runtime value that is not an array produce a warning and leave the value unchanged.

By default, the update marks the array field as touched and dirty, notifies change listeners, and runs change validation.

Example#

// items: ['first', 'second', 'third']
formApi.moveFieldValue('items', 0, 2)
// items: ['second', 'third', 'first']

Inherited from#

FormApiArrayMethods.moveFieldValue

pushFieldValue#

pushFieldValue: PushFieldValueFn<TFormData>;

Defined in: FormApi/FormApiArrayMethods.types.public.ts:343

Appends an element to an array field.

A runtime value that is not an array produces a warning and is left unchanged. By default, the update marks the array field as touched and dirty, notifies change listeners, and runs change validation.

Example#

// items: ['first', 'second']
formApi.pushFieldValue('items', 'new item')
// items: ['first', 'second', 'new item']

Inherited from#

FormApiArrayMethods.pushFieldValue

removeFieldValue#

removeFieldValue: RemoveFieldValueFn<TFormData>;

Defined in: FormApi/FormApiArrayMethods.types.public.ts:397

Removes an element from an array field.

The index must be between 0 and array.length - 1. An out-of-range index or a runtime value that is not an array produces a warning and leaves the value unchanged.

By default, the update marks the array field as touched and dirty, notifies change listeners, and runs change validation.

Example#

// items: ['first', 'second', 'third']
formApi.removeFieldValue('items', 1)
// items: ['first', 'third']

Inherited from#

FormApiArrayMethods.removeFieldValue

reset#

reset: ResetFn<TFormData>;

Defined in: FormApi/FormApi.public.ts:685

Reset form values, metadata, validation state, and mounted fields.

reset() restores the current defaultValues.

reset(values) sets the current values and also updates defaultValues to those values. This can apply expected values immediately while fresh data is fetched from the backend.

Results from validation or submission work pending at reset are discarded.

Pass { updateDefaultValues: false } as the options argument to preserve the existing defaultValues when supplying values.

resetField#

resetField: ResetFieldFn<TFormData>;

Defined in: FormApi/FormApiFieldMethods.types.public.ts:131

Restores a field path from defaultValues and resets state for its field subtree.

Existing FieldApi instances at or below the path remain mounted. Form-wide dirty history remains unchanged; use formApi.reset() to clear it.

Example#

formApi.setFieldValue('profile.name', 'Grace')
formApi.resetField('profile.name')
// `profile.name` is restored from `defaultValues`.

Inherited from#

FormApiFieldMethods.resetField

setFieldValue#

setFieldValue: SetFieldValueFn<TFormData>;

Defined in: FormApi/FormApiFieldMethods.types.public.ts:99

Updates the current value at a field path.

The next value may be supplied directly or calculated from the current value. By default, the update marks the field as touched and dirty, notifies change listeners, and runs change validation.

Example#

formApi.setFieldValue('profile.name', 'Ada')
formApi.setFieldValue('visitCount', (count) => count + 1)

Inherited from#

FormApiFieldMethods.setFieldValue

state#

readonly state: FormState<TFormData, TFormErrorTypes>;

Defined in: FormApi/FormApi.public.ts:623

Current values, validation status, and submission metadata.

swapFieldValues#

swapFieldValues: SwapFieldValuesFn<TFormData>;

Defined in: FormApi/FormApiArrayMethods.types.public.ts:308

Swaps two elements in an array field.

Both indices must be between 0 and array.length - 1. Passing equal indices does nothing. Out-of-range indices or a runtime value that is not an array produce a warning and leave the value unchanged.

By default, the update marks the array field as touched and dirty, notifies change listeners, and runs change validation.

Example#

// items: ['first', 'second', 'third']
formApi.swapFieldValues('items', 0, 2)
// items: ['third', 'second', 'first']

Inherited from#

FormApiArrayMethods.swapFieldValues

validate#

validate: (signal) => Promise<FormValidationError<TFormData>[]>;

Defined in: FormApi/FormApi.public.ts:649

Runs form-level validators enabled for the specified 'change' or 'blur' trigger.

Prefer configured validator triggers for change and blur validation, and use handleSubmit() for submission validation. Calling this method directly is rarely necessary.

Results update form-level errors and any errors routed to fields. Field-level validators are not run by this method.

Parameters#

signal#

ConfigurableValidationTrigger

The trigger used to select validators.

Returns#

Promise<FormValidationError<TFormData>[]>

A promise resolving to each error result from the validators that ran. Unlike state.errors, these results are not flattened.