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

<Note>
  This is the **React InstantSearch v7** documentation.
  If you're upgrading from v6, see the [upgrade guide](/doc/guides/building-search-ui/upgrade-guides/react/#migrate-from-react-instantsearch-v6-to-react-instantsearch-v7).
  If you were using React InstantSearch Hooks,
  this v7 documentation applies—just check for [necessary changes](/doc/guides/building-search-ui/upgrade-guides/react/#migrate-from-react-instantsearch-hooks-to-react-instantsearch-v7).
  To continue using v6, you can find the [archived documentation](https://algolia.com/old-docs/deprecated/instantsearch/react/v6/api-reference/instantsearch/).
</Note>

```tsx Signature theme={"system"}
<HitsPerPage
  items={object[]}
  // Optional props
  transformItems={function}
  classNames={object}
  ...props={ComponentProps<'div'>}
/>
```

## Import

```jsx JavaScript icon=code theme={"system"}
import { HitsPerPage } from "react-instantsearch";
```

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

## About this widget

`<HitsPerPage>` is a widget that displays a menu of options to change the number of results per page.

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

<Tip>You can also create your own UI with [`useHitsPerPage`](#hook).</Tip>

## Examples

```jsx JavaScript icon=code theme={"system"}
import React from "react";
import { liteClient as algoliasearch } from "algoliasearch/lite";
import { InstantSearch, HitsPerPage } from "react-instantsearch";

const searchClient = algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey");

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <HitsPerPage
        items={[
          { label: "8 hits per page", value: 8, default: true },
          { label: "16 hits per page", value: 16 },
        ]}
      />
    </InstantSearch>
  );
}
```

## Props

<ParamField body="items" type="HitsPerPagePropsItem[]" required>
  The list of available options, with each item:

  * `label`. The label to display in the option.
  * `value`. The number of hits to display per page.
  * `default`. The default hits per page on first search.

  <CodeGroup>
    ```jsx JavaScript theme={"system"}
    <HitsPerPage
      items={[
        { label: "8 hits per page", value: 8, default: true },
        { label: "16 hits per page", value: 16 },
      ]}
    />;
    ```

    ```ts TypeScript theme={"system"}
    type HitsPerPagePropsItem = {
      /**
       * Label to display in the option.
       */
      label: string;
      /**
       * Number of hits to display per page.
       */
      value: number;
      /**
       * The default hits per page on first search.
       * @default false
       */
      default?: boolean;
    };
    ```
  </CodeGroup>
</ParamField>

<ParamField body="transformItems">
  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`.

  <CodeGroup>
    ```jsx JavaScript theme={"system"}
    const transformItems = (items) => {
      return items.map((item) => ({
        ...item,
        label: item.label.toUpperCase(),
      }));
    };

    function Search() {
      return (
        <HitsPerPage
          // ...
          transformItems={transformItems}
        />
      );
    }
    ```

    ```tsx TypeScript theme={"system"}
    import type { HitsPerPageProps } from 'react-instantsearch';

    const transformItems: HitsPerPageProps['transformItems'] = (items) => {
      return items.map((item) => ({
        ...item,
        label: item.label.toUpperCase(),
      }));
    };

    function Search() {
      return (
        <HitsPerPage
          // ...
          transformItems={transformItems}
        />
      );
    }
    ```
  </CodeGroup>
</ParamField>

<ParamField body="classNames" type="Partial<HitsPerPageClassNames>">
  The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/react#style-your-widgets) and pass to the widget's elements.
  It's useful to style widgets with class-based CSS frameworks like [Bootstrap](https://getbootstrap.com) or [Tailwind CSS](https://tailwindcss.com).

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

  ```jsx JavaScript icon=code theme={"system"}
  <HitsPerPage
    // ...
    classNames={{
      root: "MyCustomHitsPerPage",
      select: "MyCustomHitsPerPageSelect",
      option: "MyCustomHitsPerPageOption MyCustomHitsPerPageOption--subclass",
    }}
  />;
  ```
</ParamField>

<ParamField body="...props" type="React.ComponentProps<'div'>">
  Any `<div>` prop to forward to the root element of the widget.

  ```jsx JavaScript icon=code theme={"system"}
  <HitsPerPage
    // ...
    className="MyCustomHitsPerPage"
    title="My custom title"
  />;
  ```
</ParamField>

## Hook

React InstantSearch let you create your own UI for the `<HitsPerPage>` widget with `useHitsPerPage`.
Hooks provide APIs to access the widget state and interact with InstantSearch.

The `useHitsPerPage` Hook accepts [parameters](#parameters) and returns [APIs](#hook).
It must be used inside the [`<InstantSearch>`](/doc/api-reference/widgets/instantsearch/react) component.

### Usage

First, create your React component:

```jsx JavaScript icon=code theme={"system"}
import { useHitsPerPage } from "react-instantsearch";

function CustomHitsPerPage(props) {
  const { items, refine, createURL, canRefine } = useHitsPerPage(props);

  return <>{/*Your JSX*/}</>;
}
```

Then, render the widget:

```jsx JavaScript icon=code theme={"system"}
<CustomHitsPerPage {...props} />;
```

### Parameters

Hooks accept parameters. You can either pass them manually or forward props from a custom component.

<Note>
  When passing functions to Hooks, ensure stable references to prevent unnecessary re-renders.
  Use [`useCallback()`](https://reactjs.org/docs/hooks-reference.html#usecallback) for memoization.
  Arrays and objects are automatically memoized.
</Note>

<ParamField body="items" type="HitsPerPagePropsItem[]" required>
  The list of available options, with each item:

  * `label`. The label to display in the option.
  * `value`. The number of hits to display per page.
  * `default`. The default hits per page on first search.

  <CodeGroup>
    ```jsx JavaScript theme={"system"}
    const hitsPerPageApi = useHitsPerPage({
      items: [
        { label: "8 hits per page", value: 8, default: true },
        { label: "16 hits per page", value: 16 },
      ],
    });
    ```

    ```tsx TypeScript theme={"system"}
    type HitsPerPagePropsItem = {
      /**
       * Label to display in the option.
       */
      label: string;
      /**
       * Number of hits to display per page.
       */
      value: number;
      /**
       * The default hits per page on first search.
       * @default false
       */
      default?: boolean;
    };
    ```
  </CodeGroup>
</ParamField>

<ParamField body="transformItems">
  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`.

  <CodeGroup>
    ```jsx JavaScript theme={"system"}
    const transformItems = (items) => {
      return items.map((item) => ({
        ...item,
        label: item.label.toUpperCase(),
      }));
    };

    function HitsPerPage() {
      const hitsPerPageApi = useHitsPerPage({
        // ...
        transformItems,
      });

      return <>{/* Your JSX */}</>;
    }
    ```

    ```tsx TypeScript theme={"system"}
    import type { UseHitsPerPageProps } from 'react-instantsearch';

    const transformItems: UseHitsPerPageProps['transformItems'] = (items) => {
      return items.map((item) => ({
        ...item,
        label: item.label.toUpperCase(),
      }));
    };

    function HitsPerPage() {
      const hitsPerPageApi = useHitsPerPage({
        // ...
        transformItems,
      });

      return <>{/* Your JSX */}</>;
    }
    ```
  </CodeGroup>
</ParamField>

### APIs

Hooks return APIs, such as state and functions.
You can use them to build your UI and interact with React InstantSearch.

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

  <CodeGroup>
    ```jsx JavaScript theme={"system"}
    function HitsPerPage(props) {
      const { items, refine } = useHitsPerPage(props);
      const { value } = items.find(({ isRefined }) => isRefined) || {};

      return (
        <select
          onChange={(event) => {
            refine(Number(event.target.value));
          }}
          value={String(value)}
        >
          {items.map((item) => (
            <option key={item.value} value={String(item.value)}>
              {item.label}
            </option>
          ))}
        </select>
      );
    }
    ```

    ```ts TypeScript theme={"system"}
    type HitsPerPageItem = {
      /**
       * The label to display in the option
       */
      label: string;
      /**
       * The number of hits to display per page.
       */
      value: number;
      /**
       * Whether the item is the current refined value.
       */
      isRefined: boolean;
    };
    ```
  </CodeGroup>
</ParamField>

<ParamField body="canRefine" type="boolean">
  Indicates whether the search can be refined.

  ```jsx JavaScript icon=code theme={"system"}
  function HitsPerPage(props) {
    const { items, canRefine, refine } = useHitsPerPage(props);
    const { value } = items.find(({ isRefined }) => isRefined) || {};

    return (
      <select
        onChange={(event) => {
          refine(Number(event.target.value));
        }}
        value={String(value)}
        disabled={!canRefine}
      >
        {items.map((item) => (
          <option key={item.value} value={item.value}>
            {item.label}
          </option>
        ))}
      </select>
    );
  }
  ```
</ParamField>

<ParamField body="refine" type="(value: number) => void">
  Sets the number of hits per page and triggers a search.

  ```jsx JavaScript icon=code theme={"system"}
  function HitsPerPage(props) {
    const { items, refine } = useHitsPerPage(props);
    const { value } = items.find(({ isRefined }) => isRefined) || {};

    return (
      <select
        onChange={(event) => {
          refine(Number(event.target.value));
        }}
        value={String(value)}
      >
        {items.map((item) => (
          <option key={item.value} value={item.value}>
            {item.label}
          </option>
        ))}
      </select>
    );
  }
  ```
</ParamField>

<ParamField body="createURL" type="(value: number) => string">
  Generates a URL of the next search state.

  ```jsx JavaScript icon=code theme={"system"}
  function HitsPerPage(props) {
    const { items, refine, createURL } = useHitsPerPage(props);

    return (
      <ul>
        {items.map((item) => (
          <li key={item.value}>
            <a
              href={createURL(item.value)}
              style={{ fontWeight: item.isRefined ? "bold" : "" }}
              onClick={(event) => {
                event.preventDefault();
                refine(item.value);
              }}
            >
              {item.label}
            </a>
          </li>
        ))}
      </ul>
    );
  }
  ```
</ParamField>

### Example

<CodeGroup>
  ```jsx JavaScript theme={"system"}
  import React from "react";
  import { useHitsPerPage } from "react-instantsearch";

  function CustomHitsPerPage(props) {
    const { items, refine } = useHitsPerPage(props);
    const { value: currentValue } =
      items.find(({ isRefined }) => isRefined) || {};

    return (
      <select
        onChange={(event) => {
          refine(Number(event.target.value));
        }}
        value={String(currentValue)}
      >
        {items.map((item) => (
          <option key={item.value} value={item.value}>
            {item.label}
          </option>
        ))}
      </select>
    );
  }
  ```

  ```tsx TypeScript theme={"system"}
  import React from "react";
  import { useHitsPerPage, UseHitsPerPageProps } from "react-instantsearch";

  function CustomHitsPerPage(props: UseHitsPerPageProps) {
    const { items, refine } = useHitsPerPage(props);
    const { value: currentValue } =
      items.find(({ isRefined }) => isRefined)! || {};

    return (
      <select
        onChange={(event) => {
          refine(Number(event.target.value));
        }}
        value={String(currentValue)}
      >
        {items.map((item) => (
          <option key={item.value} value={item.value}>
            {item.label}
          </option>
        ))}
      </select>
    );
  }
  ```
</CodeGroup>