Framework-free TypeScript · Browser package

Turn server errors into a clear route back.

Normalize unpredictable API payloads, connect messages to real form controls, and move focus toward a useful recovery point without taking over submission.

Try the bridge View source on GitHub

Response route

01NormalizeAccept varied payloads
02ResolveMatch field names
03RenderUse safe text
04RecoverGuide focus

Package: a11y-server-error-bridge
Core dependencies: None
Rendering: textContent, never server HTML
Submission: Owned by your application

Live demo · Basic recovery

Send back a useful rejection.

Activate the simulated response. Focus moves to the form error region, the email field receives linked error text, and editing the email clears only that field error.

Enter any email address.
Activate Apply server response.
Read the summary, then edit the email field.

Start with source

Small surface. Explicit ownership.

The package is not published to npm yet. Build the repository locally, then import the generated ESM and stylesheet.

01 / Build

Prepare the local package

npm ci
npm run build:dist

02 / Markup

Provide a form and optional summary region

<link rel="stylesheet" href="./dist/styles.css">

<form data-a11y-server-error-bridge>
  <div data-a11y-server-error-bridge-form-errors></div>
  <label for="email">Email</label>
  <input id="email" name="email">
</form>

03 / JavaScript

Pass the rejected payload to the bridge

import { createServerErrorBridge } from "./dist/index.js";

const bridge = createServerErrorBridge(form);

bridge.applyErrors({
  fields: { email: "Already used" },
  form: ["Please review the form"]
});

Verified API

Tune recovery without replacing your form.

Options are passed to createServerErrorBridge(form, options). Defaults shown here come from the package source.

Option	Default	Purpose
`focusOnApply`	`"auto"`	Chooses summary, form error, or first-invalid recovery.
`unknownFieldStrategy`	`"form"`	Promotes, retains, or ignores messages without a matched control.
`messageMode`	`"first"`	Shows the first field message or every message.
`clearOnInput`	`true`	Clears the edited field's owned error state.
`clearOnChange`	`true`	Supports controls whose value commits on change.
`useAriaErrorMessage`	`true`	Adds `aria-errormessage` alongside `aria-describedby`.
`fieldAliases`	`{}`	Maps backend field keys to selectors, elements, or resolver functions.
`addons`	`[]`	Hands work to optional integration contracts.

Methods

applyErrors(): Normalizes, resolves, renders, and applies focus recovery.
clearErrors(): Removes state owned by the bridge and restores prior ARIA tokens.
clearField(): Removes the error attached to one field.
destroy(): Idempotently clears owned output, listeners, classes, and addon state.

Lifecycle events

Events bubble from the form and use the a11y-server-error-bridge: prefix.

init · normalize · apply · field-resolved · field-unresolved · integration-conflict · focus · clear · error · destroy

Accessibility behavior

Useful state, carefully owned.

The bridge augments the form you provide. It does not certify the final application or replace testing with real responses and assistive technology.

Semantic first

Labels, inputs, headings, lists, and regions remain application markup.

Linked errors

Resolved controls receive aria-invalid, descriptions, and optional error-message references.

Predictable focus

Explicit error application can focus a summary, form message, or first invalid field.

Reversible changes

Clear and destroy restore the attributes the bridge found before rendering.

Keyboard interaction

The bridge adds no custom shortcut layer. Use standard Tab, Shift + Tab, Enter, and Space behavior supplied by native form controls.

Known boundaries

Submission, retries, authentication, client validation, translations, and live-region policy remain application responsibilities. Pass existing peer instances when the first rejected response must be handled synchronously.

Styling hooks

Override --a11y-server-error-bridge-error-color, --a11y-server-error-bridge-background, --a11y-server-error-bridge-gap, and the documented bridge classes.

Scenario library