widgets currentRefinedValues

Edit this page

Description

The current refined values widget has two purposes:

  • give the user a synthetic view of the current filters.
  • give the user the ability to remove a filter.

This widget is usually in the top part of the search UI.

Live example

You can find an example at the end of the page or a live example in our widget showcase.

Usage

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

const widget = instantsearch.widgets.currentRefinedValues({ container: string|HTMLElement, attributes: [Array<CurrentRefinedValuesAttributes>], onlyListedAttributes: [boolean], clearAll: ["before"|"after"|boolean], templates: [CurrentRefinedValuesTemplates], transformData: [CurrentRefinedValuesTransforms], autoHideContainer: [boolean], cssClasses: [CurrentRefinedValuesCSSClasses], collapsible: [boolean|{collapsed: boolean}], clearsQuery: [boolean], transformItems: [(Array<object>) => Array<object>], }: CurrentRefinedValuesWidgetOptions);
search.addWidget(widget);

Options

CurrentRefinedValuesWidgetOptions

  • containerstring|HTMLElement

    CSS Selector or HTMLElement to insert the widget

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

    Label definitions for the different filters.

  • onlyListedAttributes[boolean]
    Default value: false

    Only use the declared attributes. By default, the widget displays the refinements for the whole search state. If true, the list of attributes in attributes is used.

  • clearAll["before"|"after"|boolean]
    Default value: 'before'

    Defines the clear all button position. By default, it is placed before the set of current filters. If the value is false, the button wonโ€™t be added in the widget.

  • templates[CurrentRefinedValuesTemplates]

    Templates to use for the widget.

  • transformData[CurrentRefinedValuesTransforms]

    Set of functions to transform the data passed to the templates.

  • autoHideContainer[boolean]
    Default value: true

    Hides the widget when there are no current refinements.

  • cssClasses[CurrentRefinedValuesCSSClasses]

    CSS classes to be added.

  • collapsible[boolean|{collapsed: boolean}]
    Default value: false

    Makes the widget collapsible. The user can then choose to hide the content of the widget. This option can also be an object with the property collapsed. If this property is true, then the widget is hidden during the first rendering.

  • clearsQuery[boolean]
    Default value: false

    If true, the clear all button also clears the active search query.

  • 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.

CurrentRefinedValuesTemplates

  • header[string|(object) => string]

    Header template.

  • item[string|(object) => string]

    Item template.

  • clearAll[string|(object) => string]

    Clear all template.

CurrentRefinedValuesTransforms

  • item[(object) => object]

    Method to change the object passed to the item template.

CurrentRefinedValuesCSSClasses

  • root[string]

    CSS classes added to the root element.

  • header[string]

    CSS classes added to the header element.

  • body[string]

    CSS classes added to the body element.

  • clearAll[string]

    CSS classes added to the clearAll element.

  • list[string]

    CSS classes added to the list element.

  • item[string]

    CSS classes added to the item element.

  • count[string]

    CSS classes added to the count element.

Example

search.addWidget(
  instantsearch.widgets.currentRefinedValues({
    container: '#current-refined-values',
    clearAll: 'after',
    clearsQuery: true,
    attributes: [
      {name: 'free_shipping', label: 'Free shipping'},
      {name: 'price', label: 'Price'},
      {name: 'brand', label: 'Brand'},
      {name: 'category', label: 'Category'},
    ],
    onlyListedAttributes: true,
  })
);

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