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

Method	What 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

Method	What 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.

Method	What 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

Method	What 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

Method	What it does
`trackClick(...)`	Sends an Insights click event.
`trackConversion(...)`	Sends an Insights conversion event.
`getInsights()`	Returns the underlying Insights client.

These require data-insights="true" on the script tag.

Events

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

Event	Fires when
`ready`	Initialisation finished and the API is attached
`search`	A query is about to be sent
`results`	Results came back
`filter`	A filter selection changed
`refresh`	The query was re-run
`error`	Something failed
`filter:parent-change`	A cascading parent group's selection changed
`filter:parent-stage-change`	The 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() removes every element the script injected and deletes window.WfAlgolia. Useful in single-page contexts where the DOM is swapped out underneath the script.

`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.

Searching​

Driving the current page​

Deferred apply​

Rendering​

Tracking​

Events​

Middleware​

Teardown​

version is not the release number​

Related​