Email autocomplete attribute HTML form: Fix Email Autofill

Most lead forms lose more submissions to a half-filled email field than to any copy change. If you already have a working contact form, the email autocomplete attribute HTML form developers reach for is a one-line fix for a very specific annoyance: browsers refusing to fill the address a visitor has used a hundred times before. This guide walks field by field through the tokens browsers honor, why your email input still sits empty, and how to test the result after you connect the form to the Detected Form widget.

What the autocomplete attribute actually does

The autocomplete attribute is a hint. It tells the browser what kind of data a field expects, so the browser can offer a saved value from its own address book, contact picker or passkey store. It does not fetch anything from your server, and it does not guarantee a fill.

When the value is missing entirely, the browser treats the field as autocomplete="on" and guesses from the input's name, id, label text and surrounding context. When the value is unrecognized — say autocomplete="email-address" — browsers fall back to that same guessing behavior rather than throwing an error. That is why a typo looks like it works in one browser and silently does nothing in another.

A practical example of where this matters: a form posts its fields as name=value pairs, so the browser never sees your business logic, only the control names (how browsers send form data). The autocomplete token and the name attribute are the only signals the browser has when it decides whether to fill.

The token you want for email

For a single email input, use:

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

Three things to keep straight:

• email versus username. Use username on a login name field, even when that login happens to be an email address. Use email on contact and lead forms, where you are collecting an address to reply to. Mixing them makes password managers offer the wrong saved identity.
• Single versus multiple. If the field accepts a comma-separated list, add multiple to the autocomplete value and keep multiple on the input too. The type="email" validation then checks a comma-separated list rather than one address (client-side form validation).
• type="email" is not a replacement. The input type drives validation and mobile keyboards; the token drives filling. You want both.

Why email autofill fails in practice

Four causes cover almost every case I have debugged.

1. No name attribute. An input with only an id still submits nothing useful, and browsers weight name heavily when guessing. If you set a token, keep a sensible name beside it.
2. Label wording that fights the token. A field labelled "Where should we send the invoice?" with name="field_4" gives the browser nothing to match. The token wins only when the surrounding clues agree with it.
3. The address split across two inputs. A local part box plus a domain dropdown cannot hold a saved address. Offer one field, or accept that autofill will fail.
4. Shadow-DOM and third-party wrappers. If the input lives inside a widget's closed shadow root, browser autofill may not reach it. Check what the real <input> is before blaming the token.

This is the same class of problem covered in the existing guide to setting autocomplete="off" on contact form fields deliberately: turning autofill off rarely fixes a broken token, and usually removes a convenience your visitors wanted (autocomplete off contact form fields).

Field-by-field token reference

Field	Suggested token	Notes
Email	email	Add multiple only for lists
Full name	name	Or given-name / family-name if split
Organisation	organization	Spell it with a z
Phone	tel	Add tel-national only if you do not want the country code
Street address	street-address	One textarea or input; avoid splitting into house number and street
Postal code	postal-code	Pair with country if you have a country field
Message box	omit	Free-form comments have no token; leave it unset
Hidden field	omit	Adding a token to a hidden input invites confusing fills

Omit autocomplete entirely when no token fits. An invented value is treated as autocomplete="on", which is worse than asking nothing.

Validation interplay: keep the error path working

Client-side validation is an initial check, and it should not be treated as a security measure — server-side checks are still required (MDN form validation rationale). When a browser fills a value programmatically, some scripts do not fire the same events as typed input, so your inline error text may not clear or re-fire until the next keystroke or submit.

Practical checks:

• Keep type="email" and required on the input; do not swap to a plain text input to "make autofill work".
• Test by autofilling, then submitting immediately without touching any key. Confirm the error message appears and disappears correctly.
• If you display a custom error, tie it to the field with an aria-describedby reference and re-run the check by keyboard.
• Watch :invalid styling: a freshly filled value can flash a red border before your script clears the error. The existing guide on writing messages that help visitors fix and resubmit is a good companion read (contact form error messages).

The privacy-sensitive cases

Two field types need care:

• One-time codes. Never give a security code an email or tel token. If you use a token at all, use one-time-code, and only on the code input itself.
• Passwords. Never store, log or pass password values into a form widget or a third-party embed. If a field holds a secret, it should not be inside a detected-form payload.

Setting autocomplete="off" across a whole form as a default is a common over-correction. Do it per field, deliberately, and only where the browser would otherwise offer the wrong value.

Test script after installing the Detected Form embed

The Detected Form widget connects an HTML form you already run to WidgetJar; it does not replace your form's markup, so your tokens and names stay in your control. Once you install the WidgetJar embed script on your registered domain and point it at the form, run this sequence:

1. Desktop Chrome: load the page in a fresh profile, click the email field, and confirm the contact picker offers an address. Submit via autofill only.
2. Desktop Safari and Firefox: repeat. Note whether the fill reaches the field at all, then whether the submitted payload reaches your detected form handler.
3. Mobile: test the keyboard's contact suggestion on both iOS and Android for the email, phone and name fields.
4. Payload check: confirm the field names you see in your handler match the name attributes, including the email field.
5. Keyboard and screen reader: tab through the form without a mouse and confirm labels and error text are announced after an autofill.
6. Edge case: submit with a deliberately malformed address to confirm your type="email" message still fires.

If you are adding consent capture at the same time, keep it outside the autofilled fields and read the consent checkbox walkthrough before launch (adding a consent checkbox to an existing form).

Ship the fix

Start with the email field: one token, one honest name, one clear label. Then extend the same discipline across name, organisation, phone and address, and re-test with a real autofill rather than typed input on each browser you care about.

When you are ready to route those submissions somewhere useful, connect your existing form with the Detected Form widget — install the embed, select the form, and verify the email field arrives exactly as the visitor autofilled it.