connectors connectRefinementList

Edit this page

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

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

  • attributeNamestring

    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.

  • showMoreLimit[number]

    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: false

    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'),
    attributeName: 'categories',
    limit: 10,
  })
);


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