API Reference / React InstantSearch Hooks / <HitsPerPage>

<HitsPerPage>

A
Signature 
<HitsPerPage
  items={UseHitsPerPageProps['items']}
  // Optional props
  transformItems={UseHitsPerPageProps['transformItems']}
  classNames={Partial<HitsPerPageClassNames>}
  ...props={React.ComponentProps<'div'>}
/>
See code examples
See live example

About this widget # A

<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> widget with the hitsPerPage search parameter.

You can also create your own UI with useHitsPerPage().

Examples # A

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

import React from 'react';
import algoliasearch from 'algoliasearch/lite';
import { InstantSearch, HitsPerPage } from 'react-instantsearch-hooks-web';

const searchClient = algoliasearch('AJ0P3S7DWQ', '90dfaaf5755e694f341fe68f6e41a6d4');

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

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.
Copy 
1
2
3
4
5
6

<HitsPerPage
  items={[
    { label: '8 hits per page', value: 8, default: true },
    { label: '16 hits per page', value: 16 },
  ]}
/>
transformItems #
Optional

Receives the items and is called before displaying them. Should return a new array with the same shape as the original array. Useful for transforming, removing, or reordering items.

In addition, the full results data is available, which includes all regular response parameters, as well as parameters from the helper (for example disjunctiveFacetsRefinements).
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

<HitsPerPage
  // ...
  transformItems={(items) => {
    return items.map((item) => ({
      ...item,
      label: item.label.toUpperCase(),
    }));
  }}

  /* or, combined with results */
  transformItems={(items, { results }) => {
    return items.map(item => ({
      ...item,
      label: item.isRefined && results
        ? `${item.label} (${results.nbPages} pages in total)`
        : item.label,
    }));
  }}
/>
classNames #
type: Partial<HitsPerPageClassNames>
Optional

CSS classes to pass to the widget’s elements. This is useful to style widgets with class-based CSS frameworks like Bootstrap or Tailwind CSS.

  • root: The root element of the widget.
  • select: The select element.
  • option: The option element.
Copy 
1
2
3
4
5
6
7
8

<HitsPerPage
  // ...
  classNames={{
    root: 'MyCustomHitsPerPage',
    select: 'MyCustomHitsPerPageSelect',
    option: 'MyCustomHitsPerPageOption MyCustomHitsPerPageOption--subclass',
  }}
/>
...props #
type: React.ComponentProps<'div'>
Optional

Any <div> prop to forward to the root element of the widget.
Copy 
1
2
3
4
5

<HitsPerPage
  // ...
  className="MyCustomHitsPerPage"
  title="My custom title"
/>

Hook# A

React InstantSearch Hooks 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 and returns APIs.

See code examples

Usage#

First, create your React component:

import { useHitsPerPage } from 'react-instantsearch-hooks-web';

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

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

Then, render the widget:

<CustomHitsPerPage {...props} />

Parameters#

Hooks accept parameters. You can pass them manually, or forward the props from your custom component.

When you provide a function to Hooks, make sure to pass a stable reference with useCallback() to avoid rendering endlessly. Objects and arrays are memoized so you don’t have to stabilize them.

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.
Copy 
1
2
3
4
5
6

const hitsPerPageApi = useHitsPerPage({
  items: [
    { label: '8 hits per page', value: 8, default: true },
    { label: '16 hits per page', value: 16 },
  ],
});
transformItems #

Receives the items and is called before displaying them. Should return a new array with the same shape as the original array. Useful for transforming, removing, or reordering items.

In addition, the full results data is available, which includes all regular response parameters, as well as parameters from the helper (for example disjunctiveFacetsRefinements).
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

const hitsPerPageApi = useHitsPerPage({
  // ...
  transformItems: (items) => {
    return items.map((item) => ({
      ...item,
      label: item.label.toUpperCase(),
    }));
  },

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

APIs#

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

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.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

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>
  );
}
hasNoResults #
type: boolean

Indicates whether the search has no results.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

function HitsPerPage(props) {
  const { items, hasNoResults, refine } = useHitsPerPage(props);
  const { value } = items.find(({ isRefined }) => isRefined) || {};

  return (
    <select
      onChange={(event) => {
        refine(Number(event.target.value));
      }}
      value={String(value)}
      disabled={hasNoResults}
    >
      {items.map((item) => (
        <option key={item.value} value={item.value}>
          {item.label}
        </option>
      ))}
    </select>
  );
}
refine #
type: (value: number) => void

Sets the number of hits per page and triggers a search.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

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>
  );
}
createURL #
type: (value: number) => string

Generates a URL of the next search state.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

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

Example#

Copy 
1
2
3
4
5
6
7
8

import React from 'react';
import { useHitsPerPage } from 'react-instantsearch-hooks-web';

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

  return <>{/* Your JSX */}</>;
}
Did you find this page helpful?
React InstantSearch Hooks v6