widgets refinementList

Description

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.

Requirements

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.

Live example

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

Usage

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);

Options

RefinementListWidgetOptions

• containerstring|HTMLElement

  CSS Selector or HTMLElement to insert the widget.

• attributestring

  Name of the attribute for faceting.

• operator["and"|"or"]
  Default value: "or"

  How to apply refinements. Possible values: or, and

• sortBy[Array<string>|function]
  Default value: ["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.

• transformItems[(Array<object>) => Array<object>]

  Function to transform the items passed to the templates.

• searchable[boolean]
  Default value: 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.

• limit[number]
  Default value: 10

  The minimum number of facet values to retrieve.

• showMore[boolean]
  Default value: false

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

• showMoreLimit[number]
  Default value: 20

  The max number of items to display if the widget

• searchablePlaceholder[string]

  Value of the search field placeholder.

• searchableIsAlwaysActive[boolean]
  Default value: 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.

• searchableEscapeFacetValues[boolean]
  Default value: 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>.

• templates[RefinementListTemplates]

  Templates to use for the widget.

• cssClasses[RefinementListCSSClasses]

  CSS classes to add to the wrapping elements.

RefinementListTemplates

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

  Item template, provided with label, highlighted, value, count, isRefined, url data properties.

• searchableNoResults[string|function]

  Templates to use for search for facet values.

• showMoreText[string|function]

  Template used for the show more text, provided with isShowingMore data property.

RefinementListItemData

• countnumber

  The number of occurrences of the facet in the result set.

• isRefinedboolean

  True if the value is selected.

• labelstring

  The label to display.

• valuestring

  The value used for refining.

• highlightedstring

  The label highlighted (when using search for facet values). This value is displayed in the default template.

• urlstring

  The url with this refinement selected.

• cssClassesobject

  Object containing all the classes computed for the item.

RefinementListCSSClasses

• root[string|Array<string>]

  CSS class to add to the root element.

• noRefinementRoot[string|Array<string>]

  CSS class to add to the root element when no refinements.

• noResults[string|Array<string>]

  CSS class to add to the root element with no results.

• list[string|Array<string>]

  CSS class to add to the list element.

• item[string|Array<string>]

  CSS class to add to each item element.

• selectedItem[string|Array<string>]

  CSS class to add to each selected element.

• label[string|Array<string>]

  CSS class to add to each label element (when using the default template).

• checkbox[string|Array<string>]

  CSS class to add to each checkbox element (when using the default template).

• labelText[string|Array<string>]

  CSS class to add to each label text element.

• showMore[string|Array<string>]

  CSS class to add to the show more element

• disabledShowMore[string|Array<string>]

  CSS class to add to the disabledshow more element

• count[string|Array<string>]

  CSS class to add to each count element (when using the default template).

Widget

• render[function]

  Called after each search response has been received

• getConfiguration[function]

  Let the widget update the configuration of the search with new parameters

• init[function]

  Called once before the first search

Example

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.