Forms Rule

The autocomplete attribute must use a valid value autocomplete-valid

The autocomplete attribute tells the browser what kind of information a field collects: a given name, a postcode, an email address. The browser can then offer to fill it in, and assistive tools can add an icon or read the purpose aloud. The value has to be one of the defined tokens, spelt exactly. autocomplete="postcode" is not a token; autocomplete="postal-code" is. A wrong value is silently ignored, so the help never arrives.

WCAG 2.2 AA 1.3.5 Identify Input Purpose

Websight reports this as autocomplete attribute must be used correctly

Who it affects

Someone with a tremor joining a gym online has to type their full address by hand because the form used autocomplete="address" instead of the real tokens, and the browser offered nothing.

Someone with dyslexia or a memory impairment misspells their own email address under pressure, when the browser could have filled it correctly in one tap.

Someone using a browser extension that adds icons to fields by purpose sees no icons because the purposes are not declared in a way the extension understands.

Broken versus fixed

The broken markup is shown as code rather than rendered, because the effect is in how it is announced or handled, not how it looks.

Broken
<label for="fn">First name</label>
<input id="fn" type="text" autocomplete="firstname">

<label for="pc">Postcode</label>
<input id="pc" type="text" autocomplete="postcode">

<label for="em">Email</label>
<input id="em" type="email" autocomplete="e-mail">

None of these three values exist, so the browser treats the fields as unknown and offers nothing.

Fixed
<label for="fn">First name</label>
<input id="fn" type="text" autocomplete="given-name">

<label for="pc">Postcode</label>
<input id="pc" type="text" autocomplete="postal-code">

<label for="em">Email</label>
<input id="em" type="email" autocomplete="email">

With the real tokens, the browser offers saved details for each field as soon as it gains focus.

Test it by hand in two minutes

  1. Right click each personal-details field and choose Inspect. Read the autocomplete value.
  2. Compare it against the token list in the HTML standard (search for "autocomplete tokens"). Common ones: name, given-name, family-name, email, tel, street-address, postal-code, country, bday, organization, username, current-password, new-password, cc-number.
  3. Click into the field in Chrome with a saved address or profile. A drop-down of saved values should appear. If it does not, the token is probably wrong or does not match the field type.
  4. Check the token suits the field. autocomplete="email" on a phone field is valid but wrong, and axe flags a token that cannot apply to that input type.

The fix

Before
<input id="pc" type="text" autocomplete="postcode">
After
<input id="pc" type="text" autocomplete="postal-code">

Tokens are lower case with hyphens, from a fixed list. When in doubt, copy the spelling from the HTML standard rather than guessing from the field name.

Shipping address group

Before
<input name="addr1" autocomplete="address">
<input name="town" autocomplete="town">
After
<input name="addr1" autocomplete="shipping address-line1">
<input name="town" autocomplete="shipping address-level2">

Tokens can be combined: shipping or billing first, then the field. address-level2 is the town or city in the UK.

Switching autofill off

Before
<input type="text" autocomplete="none">
After
<input type="text" autocomplete="off">

none is not a token. Use off, and only where there is a real reason, such as a one-time code.

Password fields

Before
<input type="password" autocomplete="password">
After
<input type="password" autocomplete="current-password">

password on its own is not a token. Use current-password on sign-in and new-password on sign-up or change-password forms.

Common mistakes

  • Inventing tokens from the field name: firstname, surname, postcode, mobile.
  • Using American spellings that are not in the list, or UK spellings for tokens that only exist one way (it is organization, not organisation).
  • Putting autocomplete="off" on every field by default, which removes help from people who rely on it.
  • Using a valid token on the wrong kind of field, such as cc-number on a textarea.
  • Writing tokens in the wrong order, such as address-line1 shipping instead of shipping address-line1.

WCAG criteria this rule maps to

axe-core tags this rule as WCAG 2.2 level AA. It is one of the checks for:

The scanner can see whether the autocomplete value is a valid token, in a valid order, and allowed on that type of field. It cannot tell whether the token you chose is the right one for what the field actually asks for. Automated tools find only part of the accessibility problems on a page; a pass on this rule is not a pass on the criterion.

A Form fields must have labels label Every input and textarea needs a label that is programmatically tied to it, not just sitting nearby. A Select menus must have an accessible name select-name A select element is a drop-down list of choices. A A form field should have one label, not several form-field-multiple-labels When two or more label elements have a for attribute pointing at the same field, screen readers have to pick. A ARIA input fields must have an accessible name aria-input-field-name When a div or span is given a form role such as textbox, combobox, listbox, slider or spinbutton, assistive technology treats it as a field.

Scan your own page for this and 63 other checks

Open any page in Chrome, click Websight, and get a score out of 100 with every issue explained and a draft fix snippet per element.

Add Websight to Chrome

Free scans, no account, nothing leaves your computer. Automated tools find only part of the problems; the extension says so on every report.