Skip to content

FormSubmitContext

Defined in: FormApi/formSubmit.public.ts:210

Gives the form's onSubmit callback its submitted values, validator outputs, form API, and error helpers after submission validation succeeds.

Extends

Type Parameters

TFormData

TFormData

Library-managed. Do not specify explicitly.

TValidatorOutputs

TValidatorOutputs extends readonly unknown[]

Library-managed. Do not specify explicitly.

Properties

createErrorMap

ts
createErrorMap: CreateSubmitErrorMapFn<TFormData>;

Defined in: FormApi/formSubmit.public.ts:172

Builds a mutable map of submission errors from optional initial errors.

  • If you already have errors ready to return, use createValidationError.
  • If you want to return Standard Schema errors, use parseIssues.
  • Add errors with addFormError and addFieldError.
  • Return the map from onSubmit to report its errors.
  • The form entry targets the submitting form or group.
  • Field paths are relative to the submitting form or group.
  • An empty map indicates success.

Example

ts
formOptions({
  defaultValues: { name: '' },
  onSubmit: async ({ value, createErrorMap }) => {
    const errors = createErrorMap()
    if (await nameIsTaken(value.name)) {
      errors.addFieldError('name', 'Name is already taken')
    }
    return errors
  },
})

Inherited from

BaseSubmitContext.createErrorMap


createValidationError

ts
createValidationError: CreateValidationErrorFn<TFormData>;

Defined in: FormApi/formSubmit.public.ts:144

Wraps existing errors so onSubmit can return them as validation errors. Calling this helper alone does not update validation state.

Accepts error messages, issue objects, arrays of errors, or an error map. For a group, field paths in an error map are relative to the group.

  • If you want to build or edit errors by field, use createErrorMap.
  • If you want to return Standard Schema errors, use parseIssues.

Example

ts
formOptions({
  defaultValues: { name: '' },
  onSubmit: async ({ value, createValidationError }) => {
    if (await nameIsTaken(value.name)) {
      return createValidationError('Name is already taken')
    }
    await saveProfile(value)
  },
})

Inherited from

BaseSubmitContext.createValidationError


formApi

ts
formApi: FormApi<TFormData, ScopedErrorTypes<never, never>>;

Defined in: FormApi/formSubmit.public.ts:229

The form handling this submission.

Remarks

Important: A user may edit fields during submission. value and formApi.state.values may not be equal.


parseIssues

ts
parseIssues: ParseSubmitIssuesFn<TFormData>;

Defined in: FormApi/formSubmit.public.ts:200

Converts Standard Schema issues into a mutable error map to return from onSubmit.

  • If you want to return your own error messages or an existing error map, use createValidationError.
  • If you want to build or edit errors by field, use createErrorMap.
  • Uses the captured submission values to resolve field paths.
  • Issues without a field path become form or group errors.
  • For a group, issue paths are relative to the group.
  • Return the map to report its errors. An empty map indicates success.

Example

ts
formOptions({
  defaultValues: { name: '' },
  onSubmit: async ({ value, parseIssues }) => {
    const result = parseSchema(mySchema, value)
    if (!result.success) {
      return parseIssues(result.issues)
    }
    await saveProfile(result.data)
  },
})

Inherited from

BaseSubmitContext.parseIssues


signal

ts
signal: AbortSignal;

Defined in: FormApi/formSubmit.public.ts:118

Signals when this submission attempt is invalidated.

  • A newer submission of the same form or group aborts the signal.
  • A reset or unmount also aborts it.
  • Field edits during a submission do not abort the signal.
  • The same signal is passed to this attempt's onSubmitInvalid, if it runs.

Remarks

Important: Aborting prevents submission results from updating form or group state. Callbacks already started are still awaited, and their exceptions retain normal handling. Use the signal to stop external work that supports cancellation.

Inherited from

BaseSubmitContext.signal


validatorOutputs

ts
validatorOutputs: TValidatorOutputs;

Defined in: FormApi/formSubmit.public.ts:257

Outputs from this submission's form validators, in validators array order.

  • Standard Schemas provide their parsed output data automatically.
  • Callback validators provide the payload returned with createOutput.
  • Skipped validators contribute undefined.
  • Outputs from earlier change, blur, or mount validation are not reused.

Example

ts
formOptions({
  defaultValues: { name: '' },
  validators: [
    {
      triggers: [],
      run: ({ createOutput, value }) =>
        createOutput({ displayName: value.name.trim() }),
    },
    { triggers: [], run: mySchema },
  ],
  onSubmit: async ({ validatorOutputs }) => {
    const [customData, schemaOutput] = validatorOutputs
    await saveProfile(customData.displayName, schemaOutput)
  },
})

value

ts
value: TFormData;

Defined in: FormApi/formSubmit.public.ts:221

The form values captured when this submission started, without schema transformations applied.

Field edits made while submission is pending do not replace these values. Read transformed validator results from validatorOutputs.