Official addon · Support without disclosure

Failure details users can safely share

Keep a concise attempt number, numeric service status, and optional reference visible after a failure—separate from the transient status announcement and without exposing form values.

Try the live demo or jump to setup.

Quick facts

Package entry

a11y-form-submission-recovery/addons/failure-support-summary

Default markup

Application supplied; generated markup requires explicit opt-in.

Interaction

No controls, focus movement, live region, storage, or network activity.

Live support workflow

Choose a simulated outcome and submit. A 503 failure can be retried to demonstrate a repeated attempt. Success or the application-owned reset button clears the support section. No request leaves this page.

Install and initialize

npm install a11y-form-submission-recovery

import {
  createFormSubmissionRecovery
} from "a11y-form-submission-recovery";
import {
  createFailureSupportSummaryAddon
} from "a11y-form-submission-recovery/addons/failure-support-summary";

const supportSummary = createFailureSupportSummaryAddon({
  container: "[data-a11y-form-submission-recovery-support]",
  includeAttemptNumber: true,
  includeHttpStatus: true,
  includeSubmissionReference: true,
  labels: {
    heading: "Submission support details",
    attempt: "Attempt",
    status: "Service status",
    reference: "Reference"
  }
});

createFormSubmissionRecovery(form, {
  addons: [supportSummary]
});

Place a submission-reference addon before this addon when the core should generate and attach the reference to each attempt.

Application-owned semantic markup

A labelled section and description list keep the information navigable as ordinary document content. Do not add role="status" or aria-live; the core status region already announces the workflow outcome.

<section
  class="a11y-form-submission-recovery__support"
  data-a11y-form-submission-recovery-support
  aria-labelledby="support-title"
  hidden
>
  <h2
    id="support-title"
    data-a11y-form-submission-recovery-support-heading
  >Submission support details</h2>
  <dl>
    <div data-a11y-form-submission-recovery-support-attempt-row>
      <dt data-a11y-form-submission-recovery-support-attempt-label>
        Attempt
      </dt>
      <dd data-a11y-form-submission-recovery-support-attempt></dd>
    </div>
    <div data-a11y-form-submission-recovery-support-status-row>
      <dt data-a11y-form-submission-recovery-support-status-label>
        Service status
      </dt>
      <dd data-a11y-form-submission-recovery-support-status></dd>
    </div>
    <div data-a11y-form-submission-recovery-support-reference-row>
      <dt data-a11y-form-submission-recovery-support-reference-label>
        Reference
      </dt>
      <dd data-a11y-form-submission-recovery-support-reference></dd>
    </div>
  </dl>
</section>

Safe-field boundary

Field	Default	Behavior
Attempt number	Included	A positive integer from the sanitized failure event.
HTTP status	Included	Numeric status only. Status text and response URL are excluded.
Submission reference	Excluded	Separately opt-in and shown only when a non-empty reference exists.
Form and response content	Never included	Values, bodies, headers, field errors, messages, and URLs are not read or rendered.

Options

Option	Default	Purpose
`container`	Support data selector	Application-owned element or form-scoped selector.
`createContainer`	`false`	Explicitly creates a labelled section and description list when no container exists.
`includeAttemptNumber`	`true`	Shows the attempt number after failure.
`includeHttpStatus`	`true`	Shows a valid numeric HTTP status when available.
`includeSubmissionReference`	`false`	Shows a non-empty reference after explicit opt-in.
`labels`	English labels	Overrides heading and term text; values are always assigned with `textContent`.

Support workflow recipe

Keep the core status message short and action oriented.
Leave the support section visible after a failure and during any deliberate retry.
Ask the user to quote the reference and numeric status, not their form answers.
Use the reference to correlate server-side records only when the backend recognizes it.
Hide the section after success or an application reset.

A copy button is intentionally not part of this addon. If an application adds one, keep it application owned, require a user action, preview or clearly describe the copied fields, report copy success or failure, and repeat the privacy review.

Accessibility and keyboard behavior

The summary is static document content, not another live region.
The application-provided heading makes the section navigable by heading.
The description list preserves label-value relationships.
The addon adds no keyboard commands, controls, focus movement, color-only state, or motion.
Generated markup uses the same structure but must be explicitly enabled.

Normal browser commands such as heading navigation and text selection apply. The demo submit, retry, and reset buttons retain native keyboard behavior.

Limitations

A numeric status can be absent for network and uncertain outcomes.
A reference is useful only when the application and support process recognize it.
The addon does not copy, log, store, transmit, or format a support ticket.
The addon does not guarantee that an operational reference is non-sensitive.
Application-owned markup must keep its own valid heading relationship.