TanStack
Form creation

FormOptions

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.

Type Parameters

TFormData

TFormData

Library-managed. Do not specify explicitly.

TValidatorConfig

TValidatorConfig extends unknown[]

Library-managed. Do not specify explicitly.

TValidators

TValidators

Library-managed. Do not specify explicitly.

TSubmitReturn

TSubmitReturn

TPayload

TPayload

Library-managed. Do not specify explicitly.

Properties

[formOptionsTypePayloadSymbol]?

ts
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

ts
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.

Example

ts
formOptions({
  defaultValues: {
    name: '',
    age: 0,
    interests: [] as string[],
  },
  onSubmit: ({ value }) => {
     // Use values
  },
})

errorVisibility?

ts
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.

Example

ts
formOptions({
  defaultValues: { name: '' },
  errorVisibility: ({ state, fieldState }) =>
    fieldState.meta.isBlurred || state.submissionAttempts > 0,
})

formId?

ts
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.


listeners?

ts
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.

Example

ts
formOptions({
  defaultValues: { name: '' },
  listeners: [
    {
      triggers: ['change'],
      triggerDebounceMs: 200,
      run: ({ value }) => {
        localStorage.setItem('profile-draft', JSON.stringify(value))
      },
    },
  ],
})

onSubmit?

ts
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.

Example

ts
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' })
  },
})

onSubmitInvalid?

ts
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.

Example

ts
formOptions({
  defaultValues: { name: '' },
  onSubmitInvalid: () => {
    // Focus on first invalid input
    document.querySelector<HTMLElement>('[aria-invalid="true"]')?.focus()
  },
})

serverState?

ts
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.


validators?

ts
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.

Example

ts
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;
      },
    },
  ],
})