> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# hitsPerPage

> Lets users change the number of search results per page.

```ts Signature theme={"system"}
hitsPerPage({
  container: string | HTMLElement,
  items: object[],
  // Optional parameters
  cssClasses?: object,
  transformItems?: function,
});
```

## Import

<CodeGroup>
  ```js Package manager theme={"system"}
  import { hitsPerPage } from "instantsearch.js/es/widgets";
  ```

  ```js CDN theme={"system"}
  const { hitsPerPage } = instantsearch.widgets;
  // or directly use instantsearch.widgets.hitsPerPage()
  ```
</CodeGroup>

<Card title="See this widget in action" icon="monitor-play" href="https://instantsearchjs.netlify.app/stories/js/?path=/story/pagination-hitsperpage--default" horizontal>
  Preview this widget and its behavior.
</Card>

## 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`](/doc/api-reference/widgets/configure/js) widget with the [`hitsPerPage`](/doc/api-reference/api-parameters/hitsPerPage) search parameter.

## Examples

```js JavaScript icon=code theme={"system"}
hitsPerPage({
  container: "#hits-per-page",
  items: [
    { label: "8 hits per page", value: 8, default: true },
    { label: "16 hits per page", value: 16 },
  ],
});
```

## Options

<ParamField body="container" type="string | HTMLElement" required>
  The CSS Selector or `HTMLElement` to insert the widget into.

  <CodeGroup>
    ```js string theme={"system"}
    hitsPerPage({
      // ...
      container: "#hits-per-page",
    });
    ```

    ```js HTMLElement theme={"system"}
    hitsPerPage({
      // ...
      container: document.querySelector("#hits-per-page"),
    });
    ```
  </CodeGroup>
</ParamField>

<ParamField body="items" type="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.

  ```js JavaScript icon=code theme={"system"}
  hitsPerPage({
    // ...
    items: [
      { label: "8 hits per page", value: 8, default: true },
      { label: "16 hits per page", value: 16 },
    ],
  });
  ```
</ParamField>

<ParamField body="cssClasses" type="object" default="{}">
  The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js#style-your-widgets):

  * `root`. The root element of the widget.
  * `select`. The `select` element.
  * `option`. The `option` elements of the `select`.

  ```js JavaScript icon=code theme={"system"}
  hitsPerPage({
    // ...
    cssClasses: {
      root: "MyCustomHitsPerPage",
      select: [
        "MyCustomHitsPerPageSelect",
        "MyCustomHitsPerPageSelect--subclass",
      ],
    },
  });
  ```
</ParamField>

<ParamField body="transformItems" type="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](/doc/guides/building-search-ui/going-further/backend-search/in-depth/understanding-the-api-response/)
  and [parameters from the helper](https://community.algolia.com/algoliasearch-helper-js/reference.html#query-parameters),
  such as `disjunctiveFacetsRefinements`.

  ```js JavaScript icon=code theme={"system"}
  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,
      }));
    },
  });
  ```
</ParamField>

## HTML output

```html HTML icon=code-xml theme={"system"}
<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.

<CodeGroup>
  ```js Package manager theme={"system"}
  import { connectHitsPerPage } from "instantsearch.js/es/connectors";
  ```

  ```js CDN theme={"system"}
  const { connectHitsPerPage } = instantsearch.connectors;
  // or directly use instantsearch.connectors.connectHitsPerPage()
  ```
</CodeGroup>

Then it's a 3-step process:

```js JavaScript icon=code theme={"system"}
// 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).

```js JavaScript icon=code theme={"system"}
const renderHitsPerPage = (renderOptions, isFirstRender) => {
  const { items, canRefine, refine, widgetParams } = renderOptions;

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

  // Render the widget
};
```

#### Rendering options

<ParamField body="items" type="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.

  ```js JavaScript icon=code theme={"system"}
  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>
    `;
  };
  ```
</ParamField>

<ParamField body="canRefine" type="boolean" post={["since: v4.45.0"]}>
  Whether the search can be refined.

  ```js JavaScript icon=code theme={"system"}
  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>
    `;
  };
  ```
</ParamField>

<ParamField body="refine" type="function">
  Sets the number of hits per page and triggers a search.

  ```js JavaScript icon=code theme={"system"}
  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("")}
    `;
  };
  ```
</ParamField>

<ParamField body="widgetParams" type="object">
  All original widget options forwarded to the render function.

  ```js JavaScript icon=code theme={"system"}
  const renderHitsPerPage = (renderOptions, isFirstRender) => {
    const { widgetParams } = renderOptions;

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

  // ...

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

### 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`.

```js JavaScript icon=code theme={"system"}
const customHitsPerPage = connectHitsPerPage(renderHitsPerPage);

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

#### Instance options

<ParamField body="items" type="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.

  ```js JavaScript icon=code theme={"system"}
  customHitsPerPage({
    items: [
      { label: "8 hits per page", value: 8, default: true },
      { label: "16 hits per page", value: 16 },
    ],
  });
  ```
</ParamField>

<ParamField body="transformItems" type="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](/doc/guides/building-search-ui/going-further/backend-search/in-depth/understanding-the-api-response/)
  and [parameters from the helper](https://community.algolia.com/algoliasearch-helper-js/reference.html#query-parameters),
  such as `disjunctiveFacetsRefinements`.

  ```js JavaScript icon=code theme={"system"}
  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,
      }));
    },
  });
  ```
</ParamField>

### Full example

<CodeGroup>
  ```html HTML theme={"system"}
  <div id="hits-per-page"></div>
  ```

  ```js JavaScript theme={"system"}
  // 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 },
      ],
    }),
  ]);
  ```
</CodeGroup>