autocomplete: the right token for every form field

What autocomplete is

autocomplete names what a form field collects, using a fixed vocabulary defined by the HTML standard: given-name, email, tel, address-line1, postal-code, cc-number and the rest of the autofill field names. Browsers and password managers read the token and fill the field from data the user has already saved. WCAG success criterion 1.3.5 Identify Input Purpose, Level AA, asks that the purpose of such a field be programmatically determinable, and an autocomplete token is the technique W3C documents for meeting it.

Fields that collect anything else do not need a token. A search box, a quantity, a coupon code and a message body are all outside the vocabulary. A token the browser does not recognize is discarded, so a near miss such as firstname behaves exactly like no token at all.

What squirrel checks

The rule infers each field’s purpose from its name, id, associated <label> and placeholder, then compares the autocomplete value against that purpose. Only fields whose purpose is unambiguous count, so a field named capacity is never read as a city. It emits one check, autocomplete-tokens, at severity warning.

• Fail when a field carries a token that is not in the spec, or a token belonging to a different purpose. Report message: N field(s) carry the wrong autocomplete token, extended to N field(s) carry the wrong autocomplete token, M carry none when the page has both problems.
• Warn when an identified field has no token, or sets autocomplete="off" or autocomplete="on". Report message: N identified field(s) missing an autocomplete token.
• Pass with N identified field(s) carry the correct autocomplete token.
• Skipped with No name, email, phone, address or payment fields found when no field on the page has an identifiable purpose.

A country field is not always personal data. A locale or market switcher (for example a Shopify /localization form with country_code and locale_code selects) only changes the shop’s preferences, so a country field with no token, or with autocomplete="on" or "off", is skipped when it is the only personal-data field in its <form>. A field counts as personal data when it has a recognised name, email, phone, street address, city, state, postal code or payment purpose, a field named plain name, or a personal autocomplete token. A country field is still reported when:

• its form also holds one of those fields, for example an address form or a shipping estimator with a postal code
• it has no <form> ancestor
• it carries an autocomplete token that is not valid or not a country token

A country field with a valid country or country-name token passes in every form. Only the fields inside the same <form> element are considered: a field linked to a form through the form attribute is not. Hidden inputs and disabled fields never count. A form that collects only a country, such as a first checkout step, is not reported.

Each finding names the field with a CSS selector, quotes its opening tag and states the expected token, for example email field is tagged autocomplete="name" (expected "email").

How to fix it

<label for="ship-street">Address line 1</label>
<input id="ship-street" name="shippingAddressLine1" type="text"
       autocomplete="shipping address-line1">

The token goes on the field itself, never on the wrapper. Tokens accept the section-*, shipping/billing and home/work/mobile prefixes, so both shipping address-line1 and address-line1 satisfy the check.

autocomplete="off" is reported rather than accepted. It suppresses the browser’s ordinary autocomplete suggestions, but browsers and password managers make exceptions for credentials, so it is a poor way to keep a field out of autofill and a good way to lose the accurate kind.

Enable / disable

Disable this rule

[rules]
disable = ["a11y/autocomplete-tokens"]

Disable all Accessibility rules

[rules]
disable = ["a11y/*"]

Enable only this rule

[rules]
enable = ["a11y/autocomplete-tokens"]

enable replaces the default ["*"], so this is the only rule selected. Leave disable out: a rule that matches any disable pattern is skipped even when enable names it. Only an enabled setting under a rule’s own [rule_options] table overrides both lists.

Related rules

• a11y/form-labels: inputs, textareas and selects with no associated label.
• a11y/input-types: the other half of the same fix, type="email" next to autocomplete="email".
• a11y/aria-input-field-name: fields that have no accessible name at all.
• a11y/paste-inputs: fields whose onpaste, oncopy or oncut handler cancels the event.

Accessibility findings ship in every audit next to the SEO, performance and agent experience rules. See Website security scan with AI for how an agent works through a report.

Glossary: Form labels.

References

• The autocomplete attribute, MDN
• Autofill, HTML Standard
• Understanding SC 1.3.5 Identify Input Purpose, W3C

Check your site

Run squirrel audit https://example.com and open the Accessibility section of the report. Every field with a missing or mismatched token is listed with its expected value. Signed-out local audits need no account and cost nothing. Signed-in audits spend credits.