# autocomplete attribute must be used correctly

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

## Why This Matters

The `autocomplete` attribute does more than enable browser autofill — it programmatically communicates the *purpose* of a form field to assistive technologies. This information is critical for several groups of users:

- **Screen reader users** rely on the announced field purpose to understand what information is being requested. Without a valid `autocomplete` value, the screen reader may not convey this context clearly.
- **Users with cognitive disabilities** benefit from browsers and assistive tools that can auto-populate fields or display familiar icons based on the field's purpose, reducing the mental effort required to complete forms.
- **Users with mobility impairments** benefit from autofill functionality that minimizes the amount of manual input required.
- **Users with low vision** may use personalized stylesheets or browser extensions that adapt the presentation of form fields based on their declared purpose (e.g., showing a phone icon next to a telephone field).

This rule maps to **WCAG 2.1 Success Criterion 1.3.5: Identify Input Purpose (Level AA)**, which requires that the purpose of input fields collecting user information can be programmatically determined. The `autocomplete` attribute is the standard mechanism for satisfying this requirement in HTML.

## How the Rule Works

The axe rule `autocomplete-valid` checks that:

1. The `autocomplete` attribute value is a valid token (or combination of tokens) as defined in the [HTML specification for autofill](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofilling-form-controls:-the-autocomplete-attribute).
2. The value is appropriate for the type of form control it is applied to (e.g., `email` is used on an email-type input, not on a checkbox).
3. The tokens are correctly ordered when multiple tokens are used (e.g., a section name followed by a hint token followed by the field name).

The rule flags fields where the `autocomplete` value is misspelled, uses a non-existent token, or is applied in an invalid way.

## How to Fix It

1. **Identify all form fields** that collect personal user information (name, email, address, phone number, etc.).
2. **Check if the data type matches** one of the [53 input purposes defined in WCAG 2.1 Section 7](https://www.w3.org/TR/WCAG21/#input-purposes).
3. **Add the correct `autocomplete` value** to each matching field. Make sure:
   - The value is spelled correctly.
   - It is appropriate for the input type.
   - If using multiple tokens, they follow the correct order: optional section name (`section-*`), optional `shipping` or `billing`, optional `home`, `work`, `mobile`, `fax`, or `pager`, and then the autofill field name.
4. **Set `autocomplete="off"`** only when you have a legitimate reason to disable autofill — and note that this does not exempt you from the rule if the field still collects identifiable user data.

### Common `autocomplete` Values

Here are some of the most frequently used values:

| Purpose | `autocomplete` Value |
|---|---|
| Full name | `name` |
| Given (first) name | `given-name` |
| Family (last) name | `family-name` |
| Email address | `email` |
| Telephone number | `tel` |
| Street address | `street-address` |
| Postal code | `postal-code` |
| Country | `country` |
| Credit card number | `cc-number` |
| Username | `username` |
| New password | `new-password` |
| Current password | `current-password` |

## Examples

### Incorrect: Missing or Invalid `autocomplete` Values

```html
<!-- Missing autocomplete attribute entirely -->
<label for="name">Full Name</label>
<input type="text" id="name" name="name">

<!-- Misspelled autocomplete value -->
<label for="email">Email</label>
<input type="email" id="email" name="email" autocomplete="emal">

<!-- Invalid autocomplete value -->
<label for="phone">Phone</label>
<input type="tel" id="phone" name="phone" autocomplete="phone-number">
```

In the examples above, the first field has no `autocomplete` attribute, the second has a typo (`emal` instead of `email`), and the third uses a non-standard value (`phone-number` instead of `tel`).

### Correct: Valid `autocomplete` Values

```html
<label for="name">Full Name</label>
<input type="text" id="name" name="name" autocomplete="name">

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

<label for="phone">Phone</label>
<input type="tel" id="phone" name="phone" autocomplete="tel">
```

### Correct: Using Multiple Tokens

When a form has separate shipping and billing sections, you can use additional tokens to distinguish them:

```html
<fieldset>
  <legend>Shipping Address</legend>
  <label for="ship-street">Street Address</label>
  <input type="text" id="ship-street" name="ship-street"
    autocomplete="shipping street-address">

  <label for="ship-zip">Postal Code</label>
  <input type="text" id="ship-zip" name="ship-zip"
    autocomplete="shipping postal-code">
</fieldset>

<fieldset>
  <legend>Billing Address</legend>
  <label for="bill-street">Street Address</label>
  <input type="text" id="bill-street" name="bill-street"
    autocomplete="billing street-address">

  <label for="bill-zip">Postal Code</label>
  <input type="text" id="bill-zip" name="bill-zip"
    autocomplete="billing postal-code">
</fieldset>
```

### Correct: Named Sections with `section-*`

You can use custom section names to group related fields when the same type of data appears multiple times:

```html
<label for="home-tel">Home Phone</label>
<input type="tel" id="home-tel" name="home-tel"
  autocomplete="section-home tel">

<label for="work-tel">Work Phone</label>
<input type="tel" id="work-tel" name="work-tel"
  autocomplete="section-work tel">
```

By using valid, correctly applied `autocomplete` values, you ensure that assistive technologies can communicate the purpose of each field to users, browsers can offer reliable autofill, and your forms meet the requirements of WCAG 2.1 Success Criterion 1.3.5.