Accessible form errors Working pattern · WCAG 2.2

<form class="afe" id="delivery" novalidate data-afe>
  <!-- The summary: filled, shown and focused when the form is sent with errors.
       Use the heading level that fits your page. -->
  <div class="afe-summary" id="delivery-summary" tabindex="-1" hidden>
    <h4 class="afe-summary__title">There is a problem with your details</h4>
    <ul class="afe-summary__list"></ul>
  </div>

  <div class="afe-field">
    <label class="afe-label" for="delivery-name">Full name <span class="afe-req">(required)</span></label>
    <p class="afe-hint" id="delivery-name-hint">As it should appear on the parcel.</p>
    <p class="afe-error" id="delivery-name-error" hidden></p>
    <input class="afe-input" id="delivery-name" name="name" type="text" autocomplete="name" spellcheck="false" required aria-describedby="delivery-name-hint">
  </div>

  <div class="afe-field">
    <label class="afe-label" for="delivery-email">Email address <span class="afe-req">(required)</span></label>
    <p class="afe-hint" id="delivery-email-hint">We send updates about the delivery here.</p>
    <p class="afe-error" id="delivery-email-error" hidden></p>
    <input class="afe-input" id="delivery-email" name="email" type="email" autocomplete="email" spellcheck="false" required aria-describedby="delivery-email-hint">
  </div>

  <div class="afe-field">
    <label class="afe-label" for="delivery-phone">Phone number <span class="afe-req">(optional)</span></label>
    <p class="afe-hint" id="delivery-phone-hint">Only for the courier, if they cannot find you.</p>
    <p class="afe-error" id="delivery-phone-error" hidden></p>
    <input class="afe-input afe-input--short" id="delivery-phone" name="phone" type="tel" autocomplete="tel" aria-describedby="delivery-phone-hint">
  </div>

  <div class="afe-field">
    <label class="afe-label" for="delivery-country">Country <span class="afe-req">(required)</span></label>
    <p class="afe-error" id="delivery-country-error" hidden></p>
    <!-- data-native keeps this site's custom dropdown off the select. Leave it out on yours. -->
    <select class="afe-input" id="delivery-country" name="country" autocomplete="country" required data-native>
      <option value="">Select a country</option>
      <option value="CA">Canada</option>
      <option value="IN">India</option>
      <option value="GB">United Kingdom</option>
      <option value="US">United States</option>
    </select>
  </div>

  <div class="afe-field">
    <label class="afe-label" for="delivery-postcode">Postcode <span class="afe-req">(required)</span></label>
    <p class="afe-hint" id="delivery-postcode-hint">In India, your PIN code. In the United States, your ZIP code.</p>
    <p class="afe-error" id="delivery-postcode-error" hidden></p>
    <input class="afe-input afe-input--short" id="delivery-postcode" name="postcode" type="text" autocomplete="postal-code" spellcheck="false" required aria-describedby="delivery-postcode-hint">
  </div>

  <div class="afe-field">
    <p class="afe-error" id="delivery-consent-error" hidden></p>
    <div class="afe-check">
      <input id="delivery-consent" name="consent" type="checkbox" value="yes" required>
      <label for="delivery-consent">I agree that the courier may use these details to deliver my order <span class="afe-req">(required)</span></label>
    </div>
  </div>

  <button class="afe-submit" type="submit">Save delivery details</button>
  <p class="afe-status" role="status"></p>
</form>

/* Accessible form errors: the pattern's styles.
   Colours are custom properties, so a site can point them at its own tokens.
   Against --afe-bg, the defaults keep text at 4.5:1 or more and field
   borders at 3:1 or more, in both colour schemes. */
.afe {
    --afe-ink: #1b1b18;
    --afe-ink-2: #4a4a44;
    --afe-bg: #ffffff;
    --afe-line: #6b6b64;
    --afe-error: #b3261e;
    --afe-ok: #146c3c;
    display: grid;
    gap: 1.25rem;
    max-width: 34rem;
    color: var(--afe-ink);
    line-height: 1.5;
}
@media (prefers-color-scheme: dark) {
    .afe {
        --afe-ink: #f3f3ef;
        --afe-ink-2: #c4c4bd;
        --afe-bg: #1c1c1a;
        --afe-line: #8f8f87;
        --afe-error: #ff8a80;
        --afe-ok: #7bd6a0;
    }
}
.afe [hidden] { display: none !important; }

/* The summary: every error, as a link to its field. */
.afe-summary {
    padding: 1rem 1.25rem;
    border: 3px solid var(--afe-error);
    border-radius: 8px;
    scroll-margin-top: 6rem;
}
.afe-summary:focus { outline: 3px solid var(--afe-ink); outline-offset: 3px; }
.afe-summary__title { margin: 0 0 .5rem; font-size: 1.2rem; line-height: 1.3; }
.afe-summary__list { margin: 0; padding-left: 1.25rem; list-style: disc; }
.afe-summary__list li + li { margin-top: .3rem; }
.afe-summary__list a {
    color: var(--afe-error);
    font-weight: 600;
    text-decoration: underline;
    text-underline-offset: .15em;
}

/* A field: label, hint and error above the control. */
.afe-field { display: grid; gap: .3rem; }
.afe-field.is-invalid { padding-left: .9rem; border-left: 4px solid var(--afe-error); }
.afe-label { font-weight: 600; }
.afe-req { font-weight: 400; color: var(--afe-ink-2); }
.afe-hint { margin: 0; color: var(--afe-ink-2); }
.afe-error {
    display: flex;
    align-items: flex-start;
    gap: .45rem;
    margin: 0;
    color: var(--afe-error);
    font-weight: 600;
}
/* The icon is drawn in the text colour, so it stays visible in forced colours. */
.afe-icon {
    display: inline-grid;
    place-items: center;
    flex: none;
    box-sizing: border-box;
    width: 1.3em;
    height: 1.3em;
    margin-top: .1em;
    border: 2px solid currentColor;
    border-radius: 50%;
    font-size: .9em;
    line-height: 1;
}
.afe-icon::before { content: "!"; font-weight: 800; }

.afe-input {
    box-sizing: border-box;
    width: 100%;
    min-height: 2.75rem;
    padding: .5rem .7rem;
    border: 2px solid var(--afe-line);
    border-radius: 6px;
    background: var(--afe-bg);
    color: var(--afe-ink);
    font: inherit;
}
.afe-input--short { max-width: 14rem; }
.afe-input[aria-invalid="true"] { border-color: var(--afe-error); box-shadow: inset 0 0 0 1px var(--afe-error); }

/* The checkbox: a 24px box beside its label, so both are easy to hit. */
.afe-check { display: flex; align-items: flex-start; gap: .75rem; }
.afe-check input {
    flex: none;
    width: 1.5rem;
    height: 1.5rem;
    margin: 0;
    accent-color: var(--afe-ink);
}

.afe-submit {
    justify-self: start;
    min-height: 2.75rem;
    padding: .6rem 1.25rem;
    border: 2px solid var(--afe-ink);
    border-radius: 6px;
    background: var(--afe-ink);
    color: var(--afe-bg);
    font: inherit;
    font-weight: 700;
    cursor: pointer;
}
.afe-input:focus-visible,
.afe-check input:focus-visible,
.afe-submit:focus-visible { outline: 3px solid var(--afe-ink); outline-offset: 2px; }

/* The status line stays rendered while empty: a live region that is not in
   the page when its words arrive is not read out. */
.afe-status { margin: 0; color: var(--afe-ok); font-weight: 600; }

/* Read by screen readers, not shown. */
.afe-sr {
    position: absolute;
    width: 1px;
    height: 1px;
    overflow: hidden;
    clip-path: inset(50%);
    white-space: nowrap;
}

/**
 * Accessible form errors: the behaviour.
 *
 * Enhances every <form data-afe>. The form is checked when it is sent, never
 * while someone types. When anything is wrong:
 *   - each field in error gets its message in words, with an icon, next to it
 *     (joined to the field by aria-describedby), and is marked aria-invalid;
 *   - the summary at the top lists every message as a link to its field and
 *     takes focus, so a screen reader reads it straight away;
 *   - nothing that was typed is cleared.
 * Messages change only when the form is sent again. Clearing one as someone
 * leaves a field would move everything below it, and a click on the button
 * that caused the leaving could then land somewhere else. When every field is
 * valid, the status line says so (role="status": read out, focus stays put).
 */
import { FIELDS, SAVED, validate } from "./form-rules.js";

/** The form's values by field name. A box that is not ticked counts as "". */
function valuesOf(form) {
    const values = {};
    for (const name of FIELDS) {
        const field = form.elements.namedItem(name);
        if (!field) continue;
        values[name] = field.type === "checkbox" ? (field.checked ? field.value : "") : field.value;
    }
    return values;
}

export function enhance(form) {
    const summary = form.querySelector(".afe-summary");
    const list = form.querySelector(".afe-summary__list");
    const status = form.querySelector(".afe-status");
    const fields = FIELDS.map((name) => form.elements.namedItem(name)).filter(Boolean);
    // Each field's own description (its hint), so an error can be added to it and taken off again.
    const hints = new Map(fields.map((field) => [field, field.getAttribute("aria-describedby") || ""]));

    function showError(field, message) {
        const box = document.getElementById(`${field.id}-error`);
        const hint = hints.get(field);
        field.closest(".afe-field")?.classList.toggle("is-invalid", Boolean(message));
        if (!message) {
            box.replaceChildren();
            box.hidden = true;
            field.removeAttribute("aria-invalid");
            if (hint) field.setAttribute("aria-describedby", hint);
            else field.removeAttribute("aria-describedby");
            return;
        }
        const icon = document.createElement("span");
        icon.className = "afe-icon";
        icon.setAttribute("aria-hidden", "true");
        const prefix = document.createElement("span");
        prefix.className = "afe-sr";
        prefix.textContent = "Error:";
        const words = document.createElement("span");
        words.textContent = message;
        box.replaceChildren(icon, prefix, " ", words);
        box.hidden = false;
        field.setAttribute("aria-invalid", "true");
        field.setAttribute("aria-describedby", `${hint} ${box.id}`.trim());
    }

    function summaryLink(field, message) {
        const item = document.createElement("li");
        const link = document.createElement("a");
        link.href = `#${field.id}`;
        link.textContent = message;
        item.append(link);
        return item;
    }

    // A link in the summary shows its field with the label above it, then moves focus there.
    summary.addEventListener("click", (event) => {
        const link = event.target.closest("a[href^='#']");
        const field = link && document.getElementById(link.getAttribute("href").slice(1));
        if (!field) return;
        event.preventDefault();
        (field.closest(".afe-field") || field).scrollIntoView({ block: "center" });
        field.focus({ preventScroll: true });
    });

    form.addEventListener("submit", (event) => {
        // This example sends nothing. A real form sends the data at the end of
        // this handler (with fetch), or stops the browser only when there are
        // errors and lets it submit; either way, the server checks it again.
        event.preventDefault();
        const errors = validate(valuesOf(form));
        for (const field of fields) showError(field, errors.find((e) => e.name === field.name)?.message || "");
        status.textContent = "";
        if (errors.length) {
            list.replaceChildren(...errors.map((e) => summaryLink(form.elements.namedItem(e.name), e.message)));
            summary.hidden = false;
            summary.focus();
            return;
        }
        list.replaceChildren();
        summary.hidden = true;
        // Written a moment after it was emptied, so a second success is read out too.
        setTimeout(() => { status.textContent = SAVED; }, 100);
    });
}

if (typeof document !== "undefined") {
    for (const form of document.querySelectorAll("form[data-afe]")) enhance(form);
}

/**
 * Accessible form errors: the rules.
 *
 * Pure functions with no DOM, so they run (and are tested) anywhere. Each rule
 * takes a field's value, and all the values for rules that depend on another
 * field, and returns "" when the value is fine or the message to show when it
 * is not. Every message says what to do, not only what is wrong (WCAG 3.3.3),
 * and the same words appear in the summary and beside the field.
 */

/** The fields in the order they appear, so errors are listed in that order. */
export const FIELDS = ["name", "email", "phone", "country", "postcode", "consent"];

/** What the form says when every field is valid. */
export const SAVED = "Your delivery details are complete. This example sends nothing: they stay on this page.";

/** Postcode formats for the countries the form offers. Spaces and case are forgiven. */
export const POSTCODES = {
    CA: { re: /^[A-Z][0-9][A-Z] ?[0-9][A-Z][0-9]$/, message: "Enter a Canadian postal code, like K1A 0B1" },
    IN: { re: /^[1-9][0-9]{2} ?[0-9]{3}$/, message: "Enter a 6-digit PIN code, like 110001" },
    GB: { re: /^[A-Z]{1,2}[0-9][A-Z0-9]? ?[0-9][A-Z]{2}$/, message: "Enter a UK postcode, like EC1A 1BB" },
    US: { re: /^[0-9]{5}(-[0-9]{4})?$/, message: "Enter a 5-digit ZIP code, like 10001, or a ZIP+4 code, like 10001-1234" },
};

/** Collapse runs of spaces and trim: what people type is not what they mean to be checked. */
const tidy = (value) => String(value ?? "").replace(/\s+/g, " ").trim();

export const RULES = {
    // Names have no reliable format, so the only check is that one was given.
    name(value) {
        return tidy(value) ? "" : "Enter your full name";
    },
    email(value) {
        const v = tidy(value);
        if (!v) return "Enter your email address";
        if (!v.includes("@")) return "Enter an email address with an @, like [email protected]";
        const [, domain = ""] = v.split("@");
        if (!domain.includes(".")) return "Enter the part after the @, like [email protected]";
        if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v)) return "Enter an email address in the right format, like [email protected]";
        return "";
    },
    // Optional: an empty phone number is fine, a wrong one is not.
    phone(value) {
        const v = tidy(value);
        if (!v) return "";
        if (!/^\+?[0-9 ().-]+$/.test(v)) return "Use only digits, spaces, brackets and hyphens, with + only at the start";
        const digits = v.replace(/[^0-9]/g, "").length;
        if (digits < 7 || digits > 15) return "Enter a phone number with 7 to 15 digits, or leave it empty";
        return "";
    },
    country(value) {
        return POSTCODES[tidy(value)] ? "" : "Select the country for delivery";
    },
    postcode(value, values = {}) {
        const v = tidy(value).toUpperCase();
        if (!v) return "Enter your postcode";
        const format = POSTCODES[tidy(values.country)];
        // Without a country there is no format to check against; the country has its own error.
        return !format || format.re.test(v) ? "" : format.message;
    },
    consent(value) {
        return value ? "" : "Select the box to agree that the courier may use these details";
    },
};

/** Every problem with a set of values, in field order: [{ name, message }]. */
export function validate(values = {}) {
    const errors = [];
    for (const name of FIELDS) {
        const message = RULES[name](values[name], values);
        if (message) errors.push({ name, message });
    }
    return errors;
}