Defined in: FormApi/formOptions.public.ts:53
Configures a form's initial values, validation, listeners, and submission.
Pass these options to a framework adapter's form creation API. Use formOptions when defining reusable options so values and callbacks retain their inferred types.
TFormData
Library-managed. Do not specify explicitly.
TValidatorConfig extends unknown[]
Library-managed. Do not specify explicitly.
TValidators
Library-managed. Do not specify explicitly.
TSubmitReturn
TPayload
Library-managed. Do not specify explicitly.
readonly optional [formOptionsTypePayloadSymbol]?: TPayload;Defined in: FormApi/formOptions.public.ts:65
INTERNAL USE ONLY
A custom type payload that adapters need for things like form composition. Not a real runtime value.
defaultValues: TFormData;Defined in: FormApi/formOptions.public.ts:92
The values your form starts with.
reset() restores these values, and isDefaultValue checks whether the current values match them.
You can supply a new object whenever options are updated. Defaults are compared deeply, so recreating equal objects and arrays leaves them unchanged.
When defaults change, untouched top-level fields receive the new values. Values under touched top-level fields are preserved.
formOptions({
defaultValues: {
name: '',
age: 0,
interests: [] as string[],
},
onSubmit: ({ value }) => {
// Use values
},
})optional errorVisibility?: ErrorVisibilityFn<NoInfer<TFormData>>;Defined in: FormApi/formOptions.public.ts:117
Controls when fields expose validation errors. Return true to show errors or false to hide them. This only affects their visibility and does not change the form's validity.
Applies to every field unless the field supplies its own errorVisibility. When no errorVisibility is provided, errors are always exposed.
formOptions({
defaultValues: { name: '' },
errorVisibility: ({ state, fieldState }) =>
fieldState.meta.isBlurred || state.submissionAttempts > 0,
})optional formId?: string;Defined in: FormApi/formOptions.public.ts:99
Identifies this form through formApi.formId.
When omitted, an identifier is generated when the form is created and preserved across option updates. Supplying a new formId replaces it.
optional listeners?: FormListeners<NoInfer<TFormData>, NoInfer<GetFormErrorTypes<TValidators, unknown>>>;Defined in: FormApi/formOptions.public.ts:176
Callbacks for change, blur, submit, mount, and reset events.
Use listeners for work that does not depend on other listeners. Return values are ignored, and returned promises are not awaited.
formOptions({
defaultValues: { name: '' },
listeners: [
{
triggers: ['change'],
triggerDebounceMs: 200,
run: ({ value }) => {
localStorage.setItem('profile-draft', JSON.stringify(value))
},
},
],
})optional onSubmit?: FormOptionsOnSubmitFn<NoInfer<TFormData>, NoInfer<TryGetValidatorOutputs<TValidators>>, TSubmitReturn>;Defined in: FormApi/formOptions.public.ts:212
Handles submission after field and form submission validation succeeds. A returned promise is awaited before submission finishes.
The context provides form values, validator outputs, the form instance, and helpers for reporting submission errors.
You can also report form and field errors discovered during submission, such as validation errors returned by the server.
formOptions({
defaultValues: { name: '' },
onSubmit: async ({ value, createErrorMap }) => {
const response = await createProfile();
if (response.error === 'username_taken') {
return createErrorMap({ fields: { name: 'This name is taken' }})
}
return redirect({ to: '/my-profile' })
},
})optional onSubmitInvalid?: FormOptionsOnSubmitInvalidFn<NoInfer<TFormData>, NoInfer<GetFormErrorTypes<TValidators, TSubmitReturn>>>;Defined in: FormApi/formOptions.public.ts:235
Handles a failed submission, including submission validation failures, errors returned from onSubmit, and exceptions during validation or onSubmit.
A returned promise is awaited before submission finishes.
formOptions({
defaultValues: { name: '' },
onSubmitInvalid: () => {
// Focus on first invalid input
document.querySelector<HTMLElement>('[aria-invalid="true"]')?.focus()
},
})optional serverState?:
| NoInfer<ServerFormState<TFormData>>
| null;Defined in: FormApi/formOptions.public.ts:187
Used by server-side rendering (SSR) integrations to restore form state from the server on the client.
optional validators?: TValidators & FormOptionsValidators<NoInfer<TFormData>, TValidatorConfig, NoInfer<TValidators>>;Defined in: FormApi/formOptions.public.ts:148
An ordered array of validators for the complete form values.
By default, validators run only on submission. See triggers and skipOnSubmit to change when they run.
Submission outputs follow the same array order.
Make sure to not dynamically change the array length.
formOptions({
defaultValues: { name: '' },
validators: [
{
triggers: ['change'],
run: ({ value, createErrorMap }) => {
// Form validators can set errors on fields
const map = createErrorMap();
if (!value.name.trim()) {
map.fields.name = 'Enter a name';
}
return map;
},
},
],
})