widgets refinementList

Edit this page


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 attributeName 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.


const search = instantsearch( /* parameters */ );

const widget = instantsearch.widgets.refinementList({ container: string|HTMLElement, attributeName: string, operator: ["and"|"or"], sortBy: [Array<string>|function], transformItems: [(Array<object>) => Array<object>], limit: [number], searchForFacetValues: [SearchForFacetOptions|boolean], showMore: [RefinementListShowMoreOptions|boolean], templates: [RefinementListTemplates], transformData: [RefinementListTransforms], autoHideContainer: [boolean], cssClasses: [RefinementListCSSClasses], collapsible: [RefinementListCollapsibleOptions|boolean], }: RefinementListWidgetOptions);



  • containerstring|HTMLElement

    CSS Selector or HTMLElement to insert the widget.

  • attributeNamestring

    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.

  • limit[number]
    Default value: 10

    How much facet values to get. When the show more feature is activated this is the minimum number of facets requested (the show more button is not in active state).

  • searchForFacetValues[SearchForFacetOptions|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.

  • showMore[RefinementListShowMoreOptions|boolean]
    Default value: false

    Limit the number of results and display a showMore button.

  • templates[RefinementListTemplates]

    Templates to use for the widget.

  • transformData[RefinementListTransforms]

    Functions to update the values before applying the templates.

  • autoHideContainer[boolean]
    Default value: true

    Hide the container when no items in the refinement list.

  • cssClasses[RefinementListCSSClasses]

    CSS classes to add to the wrapping elements.

  • collapsible[RefinementListCollapsibleOptions|boolean]
    Default value: false

    If true, the user can collapse the widget. If the use clicks on the header, it will hide the content and the footer.


  • placeholder[string]

    Value of the search field placeholder.

  • templates[SearchForFacetTemplates]

    Templates to use for search for facet values.

  • isAlwaysActive[boolean]
    Default value: false

    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.

  • escapeFacetValues[boolean]
    Default value: false

    When activated, it will escape the facet values that are returned from Algolia. In this case, the surrounding tags will always be <em></em>.


  • noResults[string]

    Templates to use for search for facet values.



  • active[string]

    Template used when showMore was clicked.

  • inactive[string]

    Template used when showMore not clicked.


  • header[string|(object) => string]

    Header template, provided with refinedFacetsCount data property.

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

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


  • 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.


  • item[function]

    Function to change the object passed to the item template.


  • root[string|Array<string>]

    CSS class to add to the root element.

  • header[string|Array<string>]

    CSS class to add to the header element.

  • body[string|Array<string>]

    CSS class to add to the body element.

  • list[string|Array<string>]

    CSS class to add to the list element.

  • item[string|Array<string>]

    CSS class to add to each item element.

  • active[string|Array<string>]

    CSS class to add to each active 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).

  • count[string|Array<string>]

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


  • collapsed[boolean]

    Initial collapsed state of a collapsible 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


    container: '#brands',
    attributeName: 'brand',
    operator: 'or',
    limit: 10,
    templates: {
      header: 'Brands'

Can't find what you are looking for? Open an issue, we'll get back to you.