# Autocomplete attribute must use valid values from the HTML specification.

> Canonical HTML version: https://rocketvalidator.com/accessibility-validation/accesslint/0.16/adaptable/autocomplete-valid
> Attribution: Rocket Validator (https://rocketvalidator.com)
> License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

The `autocomplete` attribute tells browsers and assistive technologies what kind of data a form field expects. When this attribute contains invalid values, browsers cannot offer autofill suggestions, and assistive technologies cannot identify the purpose of the input. This rule checks that every `autocomplete` value on `input`, `select`, and `textarea` elements uses tokens defined in the HTML specification.

## Who is affected and why

People with cognitive disabilities often have difficulty filling out forms. When `autocomplete` values are correct, assistive technologies can label fields with familiar icons, rearrange layouts, or pre-fill known data, all of which reduce cognitive load. People with motor impairments also benefit because autofill means fewer keystrokes and less precise interaction. And for anyone using a password manager or browser autofill, valid `autocomplete` values are what make those tools work.

Invalid values silently break all of this. The browser does not throw an error; it simply ignores the attribute. The user gets no autofill, no icon hints, and no personalization.

## WCAG success criterion

This rule maps to [WCAG 1.3.5 Identify Input Purpose](https://www.w3.org/WAI/WCAG21/Understanding/identify-input-purpose.html) (Level AA). That criterion requires that the purpose of each form field collecting user information can be programmatically determined. Using valid `autocomplete` tokens is the primary technique for meeting this requirement in HTML.

## How valid values are structured

The `autocomplete` attribute accepts a space-separated list of tokens in a specific order:

1. An optional token starting with `section-` (e.g., `section-billing`), used to group related fields.
2. An optional `shipping` or `billing` token.
3. An optional contact type: `home`, `work`, `mobile`, `fax`, or `pager`. This token is only allowed when the next token is `email`, `impp`, `tel`, or a token starting with `tel-`.
4. A required autofill field name such as `name`, `email`, `username`, `street-address`, `postal-code`, `cc-number`, `bday`, etc.
5. An optional `webauthn` token.

The full list of valid autofill field names is in the [HTML specification's autofill section](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill).

## When this rule does not apply

The rule does not flag the following cases:

- The `autocomplete` value is `on` or `off` (these are toggle values, not autofill tokens).
- The element is disabled.
- The `input` type is `button`, `checkbox`, `file`, `image`, `radio`, `reset`, or `submit` (these have fixed values and do not collect user data).
- The element is not visible and not in the accessibility tree.
- The element is not focusable and does not have a widget role.

## How to fix it

1. Check each `autocomplete` value against the list of valid tokens in the HTML specification.
2. Fix typos and remove invented values. For example, `autocomplete="mail"` is not valid; use `autocomplete="email"`.
3. Make sure tokens appear in the correct order. A contact type like `work` must come immediately before `email`, `tel`, `impp`, or a `tel-*` token.
4. Match the `autocomplete` value to the `input` type. For example, `autocomplete="email"` belongs on an `input` with `type="email"` or `type="text"`, not on `type="number"`.

## Examples

### Incorrect: invalid autocomplete value

The value `mail` is not a recognized autofill token.

```html
<label for="user-email">Email</label>
<input id="user-email" type="email" autocomplete="mail">
```

### Incorrect: tokens in the wrong order

The contact type `work` must come before `email`, not after it.

```html
<label for="work-email">Work email</label>
<input id="work-email" type="email" autocomplete="email work">
```

### Correct: valid autocomplete value

```html
<label for="user-email">Email</label>
<input id="user-email" type="email" autocomplete="email">
```

### Correct: multiple tokens in the right order

```html
<label for="work-email">Work email</label>
<input id="work-email" type="email" autocomplete="work email">
```

### Correct: section grouping with billing

```html
<label for="billing-zip">Billing ZIP code</label>
<input id="billing-zip" type="text" autocomplete="section-billing billing postal-code">
```

### Correct: autocomplete turned off

Turning off autocomplete with the `off` token is valid and is not flagged by this rule.

```html
<label for="otp">One-time passcode</label>
<input id="otp" type="text" autocomplete="off">
```