widgets hitsPerPageSelector

Edit this page


The hitsPerPageSelector widget gives the user the ability to change the number of results displayed in the hits widget.

You can specify the default hits per page using a boolean in the items[] array. If none is specified, this first hits per page option will be picked.

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.hitsPerPageSelector({ container: string|HTMLElement, items: Array<HitsPerPageSelectorItems>, autoHideContainer: [boolean], cssClasses: [HitsPerPageSelectorCSSClasses], transformItems: [(Array<object>) => Array<object>], }: HitsPerPageSelectorWidgetOptions);



  • containerstring|HTMLElement

    CSS Selector or HTMLElement to insert the widget.

  • itemsArray<HitsPerPageSelectorItems>

    Array of objects defining the different values and labels.

  • autoHideContainer[boolean]
    Default value: false

    Hide the container when no results match.

  • cssClasses[HitsPerPageSelectorCSSClasses]

    CSS classes to be added.

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

    Function to transform the items passed to the templates.


  • valuenumber

    number of hits to display per page.

  • labelstring

    Label to display in the option.

  • defaultboolean

    The default hits per page on first search.


  • root[string|Array<string>]

    CSS classes added to the outer <div>.

  • select[string|Array<string>]

    CSS classes added to the parent <select>.

  • item[string|Array<string>]

    CSS classes added to each <option>.


  • 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: '#hits-per-page-selector',
    items: [
      {value: 3, label: '3 per page', default: true},
      {value: 6, label: '6 per page'},
      {value: 12, label: '12 per page'},

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