Autofill Tokens and the Purpose of an Input

A field labelled “Line 1” tells a human what to type. It does not tell software anything. The label is a string for a person; the browser sees an <input> with a name and a type, and the type says only what characters are acceptable, not what the characters mean. A field expecting a street address and a field expecting a company name are both <input type="text">, and no amount of label text changes that.

The autocomplete attribute is the mechanism that closes the gap. It is a closed vocabulary of tokens, each naming one piece of personal or transactional data, and the browser maps tokens to its stored profile fields. Once the mapping exists, three things become possible that are otherwise impossible: the browser can fill the field from saved data, the platform can expose the field’s purpose to assistive technology, and the field can be recognised by the same purpose across sites that use completely different markup.

The token grammar

The attribute value is a space-separated list of tokens with a fixed structure: an optional group name of the form section-*, an optional address scope, an optional contact qualifier, a field name, and an optional webauthn suffix. The order matters and the vocabulary is closed: an unrecognised token makes the whole value invalid, which means the attribute is treated as if it were absent.

The scope is shipping or billing, applying to address fields. The qualifier is home, work, mobile, fax, or pager, applying to contact fields. Then the field name, from a set that covers names, addresses, contact details, payment instruments, and a handful of others such as username, current-password, new-password, and one-time-code. The field names themselves include street-address and the fragment forms address-line1, address-line2, and address-line3, alongside postal-code, country, and country-name.

The group name is the part that separates two addresses of the same kind in one form. A page collecting a billing address and a delivery address uses section-a and section-b prefixes, and the browser keeps the groups apart when filling.

Some examples with their full expansion:

<input name="fname" autocomplete="given-name">
<input name="lname" autocomplete="family-name">
<input name="addr1" autocomplete="shipping address-line1">
<input name="tel"   autocomplete="home tel">
<input name="cc"    autocomplete="cc-number">
<input name="pin"   autocomplete="one-time-code">

The multi-line address case is the one that most often goes wrong. street-address names an address that may legitimately be entered as a single multi-line text box, so a form with three separate inputs must use address-line1, address-line2, and address-line3 rather than repeating street-address three times. Repeating the token across fields that hold different fragments of the same address gives the browser three targets for one profile value and no way to choose.

What consumes the attribute

The browser’s own form-fill machinery is the primary consumer. A profile stored with a name, an email, two addresses, and a card is indexed by exactly these tokens; the fill operation walks the form’s fields, reads each field’s token, and writes the matching profile value. This is why a field with autocomplete="email" fills correctly even when its name attribute is field_7 and its label says “Your electronic mail”, while a field with a perfect label and no attribute fills only if the browser’s heuristics guess its purpose from the surrounding text.

The second consumer is the platform accessibility layer. A control carrying a recognised token has that purpose exposed in its accessibility properties, and assistive technology can use it. The practical effect is that a field can be announced with its purpose rather than only its label, and tools that build a structured view of a form, such as a personal-data manager reading the fields a page is asking for, can identify them without parsing prose.

The third consumer is the specification’s own conformance requirement. WCAG 1.3.5, Identify Input Purpose, requires that the purpose of fields collecting information about the user be programmatically determinable, and the technique for it is this attribute. That criterion applies to a defined set of purposes: the fields whose meaning is about the person filling the form. A search box or a quantity field is outside its scope, and autocomplete has no token for either.

Why the vocabulary is closed

An open attribute, one where any string identifies a purpose, would be more expressive and much less useful. Browsers cannot fill a field whose purpose they have never seen; a token invented by one site is meaningless to every other. The value of the mechanism is exactly that a site cannot invent: autocomplete="customer-reference" is invalid, and the browser ignores it, which keeps the namespace from filling with per-site dialects.

The cost of the closure is that fields outside the enumerated set have no way to declare their purpose. There is no token for a policy number, a licence plate, a booking reference, or a delivery instruction. Those fields must rely on their label, and no attribute will let a browser fill them. That asymmetry is deliberate: autofill exists for data the user already has stored, and the stored data is the small set of facts a browser profile holds.

The vocabulary is also versioned by the HTML specification rather than by any browser, and browsers implement subsets. A token added to the specification is not immediately recognised by every engine, and the failure is silent: the field simply does not autofill. This is the reason a form should not depend on autofill for correctness: the token describes intent, and the form must work when nothing fills.

Interaction with field type, name, and label

Three other signals compete with the token, and their relative weight is not standardised.

The type attribute is the strongest constraint on what can be typed, not on what is meant. type="email" restricts the value to a syntactically valid address and brings up an email-oriented keyboard on touch devices; it does not say whether the address is the user’s own or a recipient’s. autocomplete="email" says it is the user’s own. A field with both is unambiguous; a field with only the type may be filled with the wrong address, or not filled at all.

The name attribute is a heuristic input. Browsers guess purpose from names like email, zip, and cc-number, and the guesses are usually right for forms that follow convention and wrong for forms that do not. Adding a correct token overrides the guess, which is one reason to add it even when the name already looks right: it removes the guess.

The label is the signal that a human reads and a browser may also read. A label of “Email” with autocomplete="email" is consistent; a label of “Recipient email” with autocomplete="email" is contradictory, and the browser will fill the user’s own address into a field meant for someone else. This mismatch is invisible in testing with an empty profile, which is why it is a common defect in forms that were built without autofill enabled.

Failure modes

Four failures recur and each has a distinct cause.

A form that disables autofill wholesale removes the tokens along with the behaviour. The common implementation is autocomplete="off" on the form element, which suppresses the browser’s fill for every field beneath it, including fields that carry valid tokens. Browsers have narrowed the effect of off over time, and password managers in particular may ignore it, but the suppression is real for ordinary profile fields, and the accessibility consequence is that the purposes become unavailable along with the fill.

A form that reuses one token for several fields breaks the mapping. Two fields both marked autocomplete="email", one for the account address and one for a confirmation, give the browser two identical targets, and the fill may write the same value into both or neither. The correct markup for a confirmation field is a separate id and name with the same token only if the semantics really are identical; usually the confirmation should have no token, because it is not a separate fact about the user.

A form that puts the token on a wrapper rather than the control has no effect. The attribute is defined on input, select, and textarea; on a div around them it is inert. Component libraries that accept an autocomplete prop and forward it to the outer element produce exactly this.

A form that builds the attribute dynamically from a value that may be empty produces autocomplete="", which is invalid and treated as absent. A token that is empty string is not the same as a token that is omitted only in that it silently discards a purpose the developer intended to set.

Where the attribute stops

The attribute says nothing about format, validity, or requiredness. It is metadata about meaning, and the validation machinery is entirely separate; the native constraint API is described in Native Constraint Validation and ValidityState. A field with autocomplete="postal-code" still needs a label, and the label still needs to state the format where the format is not universal.

Nor does the token replace a group name. A shipping address is often a fieldset with a legend, and the individual fields inside carry the address tokens; the two mechanisms are complementary, and the group naming is covered in Fieldset and Legend Group Semantics. A token on each field does not tell the user that the set of fields is one address, and a legend does not tell the browser which part of the address each field holds.

The attribute’s real value is that it is the only declarative statement of a field’s meaning that survives a change of label text, a change of language, and a change of layout. Everything else about a field is presentation; the token is the semantic claim.