Widget events

Listen for events

The <biz-locator> custom element dispatches browser CustomEvent objects for meaningful visitor actions. Events bubble and cross the widget's shadow boundary, so code can listen on the element itself or on document.

const locator = document.querySelector("biz-locator");

locator.addEventListener("handled:location-selected", (event) => {
console.log(event.detail.locationId);
});

Every payload includes version: 1 and the locator siteId. Treat the version as part of the public contract when consuming events.

Event reference

• handled:ready fires after locations and settings finish loading. It includes locationCount and onlineLocationCount.
• handled:search fires after a text or near-location search. It includes mode, resultCount and zeroResults.
• handled:no-results fires when a search or filter state produces no result. It includes source and, for searches, mode.
• handled:location-selected fires when a visitor selects a result card, marker or online location. It includes locationId and source.
• handled:directions-clicked fires when a visitor opens directions. It includes locationId and source.
• handled:action-clicked fires when a visitor uses phone, email, website or a linked custom field. It includes locationId, source and action.

type HandledEventDetail =
| { version: 1; siteId: string; locationCount: number; onlineLocationCount: number }
| { version: 1; siteId: string; mode: "text" | "near"; resultCount: number; zeroResults: boolean }
| { version: 1; siteId: string; source: "search" | "filter"; mode?: "text" | "near" }
| { version: 1; siteId: string; locationId: string; source: "card" | "marker" | "online" }
| { version: 1; siteId: string; locationId: string; source: "card" | "popup" }
| { version: 1; siteId: string; locationId: string; source: "card" | "popup"; action: string };

Privacy contract

Public event payloads deliberately omit typed search text, resolved place names, visitor coordinates, full addresses, contact values and session identifiers. Search events expose the mode and outcome rather than the visitor's query.

Google Tag Manager

document.addEventListener("handled:location-selected", (event) => {
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
  event: "locator_location_selected",
  locator_location_id: event.detail.locationId,
  locator_source: event.detail.source,
});
});

The listener can run before the widget script; it is attached to document and receives future bubbling events.

Not a location write API

Widget events report browser interactions. They do not create, edit or delete locations, and they do not expose a location query API. Locations remain managed through the dashboard, CSV or Google Sheets sync. A scoped public REST write API and webhooks are not available yet.