Skip to main content
The <RefinementList> component displays a list of facet values where users can select multiple values to refine their search.

​
Import

import { RefinementList } from 'react-instantsearch';

​
Props

​
attribute
string
required
The attribute to create the refinement list from.
<RefinementList attribute="brand" />
​
operator
'and' | 'or'
default:"or"
How to apply multiple selections.
<RefinementList attribute="brand" operator="and" />
​
limit
number
default:"10"
Maximum number of items to display.
<RefinementList attribute="brand" limit={20} />
​
showMore
boolean
default:"false"
Whether to display a “Show more” button.
<RefinementList attribute="brand" showMore={true} />
​
showMoreLimit
number
default:"20"
Maximum number of items to display when “Show more” is clicked.
<RefinementList
  attribute="brand"
  showMore={true}
  showMoreLimit={50}
/>
​
searchable
boolean
default:"false"
Whether to display a search box to filter the list.
<RefinementList attribute="brand" searchable={true} />
​
searchablePlaceholder
string
Placeholder text for the search box.
<RefinementList
  attribute="brand"
  searchable={true}
  searchablePlaceholder="Search brands..."
/>
​
searchableSelectOnSubmit
boolean
default:"true"
Whether to select the first item when submitting the search box.
<RefinementList
  attribute="brand"
  searchable={true}
  searchableSelectOnSubmit={false}
/>
​
sortBy
string[] | function
default:"['isRefined', 'count:desc', 'name:asc']"
How to sort the items.
<RefinementList
  attribute="brand"
  sortBy={['count:desc', 'name:asc']}
/>
​
escapeFacetValues
boolean
default:"true"
Whether to escape the facet values.
​
transformItems
function
Transform the refinement items before displaying them.
<RefinementList
  attribute="brand"
  transformItems={(items) =>
    items.map((item) => ({
      ...item,
      label: item.label.toUpperCase(),
    }))
  }
/>
​
translations
object
Customize the text strings.
<RefinementList
  attribute="brand"
  translations={{
    showMoreButtonText: ({ isShowingMore }) =>
      isShowingMore ? 'Show less' : 'Show more',
    noResultsText: 'No results.',
    submitButtonTitle: 'Submit',
    resetButtonTitle: 'Clear',
  }}
/>
​
classNames
object
CSS classes to customize the component styling.

​
Example

import { InstantSearch, RefinementList, SearchBox, Hits } from 'react-instantsearch';
import { liteClient as algoliasearch } from 'algoliasearch/lite';

const searchClient = algoliasearch(
  'YourApplicationID',
  'YourSearchOnlyAPIKey'
);

function App() {
  return (
    <InstantSearch searchClient={searchClient} indexName="products">
      <div className="container">
        <aside className="filters">
          <RefinementList attribute="brand" />
          <RefinementList attribute="category" />
        </aside>
        <main>
          <SearchBox />
          <Hits />
        </main>
      </div>
    </InstantSearch>
  );
}

function App() {
  return (
    <InstantSearch searchClient={searchClient} indexName="products">
      <RefinementList
        attribute="brand"
        searchable={true}
        searchablePlaceholder="Search brands..."
        showMore={true}
        limit={10}
        showMoreLimit={50}
      />
    </InstantSearch>
  );
}

Build docs developers (and LLMs) love

Get started for freeTalk to us