The refinement list widget is one of the most common widget that you can find in a search UI. With this widget, the user can filter the dataset based on facets.
The refinement list displays only the most relevant facets for the current search context. The sort option only affects the facet that are returned by the engine, not which facets are returned.
This widget also implements search for facet values, which is a mini search inside the values of the facets. This makes easy to deal with uncommon facet values.
The attribute passed to attribute
must be declared as an
attribute for faceting
in your Algolia settings.
If you also want to use search for facet values on this attribute, you need to make it searchable using the dashboard or using the API.
You can find an example at the end of the page or a live example in our widget showcase.
const search = instantsearch( /* parameters */ );
const widget = instantsearch.widgets.refinementList({
container: string|HTMLElement,
attribute: string,
operator: ["and"|"or"],
sortBy: [Array<string>|function],
transformItems: [(Array<object>) => Array<object>],
searchable: [boolean],
limit: [number],
showMore: [boolean],
showMoreLimit: [number],
searchablePlaceholder: [string],
searchableIsAlwaysActive: [boolean],
searchableEscapeFacetValues: [boolean],
templates: [RefinementListTemplates],
cssClasses: [RefinementListCSSClasses],
}: RefinementListWidgetOptions);
search.addWidget(widget);
string|HTMLElement
CSS Selector or HTMLElement to insert the widget.
string
Name of the attribute for faceting.
["and"|"or"]
"or"
How to apply refinements. Possible values: or
, and
[Array<string>|function]
["isRefined","count:desc","name:asc"]
How to sort refinements. Possible values: count:asc
count:desc
name:asc
name:desc
isRefined
.
You can also use a sort function that behaves like the standard Javascript compareFunction.
[(Array<object>) => Array<object>]
Function to transform the items passed to the templates.
[boolean]
false
Add a search input to let the user search for more facet values. In order to make this feature work, you need to make the attribute searchable using the API or the dashboard.
[number]
10
The minimum number of facet values to retrieve.
[boolean]
false
Whether to display a button that expands the number of items.
[number]
20
The max number of items to display if the widget
[string]
Value of the search field placeholder.
[boolean]
true
When false
the search field will become disabled if
there are less items to display than the options.limit
, otherwise the search field is always usable.
[boolean]
true
When activated, it will escape the facet values that are returned
from Algolia. In this case, the surrounding tags will always be <mark></mark>
.
[RefinementListTemplates]
Templates to use for the widget.
[RefinementListCSSClasses]
CSS classes to add to the wrapping elements.
[string|(RefinementListItemData) => string]
Item template, provided with label
, highlighted
, value
, count
, isRefined
, url
data properties.
[string|function]
Templates to use for search for facet values.
[string|function]
Template used for the show more text, provided with isShowingMore
data property.
number
The number of occurrences of the facet in the result set.
boolean
True if the value is selected.
string
The label to display.
string
The value used for refining.
string
The label highlighted (when using search for facet values). This value is displayed in the default template.
string
The url with this refinement selected.
object
Object containing all the classes computed for the item.
[string|Array<string>]
CSS class to add to the root element.
[string|Array<string>]
CSS class to add to the root element when no refinements.
[string|Array<string>]
CSS class to add to the root element with no results.
[string|Array<string>]
CSS class to add to the list element.
[string|Array<string>]
CSS class to add to each item element.
[string|Array<string>]
CSS class to add to each selected element.
[string|Array<string>]
CSS class to add to each label element (when using the default template).
[string|Array<string>]
CSS class to add to each checkbox element (when using the default template).
[string|Array<string>]
CSS class to add to each label text element.
[string|Array<string>]
CSS class to add to the show more element
[string|Array<string>]
CSS class to add to the disabledshow more element
[string|Array<string>]
CSS class to add to each count element (when using the default template).
[function]
Called after each search response has been received
[function]
Let the widget update the configuration of the search with new parameters
[function]
Called once before the first search
search.addWidget(
instantsearch.widgets.refinementList({
container: '#brands',
attribute: 'brand',
operator: 'or',
limit: 10,
})
);
Can't find what you are looking for? Open an issue, we'll get back to you.