connectors connectCurrentRefinements

Description

CurrentRefinements connector provides the logic to build a widget that will give the user the ability to see all the currently applied filters and, remove some or all of them.

This provides a refine(item) function to remove a selected refinement. Those functions can see their behaviour change based on the widget options used.

Usage

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

const makeCurrentRefinements= instantsearch.connectors.connectCurrentRefinements(
  function renderFn(
      renderOpts: CurrentRefinementsRenderingOptions,
      isFirstRendering: boolean) {
    // render the custom CurrentRefinements widget
  }
);

const  customCurrentRefinements = makeCurrentRefinements(instanceOpts: CustomCurrentRefinementsWidgetOptions);
search.addWidget(customCurrentRefinements);

Connector options

CurrentRefinementsRenderingOptions

• refine(item) => undefined

  Clears a single refinement

• createURL(item) => string

  Creates an individual URL where a single refinement is cleared

• itemsArray<RefinementItem>

  All the refinement items

• widgetParamsObject

  All original CustomCurrentRefinementsWidgetOptions forwarded to the renderFn.

RefinementItem

• attributestring

  The attribute on which the refinement is applied

• refinefunction

  The function to remove the refinement

• refinementsArray<Refinement>

  The current refinements

Refinement

• type"facet"|"exclude"|"disjunctive"|"hierarchical"|"numeric"|"query"

  The type of the refinement

• attributestring

  The attribute on which the refinement is applied

• labelstring

  The label of the refinement to display

• valuestring

  The raw value of the refinement

• operator[string]

  The value of the operator, only if applicable

• exhaustive[boolean]

  Whether the count is exhaustive, only if applicable

• count[number]

  number of items found, if applicable

CustomCurrentRefinementsWidgetOptions

• includedAttributes[Array<string>]

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

• excludedAttributes[Array<string>]
  Default value: ["query"]

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

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

  Function to transform the items passed to the templates.

Example

// custom `renderFn` to render the custom ClearRefinements widget
function renderFn(currentRefinementsRenderingOptions, isFirstRendering) {
  var containerNode = currentRefinementsRenderingOptions.widgetParams.containerNode;
  if (isFirstRendering) {
    containerNode
      .html('<ul id="refinements"></ul><div id="cta-container"></div>');
  }

  containerNode
    .find('#cta-container > a')
    .off('click');

  containerNode
    .find('li > a')
    .each(function() { $(this).off('click') });

  if (currentRefinementsRenderingOptions.items
      && currentRefinementsRenderingOptions.items.length > 0) {
    var list = currentRefinementsRenderingOptions.items.map(function(item) {
      return '<li>' + item.attribute +
         '<ul>' +
           item.refinements.map(function (refinement) {
             return <a href="' + currentRefinementsRenderingOptions.createURL(refinement) + '" data-attribute="' + item.attribute + '">'
               + refinement.label + '</a>'
             }).join('') +
           '</ul>'
       '</li>';
    });

    currentRefinementsRenderingOptions.find('ul').html(list);
  } else {
    containerNode.find('#cta-container').html('');
    containerNode.find('ul').html('');
  }
}

// connect `renderFn` to CurrentRefinements logic
var customCurrentRefinements = instantsearch.connectors.connectCurrentRefinements(renderFn);

// mount widget on the page
search.addWidget(
  customCurrentRefinements({
    containerNode: $('#custom-crv-container'),
  })
);

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