Skip to content
FEE
Frontend Engineering Essentials
Mid Level

[FEE-113] Autocomplete Attribute Token Reference ​

INFO

The HTML autocomplete attribute accepts a space-separated list of tokens drawn from a strict ordered grammar: optional section-*, optional shipping or billing, optional contact type, a required field-name, and an optional webauthn credential hint. Only the field-name token is mandatory; the others, when present, MUST appear in the prescribed order. Adding webauthn alongside username turns an <input> into an entry point for passkey Conditional UI when paired with navigator.credentials.get({ mediation: 'conditional' }). This reference catalogs every field-name token, explains the grouping prefixes, and documents the passkey integration.

Context ​

The WHATWG HTML Living Standard defines autocomplete as a space-separated token list with a strict ordering: [section-*] [shipping|billing] [home|work|mobile|fax|pager] field-name [webauthn]. The spec states the structure as "Optional section prefix: section-*; Optional mode: shipping or billing; Optional contact type: home, work, mobile, fax, or pager; Field name (required); Optional credential type: webauthn."

Tokens written out of order fall outside the grammar and the browser treats the attribute as autofill-unspecified, silently losing the semantic hints. The field-name token carries the meaningful signal; the surrounding tokens refine which address, which phone, or which account context the field belongs to.

Visual ​

PositionToken familyRequiredAllowed values
1Section prefixNoAny section-* token (case-insensitive; suffix is arbitrary)
2Address modeNoshipping, billing
3Contact typeNohome, work, mobile, fax, pager
4Field nameYesOne token from the field-name catalog (see Token Reference)
5Credential typeNowebauthn

Example ​

A minimal single-field autofill hint uses only the field-name token:

html
<label>
  First name
  <input type="text" name="first" autocomplete="given-name" />
</label>

A grouped form uses the section-* prefix so the browser can keep two address blocks distinct on the same page, combined with a mode qualifier:

html
<fieldset>
  <legend>Primary billing address</legend>
  <input autocomplete="section-user1 billing postal-code" name="billing-zip" />
  <input autocomplete="section-user1 billing country" name="billing-country" />
</fieldset>

<fieldset>
  <legend>Secondary billing address</legend>
  <input autocomplete="section-user2 billing postal-code" name="alt-billing-zip" />
  <input autocomplete="section-user2 billing country" name="alt-billing-country" />
</fieldset>

A sign-in field that participates in passkey Conditional UI carries both username and webauthn, then the page calls navigator.credentials.get() with conditional mediation so the request stays pending until the user picks a credential from the autofill menu:

html
<form id="login">
  <label>
    Username
    <input name="username" autocomplete="username webauthn" />
  </label>
  <label>
    Password
    <input name="password" type="password" autocomplete="current-password" />
  </label>
</form>
js
if (window.PublicKeyCredential &&
    PublicKeyCredential.isConditionalMediationAvailable) {
  const available = await PublicKeyCredential.isConditionalMediationAvailable();
  if (available) {
    const credential = await navigator.credentials.get({
      mediation: 'conditional',
      publicKey: {
        challenge: new Uint8Array(challengeFromServer),
        // allowCredentials left empty for discoverable credentials
      },
    });
    // The promise stays pending until the user picks a passkey in the autofill sheet.
    verifyOnServer(credential);
  }
}

Best Practices ​

  • MUST pair autocomplete="username" on the identifier field with autocomplete="current-password" on the password field for sign-in forms. web.dev documents that username is the token password managers recognize on email-shaped identifier fields in modern browsers, and current-password is the pair on the password input.
  • MUST use autocomplete="new-password" on signup and password-change fields so password managers suggest generated credentials and avoid autofilling the current password. MDN: "A new password. When creating a new account or changing passwords, this should be used for an 'Enter your new password' or 'Confirm new password' field."
  • SHOULD prefer autocomplete="new-password" over autocomplete="off" when suppressing autofill on an admin-sets-other-user-password page. MDN's security guide notes: "If you are defining a user management page where a user can specify a new password for another person, and therefore, you want to prevent autofilling of password fields, you can use autocomplete=\"new-password\"."
  • SHOULD treat autocomplete="off" as a non-binding request on credential fields. MDN states: "If a site sets autocomplete=\"off\" on a <form> element and the form includes username and password input fields, the browser will still offer to remember this login." Password managers deliberately override off on login flows, so relying on off for security is not workable.
  • MAY combine the section-*, shipping or billing, and contact-type tokens to distinguish multiple address blocks or phone slots within the same page.

Deep Dive ​

Tokens are only one of the signals a browser consults. Safari in particular layers heuristics over the input's name, placeholder, and label in that order. Cloudfour's autofill writeup records: "Safari uses heuristics to detect what autofill values to use and it's very aggressive in doing so. Rather than simply relying on standardized attributes, Safari evaluates the input's attributes in this order: name, placeholder, and label."

The practical consequence: a field with autocomplete="one-time-code" but name="email" can still trigger email autofill in Safari, because the heuristic outranks the token. Defensive authors keep name attributes semantically aligned with the field-name token (name="otp" for autocomplete="one-time-code", name="current-password" for autocomplete="current-password"), and avoid placeholders that describe a different field than the token declares.

Token Reference ​

The field-name token is drawn from the WHATWG catalog. The following tables group the tokens by domain. Every token is case-insensitive and appears in MDN's reference list.

Identity ​

TokenExpected formatNotes
nameFull legal namePrefer split name tokens where possible
honorific-prefix"Mr.", "Ms.", "Dr."
given-nameFirst name
additional-nameMiddle name
family-nameLast name
honorific-suffix"Jr.", "III", "PhD"
nicknameDisplay name
usernameAccount identifierPair with current-password for login; required for passkey Conditional UI
organization-titleJob title
organizationCompany name

Credentials ​

TokenExpected formatNotes
new-passwordPlaintext passwordUsed for signup and password-change flows; also the recommended suppression hint
current-passwordPlaintext passwordLogin flows; pair with username
one-time-codeNumeric OTPiOS/macOS Safari 12+ parses incoming SMS and offers the code as a keyboard suggestion; Android Chrome uses the separate WebOTP API

Contact ​

TokenExpected formatNotes
telFull phone numberCombine with home/work/mobile/fax/pager to qualify
tel-country-code"+1", "+44"
tel-nationalNational-format phone
tel-area-codeArea code
tel-localLocal portion
tel-extensionExtension digits
emailEmail addressCombine with home/work to qualify
imppInstant-messaging URL
urlHomepage URL
photoAvatar URL

Postal address ​

TokenExpected formatNotes
street-addressMulti-line street address
address-line1First street line
address-line2Second street line
address-line3Third street line
address-level4Finest administrative level
address-level3Third-level administrative area
address-level2City or locality
address-level1State or province
countryISO 3166-1 alpha-2 country code
country-nameHuman-readable country name
postal-codeZIP or postal code

Payment ​

TokenExpected formatNotes
cc-nameName on card
cc-given-nameFirst name on card
cc-additional-nameMiddle name on card
cc-family-nameLast name on card
cc-numberCard number
cc-expExpiration in MM/YY or MM/YYYY
cc-exp-monthExpiration month digits
cc-exp-yearExpiration year digits
cc-cscCard security code
cc-typeCard network name

Transaction ​

TokenExpected formatNotes
transaction-currencyISO 4217 currency code
transaction-amountDecimal amount

Demographics ​

TokenExpected formatNotes
bdayYYYY-MM-DD
bday-dayDay digits
bday-monthMonth digits
bday-yearYear digits
sexFree-form string
languageBCP 47 language tag

The section-*, shipping, billing, and contact-type tokens do not replace field-name tokens; they layer on top. MDN describes the section token as "A token whose first eight characters are the string 'section-', case-insensitive, followed by additional characters. All form controls that start with the same token belong to the named group." The mode tokens bind what follows: "shipping: The field identified by subsequent tokens is part of the shipping address or contact information. billing: The field identified by subsequent tokens is part of the billing address or contact information." The contact-type tokens (home, work, mobile, fax, pager) qualify telephone and email fields.

Passkey Conditional UI (webauthn token) ​

The webauthn token is the trailing credential hint in the grammar. The WHATWG spec describes it as "Optionally, a token...for the string 'webauthn', meaning the user agent should show public key credentials available via conditional mediation...webauthn is only valid for input and textarea elements." In practice the token matters only on <input>, because Conditional UI surfaces passkeys alongside the standard autofill menu for username fields.

When to use it: any sign-in or account-recovery page that supports passkeys. The integration is two-part. The HTML carries both tokens, space-separated:

html
<input name="username" autocomplete="username webauthn" />

The script calls navigator.credentials.get() with mediation: 'conditional'. web.dev documents the behavior: "The navigator.credentials.get() call with mediation: 'conditional' remains pending and does not show any UI on its own." The promise resolves only when the user selects a passkey from the autofill sheet; until then the page remains ready to accept a typed username and password instead.

Limitations and browser support:

  • webauthn has no effect on <textarea> per the spec, even though the grammar technically accepts both element types.
  • The token is ignored when paired with one-time-code, because an OTP field is not a credential-carrying field.
  • Firefox added explicit recognition of the webauthn autocomplete token in version 122 (January 2024). Chrome, Edge, and Safari support Conditional UI as of 2025.
  • Feature-detect with PublicKeyCredential.isConditionalMediationAvailable() before calling navigator.credentials.get(), so older browsers fall through to the username+password flow without a runtime error.

References ​