Form state management
Build a typed React form with controlled fields and centralized state.
TanStack · Hook
useForm
useForm is a React hook that creates a TanStack Form instance. The returned API manages form state, submission, and fields.
How it works
In React, useForm accepts optional form options and returns an extended FormApi instance. The instance manages form state, submission, and field interaction; fields are exposed through the returned form object and can be connected to inputs with field state and handlers.
Syntax
function useForm<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>(opts?): ReactFormExtendedApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>;Parameters
| Name | Type | Description |
|---|---|---|
opts | FormOptions<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta> | Optional form configuration, including initial values, submission behavior, and validation-related options. |
Returns
ReactFormExtendedApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>
Key points
- useForm returns an extended FormApi object rather than a plain state value.
- The returned API is the central interface for operating on the form.
- The hook covers state management, submission, and field interaction in one instance.
Example: Basic React form
import { useForm } from '@tanstack/react-form'
export default function ProfileForm() {
const form = useForm({
defaultValues: { name: '' },
onSubmit: async ({ value }) => {
console.log(value.name)
},
})
return (
<form onSubmit={(event) => {
event.preventDefault()
form.handleSubmit()
}}>
<form.Field name="name">
{(field) => (
<input
value={field.state.value}
onChange={(event) => field.handleChange(event.target.value)}
/>
)}
</form.Field>
<button type="submit">Save</button>
</form>
)
}Creates a typed form instance with initial values and an asynchronous submit handler, then binds a field to an input.
When to use it
Submission handling
Run application logic when the user submits form values.
Field integration
Connect text inputs, checkboxes, and other controls to form state.
Validation
Apply synchronous or asynchronous rules to user-entered values.
Interview questions
QWhat does useForm return and what problem does it solve?
useForm is a custom React Hook that returns an extended FormApi instance. That instance centralizes form-state management, submission handling, and interaction with fields.
Follow-up: How can configuration be shared across forms? Use formOptions to define reusable options, then spread those options into useForm while supplying form-specific behavior when needed.
QHow is a basic submission configured?
The hook accepts an options object, commonly containing defaultValues and onSubmit. The submit callback receives the current form value, allowing application code to process the submitted data.
Follow-up: How would you prevent a native page reload? Handle the form element's submit event, call preventDefault, and invoke the form instance's handleSubmit method.
QHow are individual fields connected to controls?
A field is created through the form instance's Field component. Its name identifies a value in the form data, while field state and handlers connect that value to a UI control.
Follow-up: Where does validation belong? Pass synchronous or asynchronous validator functions through a field's validators option, according to the validation event being configured.
Related
FormApiFormOptionsReactFormExtendedApiformOptionsField