Accessible forms tutorial
The pattern every Lily form follows, whatever the framework: label every control, check on submit, put each error next to its field, and summarise the errors where focus lands.
What you'll build
A two-field form that, when submitted with mistakes, says what is wrong,
beside each field and in a summary at the top, and moves focus there, so
a keyboard or screen-reader user finds the errors at once. It is shown in
plain HTML with the Lily class hooks; every framework catalog renders the
same markup from its own Field, Hint, ErrorMessage and ErrorSummary components.
About 20 minutes; the HTML tutorial first
helps.
Step 1 — Label every control, and say what you expect
<form class="form" novalidate>
<div class="field">
<label class="label" for="name">Full name</label>
<input class="text-input" type="text" id="name" name="name" autocomplete="name" required />
</div>
<div class="field">
<label class="label" for="email">Email</label>
<p class="hint" id="email-hint">We only use this to send your appointment.</p>
<input class="email-input" type="email" id="email" name="email"
autocomplete="email" aria-describedby="email-hint" required />
</div>
<button class="button" type="submit">Continue</button>
</form> - A visible
<label for>on every control, never a placeholder in its place: a placeholder vanishes as you type. - A hint joins the field's name through
aria-describedby, so a screen reader reads it with the field. autocompletelets the browser fill what it knows (WCAG 1.3.5).novalidateturns off the browser's own bubbles, because you will show the errors yourself, in your words and your language. Therequiredandtypestay: your script reads them.
Step 2 — Check on submit, not while someone types
Telling someone their email is wrong after one letter is noise. Check when
they submit. The 63 themes already style a field as invalid only after it
has been edited and left (:user-invalid), or when you set aria-invalid="true", so nothing turns red on page load.
Never disable the submit button until the form is valid: a disabled button cannot say why.
Step 3 — Put each error next to its field
<div class="field">
<label class="label" for="email">Email</label>
<p class="hint" id="email-hint">We only use this to send your appointment.</p>
<p class="error-message" id="email-error">Enter an email address in the right format, like name@example.com</p>
<input class="email-input" type="email" id="email" name="email" autocomplete="email"
aria-invalid="true" aria-describedby="email-hint email-error" required />
</div> aria-invalid="true"says the field is wrong; the message says why and how to fix it.- The message is in
aria-describedby, after the hint, so it is read when the field is focused. - Say what to do, not just what is wrong: "Enter an email address in the right format", not "Invalid".
- Never colour alone: the text is the error; the red border only repeats it (WCAG 1.4.1).
Step 4 — Summarise the errors where focus lands
<div class="error-summary" role="alert" tabindex="-1" aria-labelledby="error-summary-title">
<h2 id="error-summary-title">There is a problem</h2>
<ul>
<li><a href="#name">Enter your full name</a></li>
<li><a href="#email">Enter an email address in the right format, like name@example.com</a></li>
</ul>
</div> Put it at the top of the form and move focus to it on submit. Each link
goes straight to its field. tabindex="-1" lets the summary
take focus without adding a tab stop.
Step 5 — The script that ties it together
const messages = {
name: { valueMissing: "Enter your full name" },
email: {
valueMissing: "Enter your email address",
typeMismatch: "Enter an email address in the right format, like name@example.com",
},
};
const form = document.querySelector("form");
form.addEventListener("submit", (event) => {
form.querySelector(".error-summary")?.remove();
const errors = [];
for (const field of form.querySelectorAll("input")) {
const old = document.getElementById(field.id + "-error");
old?.remove();
const describedBy = (field.getAttribute("aria-describedby") ?? "")
.split(" ").filter((id) => id && id !== field.id + "-error");
const problem = Object.keys(messages[field.name] ?? {}).find((key) => field.validity[key]);
if (!problem) {
field.removeAttribute("aria-invalid");
field.setAttribute("aria-describedby", describedBy.join(" "));
continue;
}
const text = messages[field.name][problem];
const message = document.createElement("p");
message.className = "error-message";
message.id = field.id + "-error";
message.textContent = text;
field.before(message);
field.setAttribute("aria-invalid", "true");
field.setAttribute("aria-describedby", [...describedBy, message.id].join(" "));
errors.push({ id: field.id, text });
}
if (errors.length === 0) return; // valid: let it submit
event.preventDefault();
const summary = document.createElement("div");
summary.className = "error-summary";
summary.setAttribute("role", "alert");
summary.tabIndex = -1;
summary.setAttribute("aria-labelledby", "error-summary-title");
summary.innerHTML = '<h2 id="error-summary-title">There is a problem</h2><ul></ul>';
for (const { id, text } of errors) {
const link = document.createElement("a");
link.href = "#" + id;
link.textContent = text;
const item = document.createElement("li");
item.append(link);
summary.querySelector("ul").append(item);
}
form.prepend(summary);
summary.focus();
}); The messages are yours, in your language: the browser's validity says which rule failed, and your table says what
to tell the person. Lily ships no English for you to translate.
Check your work: submit the empty form with the keyboard. Focus moves to the summary and a screen reader reads "There is a problem" and both errors. Follow a link: focus lands in the field, which is read with its hint and its error. Fix both and submit: the form goes through, and no error is left behind.
What to avoid
- Clamping or correcting what someone typed without saying so; tell them instead.
- Clearing a form on error: keep everything they entered.
- An error that appears only on hover, or only in a tooltip.
- Timing out a form without warning; use
timeout-dialogto warn and extend.
Next steps
- Training — eight modules, each with an exercise and a self-check.
- ErrorSummary, Field and ErrorMessage in the catalog.
- A form that works worldwide — names, addresses, dates and direction.
- Theming — the invalid state each theme draws.