connectors connectRefinementList

Description

RefinementList connector provides the logic to build a custom widget that will let the user filter the results based on the values of a specific facet.

This connector provides a toggleShowMore() function to display more or less items and a refine() function to select an item.

Usage

const search= instantsearch(/* parameters */);

const makeRefinementList= instantsearch.connectors.connectRefinementList(
  function renderFn(
      renderOpts: RefinementListRenderingOptions,
      isFirstRendering: boolean) {
    // render the custom RefinementList widget
  }
);

const  customRefinementList = makeRefinementList(instanceOpts: CustomRefinementListWidgetOptions);
search.addWidget(customRefinementList);

Connector options

RefinementListRenderingOptions

• itemsArray<RefinementListItem>

  The list of filtering values returned from Algolia API.

• createURL(item.value) => string

  Creates the next state url for a selected refinement.

• refine(item.value) => undefined

  Action to apply selected refinements.

• searchForItemsfunction

  Searches for values inside the list.

• isFromSearchboolean

  true if the values are from an index search.

• canRefineboolean

  true if a refinement can be applied.

• canToggleShowMoreboolean

  true if the toggleShowMore button can be activated (enough items to display more or already displaying more than limit items)

• widgetParamsObject

  All original CustomRefinementListWidgetOptions forwarded to the renderFn.

• isShowingMoreboolean

  True if the menu is displaying all the menu items.

• toggleShowMorefunction

  Toggles the number of values displayed between limit and showMoreLimit.

RefinementListItem

• valuestring

  The value of the refinement list item.

• labelstring

  Human-readable value of the refinement list item.

• countnumber

  Number of matched results after refinement is applied.

• isRefinedboolean

  Indicates if the list item is refined.

CustomRefinementListWidgetOptions

• attributestring

  The name of the attribute in the records.

• operator["and"|"or"]
  Default value: 'or'

  How the filters are combined together.

• limit[number]
  Default value: 10

  The max number of items to display when showMoreLimit is not set or if the widget is showing less value.

• showMore[boolean]
  Default value: false

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

• showMoreLimit[number]
  Default value: 20

  The max number of items to display if the widget is showing more items.

• sortBy[Array<string>|function]
  Default value: ['isRefined','count:desc','name:asc']

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

• escapeFacetValues[boolean]
  Default value: true

  Escapes the content of the facet values.

• transformItems[(Array<object>) => Array<object>]

  Function to transform the items passed to the templates.

Example

// custom `renderFn` to render the custom RefinementList widget
function renderFn(RefinementListRenderingOptions, isFirstRendering) {
  if (isFirstRendering) {
    RefinementListRenderingOptions.widgetParams.containerNode
      .html('<ul></ul>')
  }

    RefinementListRenderingOptions.widgetParams.containerNode
      .find('li[data-refine-value]')
      .each(function() { $(this).off('click'); });

  if (RefinementListRenderingOptions.canRefine) {
    var list = RefinementListRenderingOptions.items.map(function(item) {
      return `
        <li data-refine-value="${item.value}">
          <input type="checkbox" value="${item.value}" ${item.isRefined ? 'checked' : ''} />
          <a href="${RefinementListRenderingOptions.createURL(item.value)}">
            ${item.label} (${item.count})
          </a>
        </li>
      `;
    });

    RefinementListRenderingOptions.widgetParams.containerNode.find('ul').html(list);
    RefinementListRenderingOptions.widgetParams.containerNode
      .find('li[data-refine-value]')
      .each(function() {
        $(this).on('click', function(event) {
          event.stopPropagation();
          event.preventDefault();

          RefinementListRenderingOptions.refine($(this).data('refine-value'));
        });
      });
  } else {
    RefinementListRenderingOptions.widgetParams.containerNode.find('ul').html('');
  }
}

// connect `renderFn` to RefinementList logic
var customRefinementList = instantsearch.connectors.connectRefinementList(renderFn);

// mount widget on the page
search.addWidget(
  customRefinementList({
    containerNode: $('#custom-refinement-list-container'),
    attribute: 'categories',
    limit: 10,
  })
);

Can't find what you are looking for? Open an issue, we'll get back to you.