connectors connectCurrentRefinedValues

Edit this page

Description

CurrentRefinedValues 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 and a clearAllClick function to clear all the filters. Those functions can see their behaviour change based on the widget options used.

Usage

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

const makeCurrentRefinedValues= instantsearch.connectors.connectCurrentRefinedValues(
function renderFn(
renderOpts: CurrentRefinedValuesRenderingOptions,
isFirstRendering: boolean) {
// render the custom CurrentRefinedValues widget
} );

const customCurrentRefinedValues = makeCurrentRefinedValues(instanceOpts: CustomCurrentRefinedValuesWidgetOptions);
search.addWidget(customCurrentRefinedValues);

Connector options

CurrentRefinedValuesRenderingOptions

  • attributesObject<string,object>

    Original CurrentRefinedValuesWidgetOptions.attributes mapped by keys.

  • clearAllClickfunction

    Clears all the currently refined values.

  • clearAllURLfunction

    Generate a URL which leads to a state where all the refinements have been cleared.

  • refine(item) => undefined

    Clears a single refinement.

  • createURL(item) => string

    Creates an individual url where a single refinement is cleared.

  • refinementsArray<CurrentRefinement>

    All the current refinements.

  • widgetParamsObject

    All original CustomCurrentRefinedValuesWidgetOptions forwarded to the renderFn.

CurrentRefinement

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

    Type of refinement

  • attributeNamestring

    Attribute on which the refinement is applied

  • namestring

    value of the refinement

  • numericValue[number]

    value if the attribute is numeric and used with a numeric filter

  • exhaustive[boolean]

    true if the count is exhaustive, only if applicable

  • count[number]

    number of items found, if applicable

  • query[string]

    value of the query if the type is query

CustomCurrentRefinedValuesWidgetOptions

  • attributes[Array<CurrentRefinedValuesAttributes>]
    Default value: []

    Specification for the display of refinements per attribute (default: []). By default, the widget will display all the filters set with no special treatment for the label.

  • onlyListedAttributes[boolean]
    Default value: false

    Limit the displayed refinement to the list specified.

  • clearsQuery[boolean]
    Default value: false

    Clears also the active search query when using clearAll.

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

    Function to transform the items passed to the templates.

CurrentRefinedValuesAttributes

  • namestring

    Mandatory field which is the name of the attribute.

  • labelstring

    The label to apply on a refinement per attribute.

Example

// custom `renderFn` to render the custom ClearAll widget
function renderFn(CurrentRefinedValuesRenderingOptions, isFirstRendering) {
  var containerNode = CurrentRefinedValuesRenderingOptions.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 (CurrentRefinedValuesRenderingOptions.refinements
      && CurrentRefinedValuesRenderingOptions.refinements.length > 0) {
    containerNode
      .find('#cta-container')
      .html('<a href="' + CurrentRefinedValuesRenderingOptions.clearAllURL + '">Clear all </a>');

    containerNode
      .find('#cta-container > a')
      .on('click', function(event) {
        event.preventDefault();
        CurrentRefinedValuesRenderingOptions.clearAllClick();
      });

    var list = CurrentRefinedValuesRenderingOptions.refinements.map(function(refinement) {
      return '<li><a href="' + CurrentRefinedValuesRenderingOptions.createURL(refinement) + '">'
        + refinement.computedLabel + ' ' + refinement.count + '</a></li>';
    });

    CurrentRefinedValuesRenderingOptions.containerNode.find('ul').html(list);
    CurrentRefinedValuesRenderingOptions.containerNode.find('li > a').each(function(index) {
      $(this).on('click', function(event) {
        event.preventDefault();

        var refinement = CurrentRefinedValuesRenderingOptions.refinements[index];
        CurrentRefinedValuesRenderingOptions.refine(refinement);
      });
    });
  } else {
    containerNode.find('#cta-container').html('');
    containerNode.find('ul').html('');
  }
}

// connect `renderFn` to CurrentRefinedValues logic
var customCurrentRefinedValues = instantsearch.connectors.connectCurrentRefinedValues(renderFn);

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


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