Skip to main content
The refinementList widget displays a list of facet values that users can select to filter results. It’s one of the most common filtering widgets, supporting multi-selection and search within facets.

​
Usage

const refinementList = instantsearch.widgets.refinementList({
  container: '#brand-list',
  attribute: 'brand',
});

search.addWidget(refinementList);

​
Examples

​
Basic Refinement List

instantsearch.widgets.refinementList({
  container: '#categories',
  attribute: 'categories',
  limit: 10,
});

​
With Search for Facet Values

instantsearch.widgets.refinementList({
  container: '#brands',
  attribute: 'brand',
  searchable: true,
  searchablePlaceholder: 'Search brands...',
  limit: 5,
  showMore: true,
  showMoreLimit: 20,
});

​
With OR/AND Operator

// OR operator (default) - shows results matching ANY selected value
instantsearch.widgets.refinementList({
  container: '#categories',
  attribute: 'categories',
  operator: 'or',
});

// AND operator - shows results matching ALL selected values
instantsearch.widgets.refinementList({
  container: '#features',
  attribute: 'features',
  operator: 'and',
});

​
With Custom Sorting

instantsearch.widgets.refinementList({
  container: '#brands',
  attribute: 'brand',
  sortBy: ['isRefined', 'count:desc', 'name:asc'],
});

​
Options

​
container
string | HTMLElement
required
CSS Selector or HTMLElement to insert the widget.
​
attribute
string
required
The name of the attribute in your records. Must be declared as an attribute for faceting in your Algolia settings.
​
operator
'or' | 'and'
default:"'or'"
How to apply multiple selections:
  • 'or': Show results matching ANY selected value
  • 'and': Show results matching ALL selected values
​
limit
number
default:"10"
Maximum number of facet values to display.
​
showMore
boolean
default:"false"
Whether to display a “Show more” button.
​
showMoreLimit
number
default:"20"
Maximum number of facet values to display when “Show more” is clicked.
​
sortBy
string[] | function
default:"['isRefined', 'count:desc', 'name:asc']"
How to sort refinements. Can be an array of strings or a sorting function.Available string values:
  • 'isRefined' - Refined values first
  • 'count:asc' - By count ascending
  • 'count:desc' - By count descending
  • 'name:asc' - Alphabetically ascending
  • 'name:desc' - Alphabetically descending
​
searchable
boolean
default:"false"
Add a search input to filter facet values. Requires the attribute to be searchable for faceting.
​
searchablePlaceholder
string
default:"'Search...'"
Placeholder text for the search input.
​
searchableIsAlwaysActive
boolean
default:"true"
If false, the search input is disabled when there are fewer items than the limit.
​
searchableEscapeFacetValues
boolean
default:"true"
Whether to escape facet values in the search results.
​
transformItems
function
Function to transform the items before rendering.
(items: object[]) => object[]
​
templates
object
Templates to customize the widget rendering.
​
cssClasses
object
CSS classes to add to the widget elements.

​
HTML Output

<div class="ais-RefinementList">
  <div class="ais-RefinementList-searchBox">
    <!-- SearchBox for facet values -->
  </div>
  <ul class="ais-RefinementList-list">
    <li class="ais-RefinementList-item ais-RefinementList-item--selected">
      <label class="ais-RefinementList-label">
        <input class="ais-RefinementList-checkbox" type="checkbox" checked />
        <span class="ais-RefinementList-labelText">Apple</span>
        <span class="ais-RefinementList-count">746</span>
      </label>
    </li>
    <li class="ais-RefinementList-item">
      <label class="ais-RefinementList-label">
        <input class="ais-RefinementList-checkbox" type="checkbox" />
        <span class="ais-RefinementList-labelText">Samsung</span>
        <span class="ais-RefinementList-count">633</span>
      </label>
    </li>
  </ul>
  <button class="ais-RefinementList-showMore">Show more</button>
</div>

​
Requirements

The attribute must be declared as an attribute for faceting in your Algolia index settings.For searchable faceting, the attribute must also be searchable for faceting.