The attribute system

WF-Algolia has no configuration file. Everything it knows comes from attributes on your elements, read at page load. That makes the DOM the configuration — and it means understanding two prefixes, one inheritance rule, and one failure mode.

Two prefixes, two places

Prefix	Goes on	Example
data-*	The <script> tag, once	data-app-id
wf-algolia-*	Your Designer elements, many times	wf-algolia-element

The split is not decorative. The script tag is a single, terse surface with site-wide settings. Your page has many elements, each needing an unambiguous prefix that will not collide with anything else in your project.

Mixing them up produces silence, not an error: data-index on a Div does nothing, and wf-algolia-index on the script tag does nothing.

data-wf-algolia-index is neither

Combining both prefixes is a common typo and always wrong. On an element the attribute is , with no data-.

The one exception is the read-only markers the script writes onto rendered cards, which are genuinely data-wf-algolia-* — see CSS hooks.

Role first, then settings

Every element the script cares about declares what it is, using :

<input wf-algolia-element="search-input" />

Everything else refines that role. A search input can carry wf-algolia-index to query a specific index; a filter group carries wf-algolia-field to say which facet it filters. An element with settings but no role is invisible to the script — the role is what makes it look at the element at all.

The complete list of roles and their settings is the Attribute reference, which is generated from the same source the Designer extension reads, so the two cannot disagree.

Inheritance

Some attributes cascade. The clearest is the index:

1. The element's own wf-algolia-index.
2. The nearest ancestor that declares one — usually a browse or search wrapper.
3. data-index on the script tag.

This is why a browse page usually sets the index once on its wrapper instead of on every filter and result element inside it.

It is also a common surprise. If results arrive from an index you did not expect, something above the element is supplying one. Setting wf-algolia-index explicitly on the element ends the inheritance chain immediately.

Values are strings, and comparisons are exact

Attribute values are text. The script compares them literally:

• Booleans are on only when the value is exactly true. "TRUE" and "1" are off.
• Field names match your Algolia record keys case-sensitively. Title and title are different fields, and the wrong one fails quietly on that binding while the rest of the card renders.

Repeating an attribute

The filter clause attributes accept a numbered suffix, so several independent clauses can sit on one wrapper:

<div
  wf-algolia-filter-field="category"
  wf-algolia-filter-value="Design"
  wf-algolia-filter-field-2="brand"
  wf-algolia-filter-value-2="Acme"
></div>

Numbering starts at -2 — the unsuffixed attribute is the first clause — and a clause's parts share a number, so -field-2 pairs with -value-2.

Only the clause attributes take a suffix — wf-algolia-filter-field, wf-algolia-filter-value and wf-algolia-filter-match, plus the same three in their wf-algolia-base-filter-field / wf-algolia-base-filter-value / wf-algolia-base-filter-match form. The reference marks each one. The single-value wf-algolia-filter is not among them.

Why failures are quiet

The script warns rather than throwing. A page with one wrong attribute keeps working everywhere else, which is right for a live site and confusing while you are building.

The practical consequence: keep the console open while you work. Almost every misconfiguration announces itself there, prefixed [wf-algolia], and nowhere else. Common issues catalogs every message the script can emit.

Related

• Attribute reference
• Script tag reference
• Architecture