Documentation Index
Fetch the complete documentation index at: https://developer.dromo.io/llms.txt
Use this file to discover all available pages before exploring further.
Overview
onUserEvent is a callback you can register on a DromoUploader instance to receive real-time notifications when a user interacts with specific UI controls inside the importer. It gives your host application observability into what the user is doing — useful for analytics, audit logging, conditional UI reactions, or debugging.
Registration
const importer = new DromoUploader(licenseKey, fields, settings, user);
importer.onUserEvent((event) => {
console.log(event.eventType, event.payload);
});
Only one callback can be registered per instance. Calling onUserEvent a second time replaces the first.
Callback Signature
onUserEvent(callback: (event: IUserEvent) => void): void
IUserEvent object:
interface IUserEvent<T extends EUserEventType = EUserEventType> {
eventType: T;
payload: IUserEventPayloadMap[T];
}
Event Types
Currently one event type is emitted:
eventType | Description |
|---|
"BUTTON_CLICK" | Fired whenever the user clicks a tracked button in the importer |
eventType is "BUTTON_CLICK", the payload is:
interface IButtonClickPayload {
buttonName: string; // see button name reference below
step: string; // the active step when the click occurred
}
step values
| Value | Step |
|---|
"UPLOAD" | File upload / manual data entry screen |
"HEADER_SELECT" | Header row selection screen |
"COLUMN_MATCH" | Column mapping screen |
"SELECT_MATCH" | Value / select matching screen |
"REVIEW" | Data review and validation screen |
buttonName values, grouped by step:
Navigation (cross-step)
| Value | Description |
|---|
CONTINUE | Primary continue action |
NEXT | Next step |
GO_BACK | Back navigation |
FINISH | Final submit / finish |
Upload step
| Value | Description |
|---|
UPLOAD_DATA | Upload a file |
ENTER_DATA | Open manual data entry |
DOWNLOAD_TEMPLATE | Download the CSV template |
CONFIRM_SHEET | Confirm sheet selection (multi-sheet files) |
| Value | Description |
|---|
HEADER_SELECT_CONTINUE | Continue with selected header row |
NO_HEADER_ROW | Mark file as having no header row |
Column match step
| Value | Description |
|---|
COLUMN_MATCH_IGNORE | Ignore an unmatched column |
COLUMN_MATCH_REMOVE | Remove an unmatched column |
Select / value match step
| Value | Description |
|---|
DATE_FIX_ACCEPT | Accept suggested date format fix |
DATE_FIX_UNDO | Undo date format fix |
SELECT_MATCH_CLEAR | Clear a single-select match |
MULTI_SELECT_MATCH_CLEAR | Clear a multi-select match |
Review step
| Value | Description |
|---|
FIND_AND_REPLACE_OPEN | Open find & replace panel |
FIND_AND_REPLACE_CONFIRM | Confirm a find & replace operation |
FIND_AND_REPLACE_CANCEL | Cancel find & replace |
SHOW_ROWS_WITH_ERRORS | Filter to rows with errors |
CLEAR_ROWS_WITH_ERRORS_FILTER | Clear the error filter |
TRANSFORM_DATA_OPEN | Open AI transform panel |
TRANSFORM_DATA_PREVIEW | Preview AI transform results |
TRANSFORM_DATA_REGENERATE | Regenerate AI transform |
TRANSFORM_DATA_CONFIRM | Confirm AI transform |
TRANSFORM_DATA_CANCEL | Cancel AI transform |
EXPORT_ALL | Export all rows |
EXPORT_ERRORS_ONLY | Export only rows with errors |
DOWNLOAD_XLSX | Download data as XLSX |
TOGGLE_SEARCH | Toggle search bar |
Exit confirmation modal
| Value | Description |
|---|
EXIT_CONFIRM | Confirm exit / cancel import |
EXIT_CANCEL | Stay in the importer |
Generic alert / modal actions
| Value | Description |
|---|
ALERT_PRIMARY | Primary action on a generic alert |
ALERT_SECONDARY | Secondary action on a generic alert |
Error Handling
Errors thrown inside your onUserEvent callback are caught by Dromo and logged as a warning — they will not crash the importer or interrupt the user’s flow:
[Dromo-External-Error] There was an error in your onUserEvent callback.
Example
importer.onUserEvent((event) => {
if (event.eventType === "BUTTON_CLICK") {
const { buttonName, step } = event.payload;
analytics.track("dromo_button_click", {
button: buttonName,
step: step,
userId: currentUser.id,
});
}
});
Notes
- The callback is fire-and-forget from Dromo’s perspective — the return value is ignored and the importer does not await it.
- The callback is registered on the importer instance, so each importer instance can have its own independent
onUserEvent handler.
- The callback is not invoked in headless mode (server-side Lambda execution), only during interactive browser sessions.
