Autofill event

at a glance

why it exists

Address forms are dynamic almost by definition — different countries need different fields — but browser autofill historically assumed a static form. The “industry standard” workaround is hidden form fields that try to anticipate and capture the right information, which is brittle and entrenches a technique that bad actors also abuse. The autofill event fires before values are committed, so a page can inspect what the browser intends to fill, restructure the form to match (add a state selector for a US address, say), and call refill() to have the browser fill the updated form — without hidden fields or implementation-specific hacks.

syntax

Quoted verbatim from the IDL in spec §3 (Draft CG Report, 25 September 2026). This is the draft shape, not the pinned Chromium IDL linked in the warning above:

[Exposed=Window]
interface AutofillEvent : Event {
  constructor(DOMString type, optional AutofillEventInit eventInitDict = {});
  readonly attribute FrozenArray<AutofillValueEntry> autofillValues;
  readonly attribute RefillCallback? refill;
};

callback RefillCallback = Promise<undefined> ();

dictionary AutofillEventInit : EventInit {
  sequence<AutofillValueEntry> autofillValues = [];
  boolean allowRefill = true;
};

typedef sequence<any> AutofillValueEntry;
// AutofillValueEntry is a tuple of [HTMLElement, DOMString]
// where the first element is the form control and the second is the value to fill

autofillValues

In the WICG draft, each entry is a tuple whose first element is the HTMLElement (the form control that will receive the value) and whose second is the DOMString value from the user’s autofill profile. Pinned Chromium instead declares an AutofillFieldData dictionary with field and value members; tuple destructuring below is draft-only. The browser matches controls to autofill data via the control’s autocomplete attribute (HTML autofill field names), and may also use implementation-defined heuristics. The spec does not guarantee the element actually holds that value after the fill.

refill

A RefillCallback or null. When not null, calling it signals that the page has modified the form structure and the browser should re-match the user’s autofill data against the modified form and fire a second autofill event, then fill. It returns a Promise<undefined>. Per spec §4.2, the promise is rejected with an "InvalidStateError" DOMException when: more than an implementation-defined refillTimeout has elapsed since the event was dispatched; the event’s allow refill flag is false; or a refill is already pending. refill is null when the event is itself the retry dispatch after a previous refill() (preventing infinite loops), or when the browser determines refilling is not appropriate for this operation.

AutofillEventInit

The WICG draft proposes synthetic construction (e.g. by third-party autofill providers and password-manager extensions, which spec §6.1 discusses). Pinned Chromium has no constructor, so the following defaults describe the draft only: autofillValues defaults to [] and allowRefill defaults to true. Full constructor reference: AutofillEvent() and AutofillEventInit.

the "full-address" autocomplete token

The spec also introduces a new autofill field name, "full-address" (spec §5): on a form control’s autocomplete attribute it signals that the browser SHOULD request permission for the user’s complete address data — including fields not present in the current form — so the page can receive comprehensive address data via the event and adapt its structure. Full token reference: the "full-address" autocomplete token.

event timing and refill lifecycle

In the WICG draft (§4.1), when the user selects values to fill, the browser creates an AutofillEvent of type "autofill" (bubbles true, cancelable false), dispatches it at the Document, and performs the autofill operation immediately after the dispatch. §4.3 requires the event to fire before the values are committed to the fields. If the handler calls refill() inside the implementation-defined timeout, the browser re-matches the (possibly restructured) form, queues a task to fire a second autofill event with the updated entries and allowRefill false, fills, then resolves the promise. The event targets the document rather than a form because the browser’s notion of a fill “form” may span shadow and light DOMs or multiple documents (explainer).

Note on divergence: the non-normative explainer describes a non-bubbling event with a values property that can carry booleans for checkboxes/radios; the current spec IDL instead defines bubbling and autofillValues with DOMString values. This page documents the spec. For automated testing, the spec also defines a WebDriver BiDi autofill.trigger command that triggers autofill on a form field with provided card or address data — full command reference: autofill.trigger.

examples

WICG draft illustration, not verified as runnable Chromium code: adapted from the spec’s own checkout example (§1.2) — listen at the document, inspect the pending values, adapt the form, then request a refill. The tuple entries shown here differ from the pinned Chromium field-data dictionaries:

document.addEventListener('autofill', async (event) => {
  // Each entry is a [HTMLElement, DOMString] tuple
  let countryValue = null, formElement = null;
  for (const [element, value] of event.autofillValues) {
    if (element.autocomplete === 'country') {
      countryValue = value;
      formElement = element.form;
      break;
    }
  }

  if (event.refill !== null && countryValue === 'US' &&
      !formElement.querySelector('[autocomplete="address-level1"]')) {
    const stateSelect = document.createElement('select');
    stateSelect.autocomplete = 'address-level1';
    stateSelect.name = 'state';
    stateSelect.innerHTML = buildStateOptions(); // page-supplied
    const postalCode = formElement.querySelector('[autocomplete="postal-code"]');
    postalCode.parentNode.insertBefore(stateSelect, postalCode);

    // Ask the browser to re-run autofill against the modified form.
    // Rejects with InvalidStateError after the refill timeout,
    // if a refill is pending, or if refills are not allowed.
    await event.refill();
  }
});

The feature’s editor also publishes standalone demos linked from the ChromeStatus record: autofill event demo and credit-card autofill demo.

browser compatibility

Per-version data for the AutofillEvent interface (and its autofillValues and refill members, which carry identical support) from BCD api/AutofillEvent.json (verified 2026-10-04):

BCD records only the interface and its two members: there are no separate entries for the constructor, AutofillEventInit, the AutofillValueEntry typedef, RefillCallback, the "full-address" token, or the WebDriver BiDi command (checked 2026-10-04). Interface support does not establish constructor, token, or draft tuple support: pinned Chromium IDL lacks the constructor and uses { field, value } entries; Chrome 154 with the flag exposed the interface but rejected construction. Chrome 147’s exact behavior remains unverified.

There is no webstatus.dev / web-features entry for this feature yet (queried 2026-10-04), so no Baseline status exists; interim Chrome-channel status comes from chromestatus: listed under Origin trial for milestone 147 in the milestone listing, “Proposed” on the detail record (labelled interim, queried 2026-10-04). Treat the API as a Chromium-only experiment: an exposed interface alone does not verify the constructor, entry shape, or a successful autofill/refill flow.

security and privacy

The event exposes autofill values to JavaScript before they are committed to form fields, so spec §6 says user agents SHOULD fire it only after explicit user consent to autofill (e.g. the user picking a suggestion from the dropdown). The data is limited to what the browser intends to fill into this page’s forms — the API shape keys every value to an element. After a refill(), the restructured form likely contains new fields the browser has not shown to the user before; the spec notes the browser should still consider user consent before filling them. The security questionnaire accompanies the explainer.

specifications

see also

• chromestatus — Autofill event (5137581018841088)
• Autofill Event specification (WICG Draft CG Report)
• Explainer — WICG/autofill-event README · initial proposal (WICG/proposals #162)
• HTML Living Standard — Autofill (autofill field names) · whatwg/html #4986 (upstream HTML issue cited by the showcase page for this feature; title not re-verified 2026-10-04 — github.com unreachable from this session)
• Member references: AutofillEvent() / AutofillEventInit · "full-address" token · WebDriver BiDi autofill.trigger
• chrome-platform-showcase: Autofill event demos (five concepts, route 200, 2026-10-04)
• Chromium tracking bug 466333215