Skip to main content
Signature
hitsPerPage({
  container: string | HTMLElement,
  items: object[],
  // Optional parameters
  cssClasses?: object,
  transformItems?: function,
});

​
Import

import { hitsPerPage } from "instantsearch.js/es/widgets";
View demo

​
About this widget

The hitsPerPage widget displays a menu for letting users change the number of displayed hits. If you only want to configure the number of hits per page without displaying a widget, you can use the configure widget with the hitsPerPage search parameter.

​
Examples

JavaScript
hitsPerPage({
  container: "#hits-per-page",
  items: [
    { label: "8 hits per page", value: 8, default: true },
    { label: "16 hits per page", value: 16 },
  ],
});

​
Options

​
container
string | HTMLElement
required
The CSS Selector or HTMLElement to insert the widget into.
hitsPerPage({
  // ...
  container: "#hits-per-page",
});
​
items
object[]
required
The list of available options, with each item:
  • label: string. The label to display in the option.
  • value: number. The number of hits to display per page.
  • default: boolean. The default hits per page on first search.
JavaScript
hitsPerPage({
  // ...
  items: [
    { label: "8 hits per page", value: 8, default: true },
    { label: "16 hits per page", value: 16 },
  ],
});
​
cssClasses
object
default:"{}"
The CSS classes you can override:
  • root. The root element of the widget.
  • select. The select element.
  • option. The option elements of the select.
JavaScript
hitsPerPage({
  // ...
  cssClasses: {
    root: "MyCustomHitsPerPage",
    select: [
      "MyCustomHitsPerPageSelect",
      "MyCustomHitsPerPageSelect--subclass",
    ],
  },
});
​
transformItems
function
default:"items => items"
A function that receives the list of items before they are displayed. It should return a new array with the same structure. Use this to transform, filter, or reorder the items.The function also has access to the full results data, including all standard response parameters and parameters from the helper, such as disjunctiveFacetsRefinements.
JavaScript
hitsPerPage({
  // ...
  transformItems(items) {
    return items.map((item) => ({
      ...item,
      label: item.label.toUpperCase(),
    }));
  },
});

// or, combined with results
hitsPerPage({
  // ...
  transformItems(items, { results }) {
    return items.map((item) => ({
      ...item,
      label:
        item.isRefined && results
          ? `${item.label} (${results.nbPages} pages in total)`
          : item.label,
    }));
  },
});

​
HTML output

HTML
<div class="ais-HitsPerPage">
  <select class="ais-HitsPerPage-select">
    <option class="ais-HitsPerPage-option" value="8">8 per page</option>
    <option class="ais-HitsPerPage-option" value="16">16 per page</option>
  </select>
</div>

​
Customize the UI with connectHitsPerPage

If you want to create your own UI of the hitsPerPage widget, you can use connectors. To use connectHitsPerPage, you can import it with the declaration relevant to how you installed InstantSearch.js. 
import { connectHitsPerPage } from "instantsearch.js/es/connectors";
Then it’s a 3-step process:
JavaScript
// 1. Create a render function
const renderHitsPerPage = (renderOptions, isFirstRender) => {
  // Rendering logic
};

// 2. Create the custom widget
const customHitsPerPage = connectHitsPerPage(renderHitsPerPage);

// 3. Instantiate
search.addWidgets([
  customHitsPerPage({
    // instance params
  }),
]);

​
Create a render function

This rendering function is called before the first search (init lifecycle step) and each time results come back from Algolia (render lifecycle step).
JavaScript
const renderHitsPerPage = (renderOptions, isFirstRender) => {
  const { items, canRefine, refine, widgetParams } = renderOptions;

  if (isFirstRender) {
    // Do some initial rendering and bind events
  }

  // Render the widget
};

​
Rendering options

​
items
object[]
The list of items the widget can display, with each item:
  • label: string. The label to display in the option.
  • value: number. The number of hits to display per page.
  • isRefined: boolean. Indicates if the item is the current refined value.
JavaScript
const renderHitsPerPage = (renderOptions, isFirstRender) => {
  const { items } = renderOptions;

  document.querySelector("#hits-per-page").innerHTML = `
    <select>
      ${items
        .map(
          (item) => `
            <option
              value="${item.value}"
              ${item.isRefined ? "selected" : ""}
            >
              ${item.label}
            </option>
          `,
        )
        .join("")}
    </select>
  `;
};
​
canRefine
boolean
since: v4.45.0
Whether the search can be refined.
JavaScript
const renderHitsPerPage = (renderOptions, isFirstRender) => {
  // `canRefine` is only available from v4.45.0
  // Use `hasNoResults` in earlier minor versions.
  const { items, canRefine } = renderOptions;

  document.querySelector("#hits-per-page").innerHTML = `
    <select ${!canRefine ? "disabled" : ""}>
      ${items
        .map(
          (item) => `
            <option
              value="${item.value}"
              ${item.isRefined ? "selected" : ""}
            >
              ${item.label}
            </option>
          `,
        )
        .join("")}
    </select>
  `;
};
​
refine
function
Sets the number of hits per page and triggers a search.
JavaScript
const renderHitsPerPage = (renderOptions, isFirstRender) => {
  const { items, refine } = renderOptions;
  const container = document.querySelector("#hits-per-page");

  if (isFirstRender) {
    const select = document.createElement("select");

    select.addEventListener("change", (event) => {
      refine(event.target.value);
    });

    container.appendChild(select);
  }

  container.querySelector("select").innerHTML = `
    ${items
      .map(
        (item) => `
          <option
            value="${item.value}"
            ${item.isRefined ? "selected" : ""}
          >
            ${item.label}
          </option>
        `,
      )
      .join("")}
  `;
};
​
widgetParams
object
All original widget options forwarded to the render function.
JavaScript
const renderHitsPerPage = (renderOptions, isFirstRender) => {
  const { widgetParams } = renderOptions;

  widgetParams.container.innerHTML = "...";
};

// ...

search.addWidgets([
  customHitsPerPage({
    container: document.querySelector("#hits-per-page"),
  }),
]);

​
Create and instantiate the custom widget

First, create your custom widgets using a rendering function. Then, instantiate them with parameters. There are two kinds of parameters you can pass:
  • Instance parameters. Predefined options that configure Algolia’s behavior.
  • Custom parameters. Parameters you define to make the widget reusable and adaptable.
Inside the renderFunction, both instance and custom parameters are accessible through connector.widgetParams.
JavaScript
const customHitsPerPage = connectHitsPerPage(renderHitsPerPage);

search.addWidgets([
  customHitsPerPage({
    items,
    transformItems,
  }),
]);

​
Instance options

​
items
object[]
required
The list of available options, with each item:
  • label: string. The label to display in the option.
  • value: number. The number of hits to display per page.
  • default: boolean. The default hits per page on first search.
JavaScript
customHitsPerPage({
  items: [
    { label: "8 hits per page", value: 8, default: true },
    { label: "16 hits per page", value: 16 },
  ],
});
​
transformItems
function
default:"items => items"
A function that receives the list of items before they are displayed. It should return a new array with the same structure. Use this to transform, filter, or reorder the items.The function also has access to the full results data, including all standard response parameters and parameters from the helper, such as disjunctiveFacetsRefinements.
JavaScript
customHitsPerPage({
  // ...
  transformItems(items) {
    return items.map((item) => ({
      ...item,
      label: item.label.toUpperCase(),
    }));
  },
});

// or, combined with results
customHitsPerPage({
  // ...
  transformItems(items, { results }) {
    return items.map((item) => ({
      ...item,
      label:
        item.isRefined && results
          ? `${item.label} (${results.nbPages} pages in total)`
          : item.label,
    }));
  },
});

​
Full example

<div id="hits-per-page"></div>
⌘I