Core or custom integrations
Build a form without a UI framework
TanStack · Class
FormApi
FormApi is TanStack Form’s core class for managing form state, validation, and submission. Framework adapters usually create it through hooks or factory functions, but it can be constructed directly when needed.
How it works
FormApi is the core class that owns form state and coordinates interactions such as value updates, validation, and submission. Framework adapters normally create it for you; instantiate it directly when you need a framework-independent form instance.
Syntax
new FormApi(options)Parameters
| Name | Type | Description |
|---|---|---|
options | FormOptions<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta> | Options used to configure the new form instance, including its state, validation, and submission behavior. |
Returns
A configured FormApi instance.
Key points
- FormApi is a class rather than merely a framework hook or standalone helper.
- Its central role is coordinating form-state logic and interactions.
- The API covers state access and mutation, validation, and submission workflows.
- Framework integrations generally create the instance through useForm or createForm.
- The constructor accepts form options used to configure the instance.
Common mistakes
- Prefer a framework hook or factory such as useForm or createForm unless direct construction is required.
- The core class does not itself provide framework-specific reactivity or rendering helpers.
Example: Create and submit a core form
import { FormApi } from '@tanstack/form-core'
const form = new FormApi({
defaultValues: { email: '' },
onSubmit: async ({ value }) => {
console.log(value.email)
},
})
form.mount()
form.setFieldValue('email', 'dev@example.com')
await form.handleSubmit()
form.dispose()Creates a core form, updates a field, submits the current values, and disposes the instance.
When to use it
Framework-backed forms
Use a framework adapter that creates the underlying instance
Reusable form infrastructure
Own form state, validation, and submission in a custom abstraction
Interview questions
QWhat responsibility does FormApi have?
FormApi is the core form class responsible for form-state logic and interactions. It supports reading and updating state, validation, and submission, while framework adapters add framework-specific behavior.
Follow-up: Why should an application usually avoid constructing it directly? Framework hooks or factory functions create an instance integrated with the framework's reactivity model.
QHow is a FormApi instance created?
Construct it with form options by calling the FormApi constructor. The options configure the instance, including the initial form behavior and submission handling.
Follow-up: When would manual construction be appropriate? Use it when a framework-independent or otherwise custom FormApi instance is needed.
QHow does FormApi relate to framework adapters?
FormApi is framework-agnostic core functionality. React or other adapters compose it with framework-specific helpers rather than changing the core form-state responsibilities.
Follow-up: What does an adapter add? It supplies the framework integration needed for reactive updates and framework-oriented APIs.
Related
FormOptionsReactFormApiReactFormExtendedApiAnyFormApiFormValidators