widgets numericRefinementList

Edit this page


The numeric refinement list is a widget that displays a list of numeric filters in a list. Those numeric filters are pre-configured with creating the widget.


The attribute passed to attributeName must be declared as an attribute for faceting in your Algolia settings.

The values inside this attribute must be JavaScript numbers and not strings.

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.numericRefinementList({ container: string|HTMLElement, attributeName: string, options: Array<NumericRefinementListOption>, templates: [NumericRefinementListTemplates], transformData: [NumericRefinementListTransforms], autoHideContainer: [boolean], cssClasses: [NumericRefinementListCSSClasses], collapsible: [boolean|{collapsible: boolean}], transformItems: [(Array<object>) => Array<object>], }: NumericRefinementListWidgetOptions);



  • containerstring|HTMLElement

    CSS Selector or HTMLElement to insert the widget.

  • attributeNamestring

    Name of the attribute for filtering.

  • optionsArray<NumericRefinementListOption>

    List of all the options.

  • templates[NumericRefinementListTemplates]

    Templates to use for the widget.

  • transformData[NumericRefinementListTransforms]

    Functions to change the data passes to the templates. Only item can be set.

  • autoHideContainer[boolean]
    Default value: true

    Hide the container when no results match.

  • cssClasses[NumericRefinementListCSSClasses]

    CSS classes to add to the wrapping elements.

  • collapsible[boolean|{collapsible: boolean}]
    Default value: false

    Hide the widget body and footer when clicking on header.

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

    Function to transform the items passed to the templates.


  • namestring

    Name of the option.

  • startnumber

    Lower bound of the option (>=).

  • endnumber

    Higher bound of the option (<=).


  • header[string|function]

    Header template.

  • item[string|function]

    Item template, provided with label (the name in the configuration), isRefined, url, value (the setting for the filter) data properties.


  • item({name: string, isRefined: boolean, url: string}) => object

    Transforms the data for a single item to render.


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

  • label[string|Array<string>]

    CSS class to add to each link element.

  • item[string|Array<string>]

    CSS class to add to each item element.

  • radio[string|Array<string>]

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

  • active[string|Array<string>]

    CSS class to add to each active element.


  • 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: '#popularity',
    attributeName: 'popularity',
    options: [
      {name: 'All'},
      {end: 500, name: 'less than 500'},
      {start: 500, end: 2000, name: 'between 500 and 2000'},
      {start: 2000, name: 'more than 2000'}
    templates: {
      header: 'Popularity'

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