Last updated:
With the Formcentric Event API, you can see when specific actions occur in your forms—for example, a submission or an error. These events can be automatically forwarded to tracking services such as Matomo, Google Analytics, or other analytics tools.
The API provides a unified interface that allows you to subscribe to relevant events and use them in your own tracking or processing solutions.
The Event API becomes available automatically once the Formcentric script has loaded.
To reliably register event listeners, use the formcentric:loaded custom event.
Each event follows a consistent structure with the following base properties:
Property |
Type |
Description |
eventType |
string | Event identifier (e.g., 'form:init:complete') |
timestamp |
number | Unix timestamp in milliseconds |
embedId |
string | Unique ID of the form instance |
formId |
string (optional) | Form UID (available after initialization) |
formName |
string (optional) | Form name (set via data-fc-name or chosen in Formcentric Editor, if available) |
The Formcentric Event API provides various categories of events to track user interactions, validations, and form lifecycle:
These events track the lifecycle of a form instance.
Event |
Description |
Available Properties |
form:init:start |
Wrapper begins form initialization | eventType, embedId, timestamp |
form:init:complete |
Form fully loaded and rendered | eventType, embedId, formId, formName, pageCount, timestamp |
form:stop |
Form instance stopped | eventType, embedId, reason ('user', 'error', 'navigation', 'system'), timestamp |
form:unmount |
Form instance removed from DOM | eventType, embedId, timestamp |
form:reload |
Form reloaded | eventType, embedId, trigger, timestamp |
form:cancel |
Form canceled | eventType, embedId, formId, formName, currentPage, timestamp |
form:submitted |
Form successfully submitted | eventType, embedId, formId, formName, fromPage, view, submissionTime, timestamp |
These events track navigation between form pages and form submission.
Event |
Description |
Available Properties |
page:change:start |
Page change or submission started | eventType, embedId, formId, formName, fromPage, toPage, direction ('forward', 'backward'), isSubmit, timestamp |
page:change:success |
Page change or submission successful | eventType, embedId, formId, formName, fromPage, toPage, direction, isSubmit, submissionTime (only for submission), timestamp |
page:change:failed |
Page change or submission failed | eventType, embedId, formId, formName, fromPage, toPage, direction, isSubmit, reason ('validation', 'server', 'network', 'timeout'), errorMessage (optional), timestamp |
These events capture interactions with individual form fields.
Event |
Description |
Available Properties |
field:input |
User enters data into field |
eventType, embedId, formId, formName, currentPage, fieldName, fieldLabel, fieldType, valueLength, timestamp |
field:focus |
Field receives focus | eventType, embedId, formId, formName, currentPage, fieldName, fieldLabel, fieldType, timestamp |
field:blur |
Field loses focus | eventType, embedId, formId, formName, currentPage, fieldName, fieldLabel, fieldType, timestamp |
These events report validation results for individual fields.
Event |
Description |
Available Properties |
validation:success |
Field validated successfully |
eventType, embedId, formId, formName, currentPage, fieldName, fieldLabel, timestamp |
validation:error |
Validation error occurred |
eventType, embedId, formId, formName, currentPage, fieldName, fieldLabel, errorCode, errorMessage, timestamp |
validation:cleared |
Validation error cleared |
eventType, embedId, formId, formName, currentPage, fieldName, fieldLabel, timestamp |
These events capture specific user behavior for analyzing user experience.
Event |
Description |
Available Properties |
user:hint:opened |
Hint/tooltip opened |
eventType, embedId, formId, formName, currentPage, fieldName, fieldLabel, timestamp |
user:hint:closed |
Hint/tooltip closed |
eventType, embedId, formId, formName, currentPage, fieldName, fieldLabel, timestamp |
You can use wildcards to catch multiple events with a single handler:
Full setup for Matomo tracking:
Full setup for Google Analytics 4 tracking:
Send events to your own API:
During development, you can log all events to the console for debugging:
