hitsPerPage

Signature

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

Import

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

const { hitsPerPage } = instantsearch.widgets;
// or directly use instantsearch.widgets.hitsPerPage()

See this widget in action

Preview this widget and its behavior.

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",
});

hitsPerPage({
  // ...
  container: document.querySelector("#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";

const { connectHitsPerPage } = instantsearch.connectors;
// or directly use instantsearch.connectors.connectHitsPerPage()

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("")}
  `;
};

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"),
  }),
]);

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"

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>

// Create the render function
const renderHitsPerPage = (renderOptions, isFirstRender) => {
  // `canRefine` is only available from v4.45.0
  // Use `hasNoResults` in earlier minor versions.
  const { items, canRefine, refine, widgetParams } = renderOptions;

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

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

    widgetParams.container.appendChild(select);
  }

  const select = widgetParams.container.querySelector("select");

  select.disabled = !canRefine;

  select.innerHTML = `
    ${items
      .map(
        (item) => `
          <option
            value="${item.value}"
            ${item.isRefined ? "selected" : ""}
          >
            ${item.label}
          </option>
        `,
      )
      .join("")}
  `;
};

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

// Instantiate the custom widget
search.addWidgets([
  customHitsPerPage({
    container: document.querySelector("#hits-per-page"),
    items: [
      { label: "8 hits per page", value: 8, default: true },
      { label: "16 hits per page", value: 16 },
    ],
  }),
]);

InstantSearch.js

Import

See this widget in action

About this widget

Examples

Options

HTML output

Customize the UI with `connectHitsPerPage`

Create a render function

Rendering options

Create and instantiate the custom widget

Instance options

Full example

​Import

See this widget in action

​About this widget

​Examples

​Options

​HTML output

​Customize the UI with connectHitsPerPage

​Create a render function

​Rendering options

​Create and instantiate the custom widget

​Instance options

​Full example

Import

About this widget

Examples

Options

HTML output

Customize the UI with `connectHitsPerPage`

Create a render function

Rendering options

Create and instantiate the custom widget

Instance options

Full example