Autofill is the biggest single accessibility and speed improvement most forms can get for free — and most forms get it wrong: fields without autocomplete, invented values like autocomplete="email-address", autocomplete="off" on a login, or a shipping and billing address that browsers fill with the same data because nothing tells them apart.

The autocomplete attribute takes a defined set of tokens from the HTML specification. Correct tokens let browsers and password managers fill fields accurately, let people with motor and cognitive disabilities avoid retyping personal data, and satisfy WCAG 2.1’s “Identify Input Purpose” criterion (1.3.5, AA). This page, part of keyboard navigation patterns, lists the tokens forms need and how to combine them.

Context and prerequisites

The attribute’s grammar, in order:

  1. Optional section: section-<name> — groups fields that belong together when a page has several of the same kind (two addresses in different blocks).
  2. Optional group: shipping or billing — distinguishes addresses and contact details by purpose.
  3. Optional contact type (for contact fields): home, work, mobile, fax, pager.
  4. The field name token (required): name, email, tel, street-address, postal-code, cc-number, current-password, …
  5. Optional webauthn — appended for passkey conditional UI on username or password fields.

Example: autocomplete="shipping postal-code", autocomplete="work email", autocomplete="section-guest2 shipping address-line1".

autocomplete="off" asks the browser not to store or suggest; browsers largely ignore it for login fields, and it should be used only for fields where suggestions are genuinely wrong (a one-time search box, a CAPTCHA answer).

The tokens most forms need For identity, full name uses name, and given and family names use given-name and family-name. For contact, email uses email and phone uses tel. For addresses, the first and second lines use address-line1 and address-line2, the town uses address-level2, the postcode uses postal-code and the country uses country-name or country. For organisations, company uses organization. For credentials, the login username uses username, the login password uses current-password and a new password uses new-password, with one-time-code for verification codes. For payment, card number uses cc-number, name on card uses cc-name, expiry uses cc-exp and the security code uses cc-csc. Date of birth uses bday. Field Token Full name / given / family name / given-name / family-name Email / phone email / tel Address lines address-line1, address-line2 Town / postcode / country address-level2 / postal-code / country-name Company organization Login username / password username / current-password New password / verification code new-password / one-time-code Card number, name, expiry, CVC cc-number, cc-name, cc-exp, cc-csc Date of birth bday (or bday-day, bday-month, bday-year)

The core pattern: a checkout form with correct tokens

<form>
  <fieldset>
    <legend>Contact details</legend>
    <label for="c-name">Full name</label>
    <input id="c-name" name="name" autocomplete="name">
    <label for="c-email">Email address</label>
    <input id="c-email" name="email" type="email" autocomplete="email">
    <label for="c-tel">Mobile number</label>
    <input id="c-tel" name="tel" type="tel" autocomplete="mobile tel">
  </fieldset>

  <fieldset>
    <legend>Delivery address</legend>
    <label for="s-line1">Address line 1</label>
    <input id="s-line1" name="ship-line1" autocomplete="shipping address-line1">
    <label for="s-line2">Address line 2 (optional)</label>
    <input id="s-line2" name="ship-line2" autocomplete="shipping address-line2">
    <label for="s-town">Town or city</label>
    <input id="s-town" name="ship-town" autocomplete="shipping address-level2">
    <label for="s-postcode">Postcode</label>
    <input id="s-postcode" name="ship-postcode" autocomplete="shipping postal-code">
    <label for="s-country">Country</label>
    <select id="s-country" name="ship-country" autocomplete="shipping country"><!-- ISO codes as values --></select>
  </fieldset>

  <fieldset>
    <legend>Payment</legend>
    <label for="cc-name">Name on card</label>
    <input id="cc-name" name="cc-name" autocomplete="cc-name">
    <label for="cc-number">Card number</label>
    <input id="cc-number" name="cc-number" inputmode="numeric" autocomplete="cc-number">
    <label for="cc-exp">Expiry date (MM/YY)</label>
    <input id="cc-exp" name="cc-exp" inputmode="numeric" autocomplete="cc-exp">
    <label for="cc-csc">Security code</label>
    <input id="cc-csc" name="cc-csc" inputmode="numeric" autocomplete="cc-csc">
  </fieldset>
</form>

Step-by-step walkthrough

  1. Give every personal-data field a token. WCAG 1.3.5 applies to fields collecting information about the user; a correct token is how you meet it.
  2. Use the exact spec tokens. email, not e-mail or emailAddress; postal-code, not zip. Unknown values are ignored as if no attribute were present.
  3. Match field granularity to the token. One “Full name” field gets name; separate fields get given-name and family-name. A single address textarea gets street-address; separate lines get address-line1/address-line2.
  4. Prefix with shipping/billing when both appear. Otherwise browsers may fill both blocks with the same saved address.
  5. Use section-* for repeated blocks. Multiple guests’ names on one page: section-guest1 name, section-guest2 name.
  6. Pair credential tokens with the right input types. username + current-password on login; new-password on sign-up and password change, which triggers password generation. Reconcile filled values at submit, as in handling browser autofill in controlled inputs.

Why autofill is an accessibility feature

For a person using a switch, a head pointer or voice control, every character typed costs time and effort; filling a full address by hand can take minutes. For people with memory or cognitive impairments, recalling a postcode or card expiry may be genuinely hard. Correct autocomplete tokens turn those minutes into one selection from the browser’s suggestion list. They also allow assistive technologies to present fields with familiar icons or symbols — the “input purpose” WCAG 1.3.5 is named for. None of this requires JavaScript or design changes; it is one attribute per field, and it is one of the highest-value accessibility fixes available in most forms.

Building an autocomplete value An autocomplete value is built from an optional section name such as section-guest2, an optional group such as shipping or billing, an optional contact type such as work or mobile for contact fields, and the required field token such as tel or postal-code. For example, section-guest2 shipping tel, or work email. section-* Optional. section-guest2 shipping | billing Optional. Tells addresses apart. home | work | mobile Optional, contact fields. mobile tel field token Required. postal-code, email…

Designing fields so autofill has something to match

Tokens only help when the form’s structure matches the data browsers store. Browsers keep addresses as a small set of parts — lines, town, region, postcode, country — and names as given, additional and family names. A form that asks for “House number” and “Street” separately, or “First name” and “Surname” when the audience includes people with a single name, forces the browser to guess, and it often guesses wrong or not at all. Where you can, follow the stored shape: address lines rather than house number and street, a single “Full name” field unless you genuinely need the parts, and a country select whose values are ISO codes.

When business requirements do demand unusual granularity, keep autofill working for the fields that do match and accept that the rest will be typed. Do not reuse a token on a field that means something different — marking “House name” as address-line1 fills it with a street address, which is worse than filling nothing.

Order matters too. Browsers fill a whole group at once when the user selects a saved address, and they use the relative position of fields as a hint. Grouping all address fields together, in the conventional order, inside one fieldset with a clear legend, makes a single autofill selection complete the whole block, which is the experience that saves users the most effort.

Finally, test autofill in the browsers your users have. Save a test profile with a name, email, phone and two addresses in Chrome, Safari and Firefox, fill the form from each, and check that every field receives the right part — and that shipping and billing blocks receive the addresses you chose for them.

Failure modes and edge cases

1. autocomplete="off" on login forms

Browsers ignore it for credentials to protect password-manager users, and where it is honoured it pushes people toward weak, memorable passwords. Leave credential fields fillable.

2. Invented tokens

autocomplete="address" or "postcode" do nothing. Validators such as the W3C HTML checker and axe flag invalid tokens; include one in CI.

3. Hidden fields that get filled

Browsers may fill hidden address fields (address line 2, company) that your form hides behind a toggle. Decide what happens to hidden-but-filled values with the relevance rules from what happens to errors when a field is hidden.

4. Country as free text

Browsers fill country with an ISO code and country-name with a localised name. Use a select with ISO codes as values and autocomplete="country", or accept the name with country-name and normalise server-side.

5. Custom components

Autocomplete only works on native form controls the browser recognises. A custom select or a web component must render a native input (or be form-associated with an inner input carrying the token) to be fillable, as in building Lit form controls with ElementInternals.

Common mistakes and their fixes autocomplete email-address is invalid and ignored; use email. autocomplete zip is invalid; use postal-code. autocomplete off on a password field is ignored and discourages password managers; remove it or use current-password. The same token on shipping and billing addresses causes both to be filled identically; prefix with shipping and billing. A new password field marked current-password prevents password generation; use new-password. Mistake Effect Fix "email-address" ignored email "zip" ignored postal-code "off" on password ignored / harmful current-password same tokens on both addresses both filled alike shipping / billing prefixes sign-up uses current-password no password generation new-password

Verification checklist

Frequently Asked Questions

Does autocomplete affect validation?

No — it only guides filling. Autofilled values still need validation, and some arrive without the input events your code expects; reconcile at submit.

Should the name attribute match the token?

It helps browsers’ heuristics but is not required; the autocomplete token is authoritative. Use clear, stable name values for your server and correct tokens for autofill.

What about passkeys?

Add webauthn to the username field’s token (autocomplete="username webauthn") to enable conditional passkey UI, where the browser offers saved passkeys in the autofill menu. Keep the password field for users without passkeys.

Related

← Keyboard Navigation Patterns