Validation and submission

Texaryn validates form data through the schema adapter. The runtime decides when validation runs, which errors are visible, and when to call onSubmit. Start with the React setup or your framework binding before using this guide.

Validation

Validation timing is configured per field through the validationTrigger hint:

• 'blur' runs when the field loses focus.
• 'change' runs as the user types, with debounce.
• 'submit' runs only on submission.

When a matching blur or change occurs, Texaryn validates the full form snapshot and distributes the returned errors back to nodes by JSON Pointer. The trigger decides when validation runs, not which part of the form is validated.

Validation triggersOpen in the playground

Three fields, each validated at a different moment. Change validates as you type, blur waits until you leave the field, and submit holds everything until the form is submitted.

• Validate on change
• Validate on blur
• Validate on submit
• minLength

The runtime tracks showErrors per node, so an error appears only once the field has been interacted with or a Submit has been attempted. The prop getters set aria-invalid and link aria-describedby to the error element.

FieldErrors renders inline errors per field and is included in the default widgets. ErrorSummary renders a named group above the form, headed by an h2, listing every visible error with a link to its field, and takes focus once a failed submit settles.

Error associationOpen in the playground

A field that fails validation once touched. The error has to reach assistive technology as part of the field rather than only appearing visually, and the field has to stop being announced as invalid once it is valid again.

• Error association
• Validate on blur
• minLength

Submit

Dispatch a Submit command to start the lifecycle:

form.dispatch({ type: 'Submit' })

It moves through idle, validating, submitting and submitted.

Submit captures the current data as an immutable snapshot, and both validation and onSubmit operate on that snapshot. Edits during validating cancel the attempt. Once onSubmit is running, edits update live data without changing the captured payload.

If validation fails, submission returns to idle and every invalid field shows its errors, touched or not: a Submit attempt opens the display gate that blur and change validation leave closed until the user touches a field. submission.attempts counts the accepted attempts since the last Reset. submission.error is set only when the validator or onSubmit throws or rejects, and the state returns to idle. A fresh Submit clears a previous error. A duplicate Submit while validating or submitting does nothing.

Submission lifecycleOpen in the playground

Submitting validates first and only proceeds when the form is valid. A required field left empty blocks submission and surfaces the error instead.

• Submission lifecycle
• Required and optional fields

Show submission feedback

In React, useForm subscribes to submission state. Disable the button while an attempt is pending, and show a message if the validator or submit handler throws:

<button
  type="submit"
  disabled={
    form.submission.status === 'validating' ||
    form.submission.status === 'submitting'
  }
>
  {form.submission.status === 'submitting' ? 'Saving…' : 'Save'}
</button>
{form.submission.error != null && (
  <p role="alert">Could not save. Please try again.</p>
)}

Place the button inside the native form from the getting-started example. Validation failures appear through ErrorSummary and the field widgets; submission.error represents an exception, not an invalid field.