API Reference / React InstantSearch / HitsPerPage

HitsPerPage

Signature 
<HitsPerPage
  items={object[]}
  defaultRefinement={number}
  // Optional parameters
  transformItems={function}
/>
See code examples
See live example

About this widget

We released React InstantSearch Hooks, a new InstantSearch library for React. We recommend using React InstantSearch Hooks in new projects or upgrading from React InstantSearch.

The HitsPerPage widget displays a select element to let the user change the number of displayed hits.

If you only want to configure the number of hits per page without displaying a widget, you should use the configure widget with the hitsPerPage search parameter.

Examples

Copy 
1
2
3
4
5
6
7
8
9

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

<HitsPerPage
  defaultRefinement={5}
  items={[
    { value: 5, label: 'Show 5 hits' },
    { value: 10, label: 'Show 10 hits' },
  ]}
/>

Props

items
type: object[]
Required

A list of available options.
Copy 
1
2
3
4
5
6
7

<HitsPerPage
  // ...
  items={[
    { value: 5, label: 'Show 5 hits' },
    { value: 10, label: 'Show 10 hits' },
  ]}
/>
defaultRefinement
type: number
Required

The number of selected items by default.
Copy 
1
2
3
4

<HitsPerPage
  // ...
  defaultRefinement={5}
/>
transformItems
type: function
default: items => items
Optional

Modifies the items being displayed, for example, to filter or sort them. It takes items as argument and expects them back in return.
Copy 
1
2
3
4
5
6
7
8
9

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

HTML output

Copy 
1
2
3
4
5
6

<div class="ais-HitsPerPage">
  <select class="ais-HitsPerPage-select">
    <option class="ais-HitsPerPage-option" value="3">3 per page</option>
    <option class="ais-HitsPerPage-option" value="6">6 per page</option>
  </select>
</div>

Customize the UI with connectHitsPerPage

If you want to create your own UI of the HitsPerPage widget or use another UI library, you can use connectors.

Connectors are higher-order components. They encapsulate the logic for a specific kind of widget and they provide a way to interact with the InstantSearch context.

They have an outer component API that we call exposed props, and they provide some other props to the wrapped components which are called the provided props.

It’s a 3-step process:

// 1. Create a React component
const HitsPerPage = () => {
  // return the DOM output
};

// 2. Connect the component using the connector
const CustomHitsPerPage = connectHitsPerPage(HitsPerPage);

// 3. Use your connected widget
<CustomHitsPerPage />

See code examples

Create a React component

const HitsPerPage = ({
  object[] items,
  number currentRefinement,
  function refine,
  function createURL,
}) => {
  // return the DOM output
};

Provided Props

items
type: object[]

A list of items the widget can display. If no label is provided, the value is displayed.
Copy 
1
2
3
4
5
6
7
8
9

const HitsPerPage = ({ items }) => (
  <ul>
    {items.map(item => (
      <li key={item.value} style={{ fontWeight: item.isRefined ? 'bold' : '' }}>
        {item.label}
      </li>
    ))}
  </ul>
);
currentRefinement
type: number

The currently applied refinement.
Copy 
1
2
3

const HitsPerPage = ({ currentRefinement }) => (
  <p>The search display {currentRefinement} hits.</p>
);
refine
type: function

The function to call with the next value of hits per page.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

const HitsPerPage = ({ items, refine }) => (
  <ul>
    {items.map(item => (
      <li key={item.value}>
        <a
          href="#"
          style={{ fontWeight: item.isRefined ? 'bold' : '' }}
          onClick={event => {
            event.preventDefault();
            refine(item.value);
          }}
        >
          {item.label}
        </a>
      </li>
    ))}
  </ul>
);
createURL
type: function

Generates a URL for the corresponding search state.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

const HitsPerPage = ({ items, refine, createURL }) => (
  <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>
);

Create and instantiate your connected widget

const CustomHitsPerPage = connectHitsPerPage(HitsPerPage);

<CustomHitsPerPage
  items={object[]}
  defaultRefinement={number}
  // Optional parameters
  transformItems={function}
/>

Exposed Props

items
type: object[]
Required

A list of available options.
Copy 
1
2
3
4
5
6
7

<CustomHitsPerPage
  // ...
  items={[
    { value: 5, label: 'Show 5 hits' },
    { value: 10, label: 'Show 10 hits' },
  ]}
/>
defaultRefinement
type: number
Required

The number of items selected by default.
Copy 
1
2
3
4

<CustomHitsPerPage
  // ...
  defaultRefinement={5}
/>
transformItems
type: function
default: items => items
Optional

Modifies the items being displayed, for example, to filter or sort them. Takes items as argument and expects them back in return.
Copy 
1
2
3
4
5
6
7
8
9

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

Full 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

import { connectHitsPerPage } from 'react-instantsearch-dom';

const HitsPerPage = ({ items, currentRefinement, refine, createURL }) => (
  <div>
    <p>The search display {currentRefinement} hits.</p>
    <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>
  </div>
);

const CustomHitsPerPage = connectHitsPerPage(HitsPerPage);
Did you find this page helpful?
React InstantSearch v6