RefinementList | React InstantSearch V6 (Deprecated)

Signature# Found an issue? Edit this guide A Edit this guide

<RefinementList
  attribute={string}
  // Optional parameters
  defaultRefinement={string[]}
  facetOrdering={boolean}
  operator={string}
  limit={number}
  showMore={boolean}
  showMoreLimit={number}
  searchable={boolean}
  transformItems={function}
  translations={object}
/>

About this widget# Found an issue? Edit this guide A Edit this guide

The RefinementList widget is one of the most common widgets that you can find in a search UI. With this widget, the user can filter the dataset based on facet values.

The widget only displays the most relevant facet values for the current search context.

This widget also implements search for facet values, which is a mini search inside the values of the facets. This makes it easy to deal with uncommon facet values.

Requirements#

The attribute provided to the widget must be added in attributes for faceting, either on the dashboard or using attributesForFaceting with the API.

If you are using the searchable prop, you also need to make the attribute searchable using the dashboard or using the searchable modifier of attributesForFaceting with the API.

Examples# Found an issue? Edit this guide A Edit this guide

1
2
3
import { RefinementList } from 'react-instantsearch-dom';

<RefinementList attribute="brand" />

Props# Found an issue? Edit this guide A Edit this guide

attribute#

The name of the attribute in the record.

1
<RefinementList attribute="brand" />

defaultRefinement#

The value of the item selected by default.

1
2
3
4
<RefinementList
  // ...
  defaultRefinement={['Apple']}
/>

facetOrdering#

Apply the rules of renderingContent.facetOrdering for this widget.

1
2
3
4
<RefinementList
  // ...
  facetOrdering
/>

operator#

How to apply the refinements.

1
2
3
4
<RefinementList
  // ...
  operator="and"
/>

limit#

How many facet values to retrieve. When you enable the #{showMore} feature, this is the number of facet values to display before clicking the “Show more” button.

1
2
3
4
<RefinementList
  // ...
  limit={20}
/>

showMore#

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

1
2
3
4
<RefinementList
  // ...
  showMore
/>

showMoreLimit#

The maximum number of displayed items. Only used when #{showMore} is set to true.

1
2
3
4
<RefinementList
  // ...
  showMoreLimit={30}
/>

searchable#

Whether to add a search input to let the user search for more facet values.

To make this feature work, you need to make the attribute searchable using the dashboard or using the searchable modifier of attributesForFaceting with the API.

Note that this feature is not available if you’re using Multi Index Search.

1
2
3
4
<RefinementList
  // ...
  searchable
/>

transformItems#

Modifies the items being displayed, for example, to filter or sort them. It takes items as argument and expects them back in return.

1
2
3
4
5
6
7
8
9
<RefinementList
  // ...
  transformItems={items =>
    items.map(item => ({
      ...item,
      label: item.label.toUpperCase(),
    }))
  }
/>

translations#

A mapping of keys to translation values.

• showMore: the label of the “Show more” button. Accepts one boolean parameter that is true if the values are expanded, false otherwise.
• noResults: the label of the no results text when no search for facet values results are found.
• submitTitle: the alternative text of the submit icon.
• resetTitle: the alternative text of the reset button icon.
• placeholder: the label of the input placeholder.

1
2
3
4
5
6
7
8
9
10
11
12
13
<RefinementList
  // ...
  translations={{
    showMore(expanded) {
      return expanded ? 'Show less' : 'Show more';
    },
    noResults: 'No results',
    submitTitle: 'Submit your search query.',
    resetTitle: 'Clear your search query.',
    placeholder: 'Search here...',
  }}
/>