Skip to main content
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.

Build docs developers (and LLMs) love