connectCurrentRefinements

Build a custom widget to display and remove active filters

The CurrentRefinements connector provides the logic to build a custom widget that displays all currently applied refinements and allows users to remove them.

Usage

import { connectCurrentRefinements } from 'instantsearch.js/es/connectors';

const customCurrentRefinements = connectCurrentRefinements(
  (renderOptions, isFirstRender) => {
    const { items, refine, widgetParams } = renderOptions;
    const { container } = widgetParams;
    
    container.innerHTML = `
      <ul>
        ${items.map(item => `
          <li>
            <strong>${item.label}:</strong>
            ${item.refinements.map(refinement => `
              <span>
                ${refinement.label}
                <button data-attribute="${refinement.attribute}" data-value="${refinement.value}">
                  ✕
                </button>
              </span>
            `).join('')}
          </li>
        `).join('')}
      </ul>
    `;
    
    container.querySelectorAll('button').forEach(button => {
      button.addEventListener('click', (e) => {
        const refinement = items
          .flatMap(item => item.refinements)
          .find(r => r.value === e.target.dataset.value);
        if (refinement) {
          refine(refinement);
        }
      });
    });
  }
);

search.addWidgets([
  customCurrentRefinements({
    container: document.querySelector('#current-refinements'),
  }),
]);

Connector Options

includedAttributes · string[] · default: "[]"

The attributes to include in the widget (all by default). Cannot be used with excludedAttributes.

excludedAttributes · string[] · default: "['query']"

The attributes to exclude from the widget. Cannot be used with includedAttributes.

transformItems · (items: object[]) => object[]

Function to transform the items passed to the templates.

Render Options

items · Array<CurrentRefinementItem>

All currently refined items, grouped by attribute.

Each item has:

• indexName: The index name
• indexId: The index id as provided to the index widget
• attribute: The attribute on which the refinement is applied
• label: The textual representation of this attribute
• refinements: Currently applied refinements (array of refinement objects)
• refine: Function to remove the given refinement

Each refinement has:

• attribute: The attribute on which the refinement is applied
• type: The type of the refinement (facet, exclude, disjunctive, hierarchical, numeric, query, tag)
• value: The raw value of the refinement
• label: The label of the refinement to display
• operator: The value of the operator (only if applicable)
• count: The number of found items (only if applicable)
• exhaustive: Whether the count is exhaustive (only if applicable)

refine · (refinement: object) => void

Removes the given refinement and triggers a new search.

createURL · (refinement: object) => string

Generates a URL for the next state.

canRefine · boolean

Indicates if search state can be refined.

widgetParams · object

The options passed to the connector.