API Reference / React InstantSearch Hooks / <HitsPerPage>

May. 12, 2022

<HitsPerPage>

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

<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

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

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


            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 },
  ]}
/>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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;
};


            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
<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
<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
<HitsPerPage
  // ...
  className="MyCustomHitsPerPage"
  title="My custom title"
/>

Hook

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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;
};


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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
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;
};


            hasNoResults

type: boolean

Indicates whether the search has no results.

Copy
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
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
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 */}</>;
}

1
2
3
4
5
6
7
8
9
10
11
import React from 'react';
import {
  useHitsPerPage,
  UseHitsPerPageProps,
} from 'react-instantsearch-hooks-web';

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

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

Did you find this page helpful?

<HitsPerPage>

About this widget

Examples

Props

Hook

Usage

Parameters

APIs

Example

On this page