connectRefinementList

Build a custom widget for multi-select faceted filtering

The RefinementList connector provides the logic to build a custom widget that lets users filter results based on facet values with multi-select capability.

The attribute passed as attribute must be present in attributesForFaceting on the Algolia dashboard or configured via the API.

Usage

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

const customRefinementList = connectRefinementList(
  (renderOptions, isFirstRender) => {
    const { items, refine, widgetParams } = renderOptions;
    const { container } = widgetParams;
    
    container.innerHTML = `
      <ul>
        ${items.map(item => `
          <li>
            <input 
              type="checkbox" 
              value="${item.value}"
              ${item.isRefined ? 'checked' : ''}
            />
            ${item.label} (${item.count})
          </li>
        `).join('')}
      </ul>
    `;
    
    container.querySelectorAll('input').forEach(input => {
      input.addEventListener('change', (e) => {
        refine(e.target.value);
      });
    });
  }
);

search.addWidgets([
  customRefinementList({
    container: document.querySelector('#refinement-list'),
    attribute: 'brand',
  }),
]);

Connector Options

attribute · string · required

The name of the attribute in the records.

operator · 'and' | 'or' · default: "'or'"

How the filters are combined together.

limit · number · default: "10"

The max number of items to display.

showMore · boolean · default: "false"

Whether to display a button that expands the number of items.

showMoreLimit · number · default: "20"

The max number of items to display when showing more items.

sortBy · string[] | function · default: "['isRefined', 'count:desc', 'name:asc']"

How to sort refinements. Possible values: count, isRefined, name:asc, name:desc.

You can also use a sort function that behaves like the standard JavaScript compareFunction.

escapeFacetValues · boolean · default: "true"

Escapes the content of the facet values.

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

Function to transform the items passed to the templates.

Render Options

items · Array<RefinementListItem>

The list of filtering values returned from Algolia API.

Each item has:

• value: The value of the refinement list item
• label: Human-readable value of the item
• highlighted: Human-readable highlighted value
• count: Number of matched results after refinement is applied
• isRefined: Indicates if the list item is refined

refine · (value: string) => void

Toggles the selected refinement.

searchForItems · (query: string) => void

Searches for values inside the list.

isFromSearch · boolean

true if the values are from an index search.

canRefine · boolean

true if a refinement can be applied.

isShowingMore · boolean

true if the menu is displaying all items.

toggleShowMore · () => void

Toggles the number of values displayed between limit and showMoreLimit.

canToggleShowMore · boolean

true if the toggleShowMore button can be activated.

hasExhaustiveItems · boolean

Indicates whether the results are exhaustive (complete).

createURL · (value: string) => string

Creates the URL for the next state for a selected refinement.

sendEvent · function

Sends an event to the Insights middleware.

widgetParams · object

The options passed to the connector.