Skip to main content
The HitsPerPage connector provides the logic to build a custom widget that lets users select the number of results to display per page.

​
Usage

import { connectHitsPerPage } from 'instantsearch.js/es/connectors';

const customHitsPerPage = connectHitsPerPage(
  (renderOptions, isFirstRender) => {
    const { items, refine, widgetParams } = renderOptions;
    const { container } = widgetParams;
    
    container.innerHTML = `
      <select>
        ${items.map(item => `
          <option 
            value="${item.value}"
            ${item.isRefined ? 'selected' : ''}
          >
            ${item.label}
          </option>
        `).join('')}
      </select>
    `;
    
    container.querySelector('select').addEventListener('change', (e) => {
      refine(parseInt(e.target.value));
    });
  }
);

search.addWidgets([
  customHitsPerPage({
    container: document.querySelector('#hits-per-page'),
    items: [
      { label: '10 per page', value: 10, default: true },
      { label: '20 per page', value: 20 },
      { label: '50 per page', value: 50 },
    ],
  }),
]);

​
Connector Options

​
items
Array<HitsPerPageItem>
required
Array of objects defining the different values and labels.Each item must have:
  • label: Label to display in the option
  • value: Number of hits to display per page
  • default: Whether this is the default hits per page (one item must be default)
​
transformItems
(items: object[]) => object[]
Function to transform the items passed to the templates.

​
Render Options

​
items
Array<HitsPerPageRenderItem>
Array of objects defining the different values and labels.Each item has:
  • label: Label to display in the option
  • value: Number of hits to display per page
  • isRefined: Indicates if it’s the current refined value
​
refine
(value: number) => void
Sets the number of hits per page and triggers a search.
​
createURL
(value: number) => string
Creates the URL for a single item name in the list.
​
canRefine
boolean
Indicates if search state can be refined.
​
hasNoResults
boolean
Indicates whether or not the search has results.
This parameter is deprecated. Use canRefine instead.
​
widgetParams
object
The options passed to the connector.