Migrating from Formie Plugin

Use the compatibility bridge to move existing browser integrations to @verbb/formie-browser one listener at a time. It forwards supported DOM and validator events while you update your handlers.

Use the bridge only as a migration step, then register all listeners with the formie:* event names.

What Changed

The main browser changes from the old bundled Formie plugin JavaScript are:

• lifecycle and submit hooks now use canonical formie:* DOM events
• validator lifecycle hooks now use canonical formie:validator:* events
• the public browser API is now either the formie() helper or a client created with createFormieClient()

If your old code only listens for supported legacy event names, leave compatibility enabled while you migrate each listener to the new event surface.

Turn on Compatibility

Managed or Rendered Forms

Formie-rendered HTML inherits the plugin's compatibilityMode setting, which is enabled by default. This works with automatic startup and HTML loaded through REST or GraphQL; you do not need your own bundle or mount call. Purge cached form HTML after changing the setting.

For standalone HTML that Formie does not render, enable compatibility on the root:

<form data-formie data-formie-form data-formie-compatibility="true">
  ...
</form>

Your Own Bundle

If you mount with the package directly, the rendered form still supplies the default. Pass an explicit compatibility option to override it:

import { createFormieClient } from '@verbb/formie-browser';

const formie = createFormieClient();
const root = document.querySelector('[data-formie-form]');

if (root instanceof HTMLElement) {
  await formie.mount(root, {
    mode: 'server-rendered',
    compatibility: true,
  });
}

You can also opt into only part of the bridge:

await formie.mount(root, {
  mode: 'server-rendered',
  compatibility: {
    legacyDomEvents: true,
    legacyValidatorEvents: false,
  },
});

Event Mapping

These legacy DOM events can be bridged during migration:

Legacy event	Canonical event	Notes
onFormieLoaded	formie:mount:after	Approximate mapping
onFormieInit	formie:mount:after	Approximate mapping
onFormieReady	formie:mount:after	Safe mapping
onAfterFormieSubmit	formie:submit:result	Safe mapping
onFormieSubmitError	formie:submit:result	Safe mapping
onFormiePageToggle	formie:page:navigate:after	Safe mapping
onBeforeFormieSubmit	formie:submit:before	Approximate mapping
onFormieValidate	formie:stage:validate:before	Approximate mapping
onAfterFormieValidate	formie:stage:validate:after	Approximate mapping
onFormieSubmit	formie:submit:after	Approximate mapping

These validator events can be bridged too:

Legacy event	Canonical event
formieValidatorInitialized	formie:validator:ready
formieValidatorDestroyed	formie:validator:destroy
formieValidatorShowError	formie:validator:show-error
formieValidatorClearError	formie:validator:clear-error

Approximate mappings do not preserve every timing or cancellation behaviour. In particular, onFormieLoaded and onFormieInit fire for each mounted form, legacy events do not forward preventDefault() to the workflow, and onFormieThemeReady is not bridged.

Recommended Migration Path

1. Leave the plugin's compatibility mode enabled, or enable the bridge for standalone HTML.
2. Replace old event listeners with the canonical formie:* or formie:validator:* names.
3. Test any submit-flow logic that relied on older event timing.
4. Remove compatibility once the old listeners are gone.

Related Pages

• JavaScript events
• JavaScript API
• Custom client

Address Hooks

Older forms may still render legacy bare hooks such as [data-address1] or [data-state]. Provider modules fall back to those automatically via ADDRESS_LEGACY_SELECTORS. Use the attributes in Address Reference when updating your markup.