Featured example · E-commerce flow

Recover a rejected checkout.

A payment API rejects nested address data, a promotion, and an unknown token field. The bridge turns that response into a focused route the shopper can complete.

Order
#NTH-2048
Total
€128.00

Recovery scenario

Correct the address and try again.

The first submission is intentionally rejected. Correct all three visible values to reach the local success state.

Try it

  1. Submit the prefilled checkout.
  2. Read the promoted token error in the form summary.
  3. Use customer@example.com, postal code 10431, and an empty promo field.
  4. Submit again and confirm the errors clear.
checkout.submit422 response

Delivery details

The payment action and response are simulated locally.

Ready for the local checkout simulation.

Implementation

Bridge backend names to usable controls.

Developer notes

  • shipping.postal_code maps to #checkout-postal.
  • coupon_code maps to #checkout-promo.
  • Mapped controls clear both the alias entry and owned control state explicitly on input.
  • messageMode: "all" displays both promotion messages.
  • The unknown payment.token field is promoted into the form summary.
  • The application owns pending and success states.

Accessibility notes

  • Native controls retain visible labels and autocomplete tokens.
  • The promoted unknown-field message is not silently lost.
  • Focus moves to the form error region after rejection.
  • Editing each matched field clears only its linked state.
  • Color, text, border, and focus all communicate the error state.

Copy path

How to use it.

  1. Give every checkout control a stable ID and form name.
  2. Map backend keys that differ from those client-side identifiers.
  3. Choose whether unknown fields become form errors, remain available, or are ignored.

HTML

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

<form id="checkout" data-a11y-server-error-bridge>
  <div data-a11y-server-error-bridge-form-errors></div>
  <label for="checkout-postal">Postal code</label>
  <input id="checkout-postal" name="postalCode">
  <button type="submit">Place order</button>
</form>

JavaScript

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

const form = document.querySelector("#checkout");
const bridge = createServerErrorBridge(form, {
  messageMode: "all",
  fieldAliases: {
    "shipping.postal_code": "checkout-postal"
  },
  unknownFieldStrategy: "form"
});

bridge.applyErrors(rejectedCheckoutPayload);