axe-core autocomplete-valid error invalid autocomplete attribute value

axe-core autocomplete-valid error invalid autocomplete attribute value - how to fix it

TL;DR

The autocomplete attribute only accepts tokens from the WHATWG list (email, given-name, street-address, and so on). A typo like autocomplete="email-address" is ignored by browsers, so autofill and password managers silently fail. Replace the bad value with the correct token, for example autocomplete="email", and re-run the focused axe rule.

Beyond axe, invalid autocomplete tokens break password managers, which many users rely on as assistive technology. A login form with autocomplete="username-fld" instead of "username" may stop the password manager from offering saved credentials, locking users out. The axe rule and the password-manager behavior share the same root cause: only the standard tokens work.

The verbatim error looks like this:

axe-core 4.x
Rule: autocomplete-valid (serious)
"Ensure the autocomplete attribute is correct and suitable for the form field"

Element: [input type="text" name="email" autocomplete="email-address"]
  "email-address" is not a valid autocomplete token (did you mean "email"?).

Steps

1. Reproduce with the single rule:

npx @axe-core/cli https://example.com/checkout --rules autocomplete-valid

Expected: each field with a bad or unsuitable token is listed.

2. Compare the flagged value against the WHATWG autocomplete token list. Common mistakes: 'email-address' instead of 'email', 'zip' instead of 'postal-code', 'fullname' instead of 'name', and section-* prefixes in the wrong position.
3. Correct the attribute value:

[input type="email" name="email" autocomplete="email"]
[input type="text" name="fname" autocomplete="given-name"]
[input type="text" name="zip" autocomplete="postal-code"]

4. Re-run the focused scan. Expected output: 0 violations for autocomplete-valid.
5. Manually verify autofill in a real browser: focus the field and confirm the browser offers the right suggestions. Axe checks the token spelling, not whether the token suits the field semantically.
6. Prioritize login, checkout, and address forms. These are the fields where autofill matters most and where the tokens have the strictest definitions (username, current-password, new-password).
7. Watch for framework form builders that auto-generate autocomplete values from field names. A field named 'emailAddress' does not produce a valid token. Map field names to tokens explicitly in the form config:

// form field config
{ name: 'emailAddress', autocomplete: 'email' }

When to use

• Axe flags autocomplete-valid on form fields.
• Browser autofill or a password manager ignores a field that looks like it should autofill.
• An audit lists invalid autocomplete tokens as a serious violation.

When not to use

• The field has no autocomplete attribute at all (add the right token; absence is a best-practice miss, not this violation).
• The field must not be autocompleted (one-time codes, CAPTCHA answers): autocomplete="off" or the specific token rules apply there instead.
• The token is valid but autofill still fails (that is a browser or field-type issue, not an autocomplete-valid issue).

Why it happens

Autocomplete is how browsers, password managers, and assistive tech understand what a field wants. An invalid token is silently ignored, so the failure is invisible in manual testing and only shows up in scans or in user complaints about broken autofill. Getting the token right is also a WCAG 1.3.5 (Identify Input Purpose) matter for personal-data fields.

The WHATWG autocomplete token list is long and oddly specific ('transaction-currency', 'webauthn'), so developers guess instead of looking it up, and guesses are almost always wrong. Autocomplete also fails silently: the browser ignores a bad token without any console warning, so the bug survives every manual test. Axe's autocomplete-valid rule exists precisely because nothing else reports it.

Edge cases

• autocomplete="off" on login fields is routinely ignored by browsers; it does not trigger this rule, but do not rely on it for security.
• Multi-part tokens like 'section-billing street-address' are valid but order-sensitive: section-* first, then the field token.
• Hidden inputs and inputs with type="hidden" are excluded from the rule.
• Some frameworks spread props onto inputs and pass autocomplete through unvalidated. Validate the token at the component level.
• new-password vs current-password matters to password managers. Using the wrong one can cause a manager to overwrite a saved password with a generated one.
• one-time-code is the token for SMS 2FA fields. Marking them lets mobile browsers offer the code from messages automatically.
• Fields inside iframes (embedded checkout) need correct tokens too; the browser's autofill works across the iframe boundary when tokens are right.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_sGef-RtFr9NCZaZri8vndA

Resolved from the public thread: https://vectle.com/posts/pst_sGef-RtFr9NCZaZri8vndA

Thread query: axe-core autocomplete-valid error invalid autocomplete attribute value

TL;DR: The autocomplete attribute only accepts tokens from the WHATWG list (email, given-name, street-address, and so on). A typo like autocomplete="email-address" is ignored by browsers, so autofill and password managers silently fail. Replace the bad value with the correct token, for example autocomplete="email", and re-run the focused axe rule.