# Cross-Field Password Confirmation Logic: Implementation & Edge Cases

This recipe implements a real-time “passwords must match” check that updates as the user types, survives paste and autofill, normalizes Unicode, and announces mismatches to screen readers exactly once — all in framework-agnostic TypeScript.

It is the focused, copy-ready companion to Cross-Field Validation Strategies: that guide explains the dependency-graph and topological-order machinery; here we apply it to the single most common two-field relationship and keep the site’s <form novalidate> plus manual reportValidity() house pattern in charge of submission.

# When to Use This Recipe

• Use it on any sign-up, password-reset, or change-password form with a confirmation field.
• Use it when you want immediate input-time feedback rather than waiting for blur or submit.
• Reach for the parent guide instead when more than two fields interlock or when matching depends on a server response — those need the full dependency resolver and an AbortController-backed asynchronous server check.

# The Minimal Working Implementation

The architecture keeps a single normalized state object outside the event loop, attaches an input listener to both fields, and routes every change through one pure comparison function. As established in Cross-Field Validation Strategies, tracking the dependency outside the DOM prevents redundant queries and guarantees deterministic transitions.

interface ValidationState {
  password: string;
  confirm: string;
  isValid: boolean;
  message: string;
}

const state: ValidationState = { password: '', confirm: '', isValid: false, message: '' };

// Pure, side-effect-free comparison — trivial to unit test.
function validateMatch(pw: string, confirm: string): Pick<ValidationState, 'isValid' | 'message'> {
  // Unicode-normalize so visually identical input compares equal.
  const a = pw.normalize('NFC');
  const b = confirm.normalize('NFC');

  if (!b) return { isValid: false, message: '' };               // empty confirm: stay silent
  if (a !== b) return { isValid: false, message: 'Passwords do not match.' };
  return { isValid: true, message: 'Passwords match.' };
}

// DOM writes batched into one frame to avoid layout thrashing.
function renderState(s: ValidationState, confirmInput: HTMLInputElement, errorEl: HTMLElement): void {
  requestAnimationFrame(() => {
    const { isValid, message } = validateMatch(s.password, s.confirm);
    const showError = !isValid && Boolean(message);

    confirmInput.classList.toggle('is-valid', isValid);
    confirmInput.classList.toggle('is-invalid', showError);
    confirmInput.setAttribute('aria-invalid', String(showError));
    errorEl.textContent = message;
    errorEl.classList.toggle('hidden', !message);
  });
}

const pwInput = document.querySelector<HTMLInputElement>('#password')!;
const confirmInput = document.querySelector<HTMLInputElement>('#confirm-password')!;
const errorEl = document.querySelector<HTMLElement>('#confirm-error')!;

// Bidirectional: editing EITHER field re-runs the shared rule.
function handleInput(e: Event): void {
  const target = e.target as HTMLInputElement;
  if ((e as InputEvent).isComposing) return; // skip IME intermediate states
  if (target.id === 'password') state.password = target.value;
  else state.confirm = target.value;
  renderState(state, confirmInput, errorEl);
}

pwInput.addEventListener('input', handleInput);
confirmInput.addEventListener('input', handleInput);

The matching markup wires the error container to the confirmation field and provides a polite live region so the verdict is announced without stealing focus:

<div class="field">
  <label for="password">Password</label>
  <input id="password" type="password" autocomplete="new-password" />
</div>
<div class="field">
  <label for="confirm-password">Confirm password</label>
  <input id="confirm-password" type="password" autocomplete="new-password"
         aria-describedby="confirm-error" aria-invalid="false" />
  <p id="confirm-error" class="field-error" aria-live="polite" aria-atomic="true"></p>
</div>

# Parameter & Option Reference

# Verifying It Works

1. Type a mismatch: Confirmation gains aria-invalid="true", the error text appears, and the live region announces it once.
2. Correct it: As soon as the values match, aria-invalid flips to false and the message changes to “Passwords match.”
3. Paste into confirmation: The value commits and the rule re-runs (see paste handling below).
4. Playwright assertion:

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

test('flags and clears a password mismatch', async ({ page }) => {
  await page.goto('/signup');
  await page.getByLabel('Password').fill('Sup3r-Secret!');
  await page.getByLabel('Confirm password').fill('Sup3r-Secre');
  await expect(page.locator('#confirm-error')).toHaveText('Passwords do not match.');
  await page.getByLabel('Confirm password').fill('Sup3r-Secret!');
  await expect(page.getByLabel('Confirm password')).toHaveAttribute('aria-invalid', 'false');
});

# Edge Cases & Failure Modes

1. Paste and autofill fire after the value lands. A paste event runs before the pasted text is in the DOM, and browser autofill may not fire input at all. Defer the re-check and listen for the autofill animation.

// Paste: defer one tick so the clipboard value is committed.
confirmInput.addEventListener('paste', () => setTimeout(() => handleInput({ target: confirmInput } as unknown as Event), 0));

// Autofill: WebKit/Chromium emit an animationstart on the autofill pseudo-class.
confirmInput.addEventListener('animationstart', (e) => {
  if ((e as AnimationEvent).animationName.includes('autofill')) handleInput({ target: confirmInput } as unknown as Event);
});

@keyframes onAutoFillStart { from {} to {} }
input:-webkit-autofill { animation-name: onAutoFillStart; }

2. Hidden characters defeat a correct password. A pasted password can carry zero-width spaces or a BOM, producing a false mismatch. Strip them alongside the NFC normalization.

const sanitize = (v: string) => v.replace(/[​-‍]/g, '').normalize('NFC');
// use sanitize() in both the input handler and validateMatch

3. Listener leaks in single-page apps. Re-mounting the form without removing listeners doubles them, causing duplicate announcements. Tear down on unmount.

export function teardown(): void {
  pwInput.removeEventListener('input', handleInput);
  confirmInput.removeEventListener('input', handleInput);
}

4. Caps Lock silently breaks the match. With masked type="password" fields a user cannot see that Caps Lock turned Secret! into sECRET!, so the mismatch looks inexplicable. Surface a non-blocking warning via the getModifierState API rather than only reporting “do not match.”

function watchCapsLock(input: HTMLInputElement, warningEl: HTMLElement): void {
  const update = (e: KeyboardEvent) => {
    const on = e.getModifierState?.('CapsLock');
    warningEl.textContent = on ? 'Caps Lock is on.' : '';
    warningEl.classList.toggle('hidden', !on);
  };
  input.addEventListener('keyup', update);
  input.addEventListener('keydown', update);
}

Pair the warning with its own aria-live="polite" region so it is announced once when state changes, and keep it distinct from the match error container so the two messages never overwrite each other. This turns a baffling mismatch into a self-explanatory one and noticeably cuts support tickets on sign-up flows.

# Gating Submission with setCustomValidity

The input-time rendering above is a UX layer; it does not stop a determined user from pressing Enter while the fields disagree. Because the site keeps <form novalidate> and calls reportValidity() by hand, you can promote the same pure comparison into the Constraint Validation API so the browser refuses submission and surfaces the message through its native bubble — without giving up your custom live-region text.

The mechanism is setCustomValidity(). Passing a non-empty string marks the control invalid and populates its validationMessage; passing the empty string clears the flag. The subtlety most implementations miss is that a stale custom-validity string is sticky: if you set it on mismatch and never clear it, the field stays invalid forever even after the values agree. Re-derive it on every change from the single source of truth.

// Bridge the pure rule into ValidityState so the form itself blocks submit.
function syncConstraint(confirmInput: HTMLInputElement, s: ValidationState): void {
  const { isValid, message } = validateMatch(s.password, s.confirm);
  // Empty string ⇒ valid; any non-empty string ⇒ customError === true.
  confirmInput.setCustomValidity(isValid ? '' : message);
}

const form = document.querySelector<HTMLFormElement>('#signup-form')!;

form.addEventListener('submit', (e) => {
  syncConstraint(confirmInput, state);
  // reportValidity() returns false and shows the native bubble on the first
  // invalid control, mirroring what the polite live region already announced.
  if (!form.reportValidity()) {
    e.preventDefault();
  }
});

Call syncConstraint from inside handleInput as well, so confirmInput.validity.customError tracks the live state and a scripted form.checkValidity() — used by test harnesses or a disabled-until-valid submit button — always reflects reality. Because setCustomValidity writes to the element rather than to a detached object, it also participates in the :invalid CSS pseudo-class for free, letting you style the field without a second is-invalid toggle if you prefer.

# Preventing Password-Manager False Mismatches

Password managers are the most common source of “it matched a second ago” bug reports. When a manager fills the first field and then generates or fills the confirmation, the two writes can land in separate microtasks, so a comparison that runs on the first input event sees an empty confirmation and caches a mismatch that never clears. The new-password autocomplete hint helps managers fill both fields, but the render still has to be re-triggered after the second write.

The robust fix is to treat the field value — not the event timing — as the source of truth, and to reconcile once more after the current task queue drains:

// After any burst of programmatic writes, re-read both live DOM values and
// re-run the rule. queueMicrotask defers past a manager's paired fill.
function reconcileFromDom(): void {
  queueMicrotask(() => {
    state.password = pwInput.value;
    state.confirm = confirmInput.value;
    renderState(state, confirmInput, errorEl);
    syncConstraint(confirmInput, state);
  });
}

// Managers frequently fire 'change' (not 'input') on their final write.
pwInput.addEventListener('change', reconcileFromDom);
confirmInput.addEventListener('change', reconcileFromDom);

Reading .value directly sidesteps the whole class of ordering bugs: no matter how many events a manager emits or drops, the last reconciliation observes the settled DOM. Keep the change listeners in addition to input, not instead of it — input gives you keystroke-level responsiveness, while change is the reliable catch-all for autofill, drag-and-drop, and speech dictation that some engines route around input entirely.

# Related Guides

• Cross-Field Validation Strategies — the dependency-graph foundation this recipe applies
• Validating a Date Range (Start Before End) — the same bidirectional pattern for two coupled dates
• Synchronous Validation Patterns — composing the pure comparison this recipe relies on
• Asynchronous Server Checks — when matching must be verified against a backend

← Back to Cross-Field Validation Strategies