a11y-validate

Accessible form validation. Zero dependencies, one file, works with any framework or plain HTML.

The problem

Most form-validation libraries show a red message under a field and call it done. A screen reader user gets none of that: nothing announces that submission failed, nothing tells them how many fields have problems, focus doesn't move anywhere useful, and the error text is often not actually linked to the field it describes. The visual experience and the accessible experience quietly diverge.

a11y-validate builds on the pattern GOV.UK and the US Web Design System converged on after real user testing: a focus-managed error summary at the top of the form, linked to each problem field, plus proper aria-invalid / aria-describedby wiring on every field itself.

Install

Drop the file in and include it — no build step, no bundler required:

<script src="a11y-validate.js"></script>

Or via npm if you're bundling:

npm install a11y-validate

Quick start (zero JS config)

Add data-a11y-validate to any form. Standard HTML5 validation attributes (required, pattern, minlength, type="email", etc.) are picked up automatically — a11y-validate uses the browser's own Constraint Validation API rather than reimplementing it.

<form data-a11y-validate>
  <label for="email">Email address</label>
  <input type="email" id="email" name="email" required
         data-error-required="Please enter your email address."
         data-error-type="Please enter a valid email address.">

  <button type="submit">Submit</button>
</form>
<script src="a11y-validate.js"></script>

Submit it empty or with something invalid and you'll see:

• An error summary box appears at the top, focus moves to it, and a screen reader announces it immediately
• Each summary entry links directly to its field
• The field itself gets aria-invalid="true" and an error message wired via aria-describedby, so a screen reader announces the specific problem the moment that field is focused

Custom messages per validation type

Any HTML5 validation failure can have a custom message via a data-error-* attribute:

| Attribute | Fires when | |---|---| | data-error-required | field is empty but required | | data-error-type | type="email"/type="url"/etc. doesn't match | | data-error-pattern | pattern attribute doesn't match | | data-error-minlength / data-error-maxlength | minlength / maxlength violated | | data-error-min / data-error-max | min / max violated | | data-error-step | step violated |

If you don't provide one, a sensible default is used.

Custom validation rules

For anything HTML5 attributes can't express (password strength, matching another field, an async-feeling check), use programmatic init instead of the data-a11y-validate attribute:

A11yValidate.init(document.getElementById('signup-form'), {
  rules: {
    password: (value) => value.length >= 8 ? null : 'Password must be at least 8 characters.'
  },
  onValidSubmit: (event, values) => {
    // values = { username: '...', password: '...' }
    // handle your fetch/submit here — event.preventDefault() is already called
  }
});

A rule function receives the field's current value and returns an error string, or null/falsy when valid. Rules run after built-in HTML5 validation, so a required field with an empty value never reaches your custom rule.

If onValidSubmit isn't provided, a successful validation lets the form submit natively (a real POST navigation).

Behavior details worth knowing

• Errors don't appear while first filling in the form. Live revalidation on blur/input only activates after the user has attempted a submit once — so tabbing through an untouched form doesn't trigger a wall of red text.
• Fields don't need a pre-set id. One is generated automatically if missing, so error linking always works.
• The error summary is focused, not the first field. This matches the tested GOV.UK/USWDS pattern — screen reader users hear the full picture ("N problems, here's what they are") before moving to fix anything, rather than landing on field one with no context.

Styling

Minimal inline styles are applied by default (red border/text for errors) so it's usable out of the box. Override with your own CSS by targeting .a11y-error, .a11y-error-summary, .a11y-error-summary-heading, and .a11y-error-summary-list.

Why this exists

Most "accessible" form libraries are accessible in name only — a color change on invalid fields, no summary, no focus management, no verified aria-describedby linkage. This one leans entirely on the browser's own validation engine for the "what's invalid" question, and spends its actual code on the accessibility wiring most libraries skip.

Built by Cybergeon Technologies.

License

MIT © Cybergeon Technologies — see LICENSE.