# FormApi

Defined in: [FormApi/FormApi.public.ts:212](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L212)

Type-safe methods for reading, updating, and resetting individual field
values.

## Extends

- [`FormApiFieldMethods`](FormApiFieldMethods.md)\<`TFormData`\>.[`FormApiArrayMethods`](FormApiArrayMethods.md)\<`TFormData`\>

## Type Parameters

### TFormData

`TFormData`

Library-managed. Do not specify explicitly.

### TFormError

`TFormError` *extends* [`ScopedErrorTypes`](ScopedErrorTypes.md)

## Properties

### atom

```ts
atom: ReadonlyAtom<FormState<TFormData, TFormError>>;
```

Defined in: [FormApi/FormApi.public.ts:224](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L224)

Read-only atom containing reactive `FormState` snapshots.

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

***

### clearFieldValues

```ts
clearFieldValues: ClearFieldValuesFn<TFormData>;
```

Defined in: [FormApi/FormApiArrayMethods.types.public.ts:410](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L410)

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

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

#### Inherited from

[`FormApiArrayMethods`](FormApiArrayMethods.md).[`clearFieldValues`](FormApiArrayMethods.md#clearfieldvalues)

***

### defaultValues

```ts
readonly defaultValues: TFormData;
```

Defined in: [FormApi/FormApi.public.ts:228](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L228)

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

***

### filterFieldValues

```ts
filterFieldValues: FilterFieldValuesFn<TFormData>;
```

Defined in: [FormApi/FormApiArrayMethods.types.public.ts:465](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L465)

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

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

#### Inherited from

[`FormApiArrayMethods`](FormApiArrayMethods.md).[`filterFieldValues`](FormApiArrayMethods.md#filterfieldvalues)

***

### formId

```ts
readonly formId: string;
```

Defined in: [FormApi/FormApi.public.ts:235](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L235)

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

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

***

### getFieldValue

```ts
getFieldValue: GetFieldValueFn<TFormData>;
```

Defined in: [FormApi/FormApiFieldMethods.types.public.ts:114](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiFieldMethods.types.public.ts#L114)

Reads the current value at a field path.

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

#### Example

```ts
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`](FormApiFieldMethods.md).[`getFieldValue`](FormApiFieldMethods.md#getfieldvalue)

***

### handleSubmit

```ts
handleSubmit: HandleSubmitFn<TFormData>;
```

Defined in: [FormApi/FormApi.public.ts:286](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L286)

Runs submission validation and submits current values when validation
succeeds.

A submission attempt touches all fields.

Field validators run before form validators, and `onSubmit` is awaited only
when validation succeeds.
Validation error results and errors returned by `onSubmit` through
`createValidationError` or `createErrorMap` are stored as error state.
`onSubmitInvalid` is awaited after a failed attempt.
Exceptions reject after submission state is cleaned up, unless
`onSubmitInvalid` calls `preventThrow()`.

Each call starts a fresh attempt with its own promise and captured values,
superseding the form's pending attempt. Later edits do not cancel it or
replace its captured values. Group submissions remain independent.

Supersession, reset, unmount, or server-state replacement aborts the attempt's
callback signal and pending validation. Cancellation before callbacks start
resolves with `[]`. Callbacks already started are still awaited with normal
error handling, while their results cannot update form state. Submission
state tracks only the current attempt.

The returned promise resolves to a flat array of issues and error maps
from field and form validation, plus errors returned by `onSubmit` through
its validation helpers. Strings become issue objects. The array is empty
if no errors are produced.

***

### insertFieldValue

```ts
insertFieldValue: InsertFieldValueFn<TFormData>;
```

Defined in: [FormApi/FormApiArrayMethods.types.public.ts:394](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L394)

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

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

#### Inherited from

[`FormApiArrayMethods`](FormApiArrayMethods.md).[`insertFieldValue`](FormApiArrayMethods.md#insertfieldvalue)

***

### moveFieldValue

```ts
moveFieldValue: MoveFieldValueFn<TFormData>;
```

Defined in: [FormApi/FormApiArrayMethods.types.public.ts:359](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L359)

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

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

#### Inherited from

[`FormApiArrayMethods`](FormApiArrayMethods.md).[`moveFieldValue`](FormApiArrayMethods.md#movefieldvalue)

***

### pushFieldValue

```ts
pushFieldValue: PushFieldValueFn<TFormData>;
```

Defined in: [FormApi/FormApiArrayMethods.types.public.ts:375](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L375)

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

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

#### Inherited from

[`FormApiArrayMethods`](FormApiArrayMethods.md).[`pushFieldValue`](FormApiArrayMethods.md#pushfieldvalue)

***

### removeFieldValue

```ts
removeFieldValue: RemoveFieldValueFn<TFormData>;
```

Defined in: [FormApi/FormApiArrayMethods.types.public.ts:429](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L429)

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

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

#### Inherited from

[`FormApiArrayMethods`](FormApiArrayMethods.md).[`removeFieldValue`](FormApiArrayMethods.md#removefieldvalue)

***

### replaceFieldValue

```ts
replaceFieldValue: ReplaceFieldValueFn<TFormData>;
```

Defined in: [FormApi/FormApiArrayMethods.types.public.ts:448](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L448)

Replaces the element at an index in 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

```ts
// items: ['first', 'second', 'third']
formApi.replaceFieldValue('items', 1, 'new item')
// items: ['first', 'new item', 'third']
```

#### Inherited from

[`FormApiArrayMethods`](FormApiArrayMethods.md).[`replaceFieldValue`](FormApiArrayMethods.md#replacefieldvalue)

***

### reset

```ts
reset: ResetFn<TFormData>;
```

Defined in: [FormApi/FormApi.public.ts:301](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L301)

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

```ts
resetField: ResetFieldFn<TFormData>;
```

Defined in: [FormApi/FormApiFieldMethods.types.public.ts:131](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiFieldMethods.types.public.ts#L131)

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

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

#### Inherited from

[`FormApiFieldMethods`](FormApiFieldMethods.md).[`resetField`](FormApiFieldMethods.md#resetfield)

***

### setFieldValue

```ts
setFieldValue: SetFieldValueFn<TFormData>;
```

Defined in: [FormApi/FormApiFieldMethods.types.public.ts:99](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiFieldMethods.types.public.ts#L99)

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

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

#### Inherited from

[`FormApiFieldMethods`](FormApiFieldMethods.md).[`setFieldValue`](FormApiFieldMethods.md#setfieldvalue)

***

### state

```ts
readonly state: FormState<TFormData, TFormError>;
```

Defined in: [FormApi/FormApi.public.ts:226](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L226)

Current values, validation status, and submission metadata.

***

### swapFieldValues

```ts
swapFieldValues: SwapFieldValuesFn<TFormData>;
```

Defined in: [FormApi/FormApiArrayMethods.types.public.ts:340](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L340)

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

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

#### Inherited from

[`FormApiArrayMethods`](FormApiArrayMethods.md).[`swapFieldValues`](FormApiArrayMethods.md#swapfieldvalues)

***

### validate

```ts
validate: (signal) => Promise<FormattedValidationError<TFormData>[]>;
```

Defined in: [FormApi/FormApi.public.ts:253](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L253)

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

[`DynamicValidatorTriggers`](../type-aliases/DynamicValidatorTriggers.md)

The trigger used to select validators.

#### Returns

`Promise`\<[`FormattedValidationError`](../type-aliases/FormattedValidationError.md)\<`TFormData`\>[]\>

A promise resolving to a flat array of issues and error maps from
the validators that ran. Strings become issue objects; error maps retain
their field paths.
