Skip to main content

Public API

Attributes cover most of what people build. When you need to drive the script from your own code — a custom control, an IX2 interaction, an analytics hook — everything is on window.WfAlgolia once the script has initialised.

window.WfAlgolia.on('results', ({ hits }) => {
  console.log(`${hits.length} hits`);
});
Wait for ready

The object is attached at the end of initialisation. Code that runs before the script finishes will find window.WfAlgolia undefined. Listen for the ready event, or run your code from the footer after the script tag.

Searching​

MethodWhat it does
search(indexName, query, params?)Runs one query. Click analytics are enabled by default; your params are merged over the defaults.
multiSearch(queries)Runs several queries in one request.
getObject(indexName, objectID)Fetches a single record by ID.
getClient()Returns the underlying Algolia client, for anything not wrapped here.

Driving the current page​

MethodWhat it does
setQuery(query)Sets the search text and re-runs the query.
getQuery()Reads the current text. Prefers a browse-search input over a plain search-input.
refresh()Re-runs the current query as it stands.
setFilter(field, values)Replaces the selected values for one field and re-queries.
clearFilter(field)Clears one field.
clearAllFilters()Clears every field.
getFilterState()Returns a deep copy of the current filter state — mutating it does nothing.

Deferred apply​

For filter groups running in deferred mode, selections accumulate in a staging area until committed.

MethodWhat it does
commitStaging()Promotes staged selections to the live filter state.
discardStaging()Throws staged selections away.
Committing does not re-query

commitStaging() deliberately does not run the query — staging and refreshing are separate so you can commit several groups and query once. Call refresh() yourself afterwards.

Rendering​

MethodWhat it does
cloneAndPopulate(template, hit)Clones one of your templates and fills it from a hit.
populateCard(card, hit)Fills an element that already exists.

Both close over the loaded configuration, so data-highlight-tag and the snippet settings apply without you passing them.

Tracking​

MethodWhat it does
trackClick(...)Sends an Insights click event.
trackConversion(...)Sends an Insights conversion event.
getInsights()Returns the underlying Insights client.
setInsightsConsent(granted)Grants or withdraws consent to track.
hasInsightsConsent()Whether consent has been given.

data-insights="true" on its own is not enough. With it set and no consent, the script binds its tracking and then sends nothing — no events, and no Insights cookie. There is no error, so a missing consent call looks exactly like a working install that nobody has clicked.

Grant consent one of two ways:

// From your cookie banner, when the visitor accepts:
window.WfAlgolia.setInsightsConsent(true);

or, if your site already has a legal basis to track and you want events to flow from the first page view, declare it on the script tag instead:

<script ... data-insights="true" data-insights-consent="granted"></script>

Call setInsightsConsent(false) to stop again, and hasInsightsConsent() to read the current state.

Events that happen before consent are discarded, not buffered and replayed. Nothing a visitor did before agreeing ever reaches Algolia. A banner accepted after the page has loaded works with no reload.

The same gate covers the recommended-for-you Recommend model, which reads a visitor identifier from a cookie — it stays hidden until consent arrives. See Detail and recommendations.

Events​

on(event, handler) subscribes, off(event, handler) unsubscribes.

EventFires when
readyInitialisation finished and the API is attached
searchA query is about to be sent
resultsResults came back
filterA filter selection changed
refreshThe query was re-run
errorSomething failed
filter:parent-changeA cascading parent group's selection changed
filter:parent-stage-changeThe same, while in deferred-apply mode

A handler that throws does not break the script — the error is caught and logged as [wf-algolia] Event handler error (…).

Middleware​

use(middleware) registers beforeSearch / afterSearch interceptors, for rewriting query parameters or post-processing results globally.

Teardown​

destroy() stops the script and releases everything it was holding:

  • every event listener it attached,
  • its observers,
  • any Algolia request still in flight,
  • pending debounced searches and any other timer it scheduled,
  • the stylesheet it injected,
  • the window.WfAlgolia and window.aa globals,
  • every element it injected.

Useful in single-page contexts where the DOM is swapped out underneath the script.

What it does not do​

destroy() is teardown-only. It does not put your page back the way it was before the script ran: elements the script hid stay hidden, and attributes it stamped stay stamped.

That means re-initialising after destroy() is not supported — reload the page. Restoring the DOM byte-for-byte would mean snapshotting every element the script touches, and getting that subtly wrong corrupts your page, which is a worse outcome than a reload.

Loading the script twice​

If the script is embedded twice — the usual way is custom code in both site settings and page settings — the second copy now does nothing and says so:

[wf-algolia] Already initialized on this page — ignoring a second embed of the
script. Remove the duplicate <script> tag: running twice doubles your Algolia
queries and Insights events.

Before this, both copies ran: two sets of listeners, two Algolia queries per keystroke, and two Insights events per click. If you see that warning, find and delete the duplicate tag.

version is not the release number​

WfAlgolia.version returns a hard-coded 1.0.0 and does not track the published package version. Use it to confirm the object exists; read the src on your script tag to find out which build is actually loaded.