# Live Password Requirements Checklist

How do you show every password rule up front, tick each one off as the user types, and make sure the checklist, the error message and the browser’s own validity state never disagree? This recipe renders the checklist from a single rule table, updates it on every input event, mirrors the first unmet rule into setCustomValidity() so the Constraint Validation API stays authoritative, and wires the list to the field with aria-describedby so screen reader users get the same information sighted users do — without a live region firing on every keystroke.

# When to Use a Live Requirements Checklist

A checklist is the right tool when a field has several independent, binary rules that users cannot guess. Passwords are the canonical case, but usernames and some identifier fields share the shape. Reach for it when:

• The rules are hard constraints. Every item on the list must block submission if unmet. Advisory signals such as “guessability” belong in the password strength meter instead.
• There are two to five rules. One rule is just hint text; more than five suggests the policy itself needs simplifying.
• Rules can be checked synchronously. A rule that needs the network, like breach screening, should appear as a pending item that resolves after a debounce, not flicker on every keystroke.

Compared with a single error message that appears after submit, the checklist moves the information to before the mistake. Compared with inline errors on blur, it gives continuous feedback while typing, which suits passwords specifically because users cannot see what they typed.

# Minimal Working Checklist Implementation

The rule table is the single source of truth. The checklist markup, the custom validity message and the unit tests all derive from it, so adding a rule is a one-line change.

<label for="pw">Password</label>
<input id="pw" name="password" type="password" required minlength="12"
       autocomplete="new-password" aria-describedby="pw-reqs-heading pw-reqs pw-err">
<p id="pw-reqs-heading" class="reqs-heading">Your password needs:</p>
<ul id="pw-reqs" class="reqs"></ul>
<p id="pw-err" class="field-error" hidden></p>

interface Requirement {
  id: string;
  text: string;
  test: (value: string) => boolean;
}

const REQUIREMENTS: readonly Requirement[] = [
  { id: "len", text: "at least 12 characters", test: (v) => [...v].length >= 12 },
  { id: "space", text: "no spaces at the start or end", test: (v) => v === v.trim() },
  { id: "repeat", text: "no character repeated more than 3 times in a row", test: (v) => !/(.)\1{3,}/u.test(v) },
];

const field = document.querySelector<HTMLInputElement>("#pw")!;
const list = document.querySelector<HTMLUListElement>("#pw-reqs")!;
const error = document.querySelector<HTMLElement>("#pw-err")!;

// Build the list once; afterwards we only flip attributes and text.
const items = new Map<string, HTMLLIElement>();
for (const req of REQUIREMENTS) {
  const li = document.createElement("li");
  li.id = `req-${req.id}`;
  li.dataset.state = "pending";
  li.innerHTML = `<span class="req-status"></span> <span class="req-text"></span>`;
  li.querySelector(".req-text")!.textContent = req.text;
  list.append(li);
  items.set(req.id, li);
}

function sync(): boolean {
  const value = field.value;
  let firstUnmet: Requirement | undefined;
  for (const req of REQUIREMENTS) {
    const met = value.length > 0 && req.test(value);
    const li = items.get(req.id)!;
    li.dataset.state = value.length === 0 ? "pending" : met ? "met" : "unmet";
    // State in words, visually hidden or visible — never colour alone.
    li.querySelector(".req-status")!.textContent = value.length === 0 ? "" : met ? "Done:" : "Still needed:";
    if (!met && !firstUnmet) firstUnmet = req;
  }
  // Mirror into the native validity model so reportValidity() tells the same story.
  field.setCustomValidity(firstUnmet && value.length > 0 ? `Password needs ${firstUnmet.text}.` : "");
  return !firstUnmet;
}

field.addEventListener("input", () => {
  sync();
  // Once an error is showing, clear it the moment the rules are all met.
  if (!error.hidden && field.validity.valid) {
    error.hidden = true;
    field.removeAttribute("aria-invalid");
  }
});

field.form!.addEventListener("submit", (event) => {
  sync();
  if (!field.form!.checkValidity()) {
    event.preventDefault();
    error.textContent = field.validationMessage; // names the first unmet rule
    error.hidden = false;
    field.setAttribute("aria-invalid", "true");
    field.form!.reportValidity();
  }
});

The pending state matters: before the user types anything, rules should look neutral rather than failed. Painting three red crosses on an empty field is the checklist equivalent of showing an error before the user has had a chance — the problem the inline validation timing guide describes as “punishing early”.

# Checklist Option Reference

Keep the status prefix as real text even if you also draw icons. A visually hidden span works if the design wants icons only, but the words must exist in the accessibility tree; a CSS ::before icon does not reliably announce.

.reqs li[data-state="met"]   { color: var(--ok-text); }
.reqs li[data-state="unmet"] { color: var(--warn-text); }
.reqs li[data-state="met"]   .req-status::before { content: "✓ "; }
.reqs li[data-state="unmet"] .req-status::before { content: "• "; }

# Verification Steps

• Focus the field with a screen reader: you hear the label, then “Your password needs:” and each rule.
• Type a short value: items change visually, but nothing is announced mid-typing.
• Submit with one rule unmet: focus returns to the field and the message names that exact rule.
• Fix the rule: the error disappears on the next input without another submit.
• Clear the field: every item returns to the neutral pending state.

import { test, expect } from "@playwright/test";

test("checklist and validity stay in sync", async ({ page }) => {
  await page.goto("/signup");
  const pw = page.getByLabel("Password");
  await pw.pressSequentially("short");
  await expect(page.locator("#req-len")).toHaveAttribute("data-state", "unmet");
  await page.getByRole("button", { name: "Continue" }).click();
  await expect(pw).toHaveAttribute("aria-invalid", "true");
  await expect(page.locator("#pw-err")).toHaveText("Password needs at least 12 characters.");
  await pw.pressSequentially(" but longer now");
  await expect(page.locator("#req-len")).toHaveAttribute("data-state", "met");
  await expect(page.locator("#pw-err")).toBeHidden();
});

# Edge Cases and Failure Modes

Checklist and error disagree. If the checklist is built from one array and the error from a hand-written if chain, they drift. Always derive both from the same REQUIREMENTS table, and assert in a unit test that every rule’s text appears in its own error message.

Password managers fill the field without input. Some managers set the value and dispatch only change. Listen for both, or the checklist stays pending next to a perfectly valid generated password.

for (const type of ["input", "change"] as const) field.addEventListener(type, sync);

Asynchronous rules in a synchronous list. A breach check cannot run per keystroke. Render it as a separate item that shows “Checking…” after a debounce and resolves later, following the pattern in checking passwords against breached lists; keep it out of sync() so the synchronous items remain instant.

Hidden-field reveal. When the user toggles visibility with the show/hide password toggle, nothing about the rules changes; do not rebuild the list or re-run sync() on the toggle click.

# Rendering the Checklist Server-Side for Progressive Enhancement

The checklist is built by script above, which means users without JavaScript — or users on a slow connection before the bundle arrives — see no rules at all. Render the list in the HTML instead, in its neutral pending state, and let the script take over the existing items rather than creating them. The rules then appear instantly, survive a failed script load, and give the server-rendered error page something to reference when a submission comes back rejected.

<ul id="pw-reqs" class="reqs">
  <li id="req-len" data-state="pending"><span class="req-status"></span> <span class="req-text">at least 12 characters</span></li>
  <li id="req-space" data-state="pending"><span class="req-status"></span> <span class="req-text">no spaces at the start or end</span></li>
  <li id="req-repeat" data-state="pending"><span class="req-status"></span> <span class="req-text">no character repeated more than 3 times in a row</span></li>
</ul>

// Adopt server-rendered items instead of creating new ones.
for (const req of REQUIREMENTS) {
  const li = document.getElementById(`req-${req.id}`) as HTMLLIElement | null;
  if (!li) throw new Error(`Missing checklist item for rule "${req.id}"`);
  items.set(req.id, li);
}

The thrown error is deliberate: if a developer adds a rule to the table but forgets the markup, the page fails loudly in development rather than silently omitting a requirement in production. When the server rejects a submission, it can re-render the same list with data-state="unmet" on the failing items, so the user returns to exactly the view they would have seen with scripting enabled. That parity between the scripted and unscripted paths is the core idea of progressive enhancement without JavaScript.

# Writing Requirement Text That Works as Both Hint and Error

Each rule’s text is read in two contexts: as a neutral hint before typing (“Your password needs: at least 12 characters”) and inside the error sentence after a failed submit (“Password needs at least 12 characters.”). Writing it as a lowercase noun phrase that completes “needs…” makes both readings grammatical, which is why the table stores “at least 12 characters” rather than “Must be 12+ chars”. Avoid jargon such as “alphanumeric” or “special character” — say what counts (“a number or symbol, like 7 or #”) — and never phrase a rule negatively when a positive phrasing exists. The same guidance applies to every other field on the form; the clear inline error message copy guide covers the broader rules.

# Related Guides

• Password Validation Patterns — the full pipeline this checklist is one stage of.
• Building an Accessible Password Strength Meter — advisory strength next to the hard rules.
• Linking Errors with aria-describedby — the association technique used for the list and error.
• Clearing Custom Validity on Input — why the error clears the moment the rules pass.

← Back to Password Validation Patterns