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" | "api" }
| { 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.

Driving the locator from your page

Events are the read side. To run a search, apply a filter or open a location from your own script, the element has methods for each: see the JavaScript API. A location opened that way still fires handled:location-selected, with source: "api".

Not a location write API

Widget events report browser interactions. They do not create, edit or delete locations. For that, use the Location API, which covers reading, creating, updating and deleting locations with an account API key, plus a Query API for building your own front end.

To be called when a location or a lead changes, rather than when a visitor does something, register a webhook.