Events and JavaScript API

The widget exposes window.findalo: an event bus for everything that happens in the search, plus methods to control it from your code. Your JS can live in your store or in the panel's editor (Appearance → Advanced).

Events

Event	Payload	When
search	{ query, total, took_ms, match_mode, lang }	Every executed search (queries of 2+ characters). match_mode tells whether the results are direct or suggested (“fallback”).
zero	{ query, total: 0, took_ms, match_mode, lang }	Search with 0 results. Rare: the search never leaves the screen empty — the real “no results” signal is search with match_mode “fallback”.
click	{ product_id, product_name, product_url, price, currency, query, position }	Click on a product in the results.
add-to-cart	{ product_id, product_name, price, currency, quantity, cart_count }	Product added to the cart from the search.
quick-view	{ product_id, product_name, product_url, price, currency, query, position }	A product's quick view opened.
cart-open	{ cart_count }	Cart panel opened from the search header.
express-purchase	{ payment_intent, order_id, reference }	Purchase completed via express checkout (when enabled).
open	{ prefill }	Search opened. prefill carries the initial query, if any.
close	{}	Search closed.
context	el objeto window.FINDALO_CTX completo	El contexto de navegación ya resuelto, con la parte privada (carrito y cliente) incluida. Dispara una vez por carga de página. Ver /devs/contexto.

Examples

Send searches to your GA4

findalo.on('search', (e) => {
  gtag?.('event', 'site_search', { search_term: e.query, results: e.total });
});

(For GA4 there's a no-code integration in the panel — Analytics → Forward to your GA4. Write your own only if you need something different.)

Detect searches with no real results

// The search never leaves the screen empty: when nothing matches, it shows
// suggestions with match_mode 'fallback'. That is the real "no results"
// signal — the 'zero' event almost never fires.
findalo.on('search', (e) => {
  if (e.match_mode === 'fallback') {
    // e.g. open your support chat with the query
  }
});

Open the search from your own elements

document.querySelector('#hero-buscar')
  ?.addEventListener('click', () => findalo.open());

// or directly with a query:
findalo.search('crema hidratante');

Methods and properties

Method / property	What it does
findalo.on(event, callback)	Subscribes to a bus event. Returns a function to unsubscribe.
findalo.open(query?)	Opens the search, optionally with an initial query.
findalo.search(query)	Opens the search and runs the query.
findalo.close()	Closes the search.
findalo.tenant	Slug of the search (read-only).
findalo.lang	Active widget language (read-only).
findalo.version	JS API version (read-only).
findalo.context()	Contexto de navegación de la página: la misma variable window.FINDALO_CTX (tipo de página, ids, idioma, divisa, carrito, cliente). Ver /devs/contexto.
findalo.onContext(callback)	Ejecuta el callback con el contexto COMPLETO (carrito y cliente ya resueltos); si ya lo está, en el acto. Es la vía correcta si dependes del carrito.

Guarantee: event names and their payload keys are a stable contract — we may add new fields, never rename or remove existing ones.