Connect UI controls to field state and handlers
Building a text input, checkbox, or other controlled form control
TanStack · Class
FieldApi
FieldApi manages the state and behavior of one TanStack Form field. Framework hooks or field-creation functions normally create it so it participates in the framework's reactivity model.
How it works
FieldApi is the object-oriented interface for a single TanStack Form field. In normal framework usage, a hook or field-creation function constructs it, and consumers use its state plus event and validation methods to manage the field without manually instantiating the class.
Syntax
class FieldApi<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnDynamic, TFormOnDynamicAsync, TFormOnServer, TPatentSubmitMeta>Parameters
| Name | Type | Description |
|---|---|---|
type parameters | TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnB | Generic field and form type parameters govern the parent data, field name and value, validation callbacks, and form-level callbacks. |
Returns
A FieldApi instance representing the specified field.
Key points
- FieldApi encapsulates operations and state for one form field.
- Framework integrations are the normal way to obtain a field API instance.
- The framework-created instance is connected to the integration's reactivity behavior.
Common mistakes
- Prefer a framework integration such as useField or createField instead of constructing FieldApi yourself.
Example: Managing a field with useField
import { useField } from '@tanstack/react-form'
export function EmailField() {
const field = useField({
name: 'email',
defaultValue: '',
validators: {
onChange: ({ value }) =>
value.includes('@') ? undefined : 'Enter a valid email',
},
})
return (
<label>
Email
<input
value={field.state.value}
onChange={(event) => field.handleChange(event.target.value)}
onBlur={field.handleBlur}
/>
{!field.state.meta.isValid && <span>{field.state.meta.errors.join(', ')}</span>}
</label>
)
}Creates a managed field through the framework hook, then reads its state and forwards input and blur events to the field API.
When to use it
Read validation status and field errors
Displaying validation feedback beside an input
Share field operations across components
Implementing reusable form utilities
Manually construct a field API when direct instantiation is required
Creating a field outside a standard framework helper
Interview questions
QWhat is FieldApi?
FieldApi represents the API for managing one form field. It exposes the field's state and operations used to read values, process changes and blur events, and participate in validation.
Follow-up: How should a framework integration expose it? Use the framework's field hook or creation function so the instance follows that framework's reactivity model.
QHow is a FieldApi instance normally created?
Usually, application code does not call its constructor. A framework hook such as useField or a creation function such as createField creates the instance for the component or field definition.
Follow-up: When would direct construction be reasonable? Only when a manual instance is specifically needed outside the normal framework-managed creation path.
QWhat does a field API manage?
A field has its own state, including its current value, validation status, errors, and other metadata. Consumers access that state through the field API and connect UI events to the API's handlers.
Follow-up: How can generic error-rendering code avoid depending on a concrete field name? Use a suitably generic field API type, while retaining value types when the helper reads or updates values.
Related
useFieldcreateFieldFieldApiOptionsFieldOptionsAnyFieldApiFieldWithValue