UI libraries / React InstantSearch / Widgets

Dec. 04, 2023

<HitsPerPage>

This is the React InstantSearch v7 documentation. React InstantSearch v7 is the latest version of React InstantSearch and the stable version of React InstantSearch Hooks.

If you were using React InstantSearch v6, you can upgrade to v7.

If you were using React InstantSearch Hooks, you can still use the React InstantSearch v7 documentation, but you should check the upgrade guide for necessary changes.

If you want to keep using React InstantSearch v6, you can find the archived documentation.

Signature

<HitsPerPage
  items={object[]}
  // Optional props
  transformItems={function}
  classNames={object}
  ...props={ComponentProps<'div'>}
/>

Import

Copy

1
import { HitsPerPage } from 'react-instantsearch';

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';

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

Parameter Description


            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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
const transformItems = (items) => {
  return items.map((item) => ({
    ...item,
    label: item.label.toUpperCase(),
  }));
};

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

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


            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 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';

function CustomHitsPerPage(props) {
  const {
    items,
    refine,
    createURL,
    canRefine,
  } = 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 to avoid rendering endlessly (for example, with useCallback()). Objects and arrays are memoized; you don’t need to stabilize them.

Parameter Description


            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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
const transformItems = (items) => {
  return items.map((item) => ({
    ...item,
    label: item.label.toUpperCase(),
  }));
};

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

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

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

APIs

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

Parameter Description


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


            canRefine

type: boolean

Indicates whether the search can be refined.

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


            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
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
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>
  );
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
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>
  );
}

Did you find this page helpful?

<HitsPerPage>

About this widget

Examples

Props

Hook

Usage

Parameters

APIs

Example

On this page