HitsPerPage

Lets users change the number of search results per page.

This is the React InstantSearch v7 documentation. If you’re upgrading from v6, see the upgrade guide. If you were using React InstantSearch Hooks, this v7 documentation applies—just check for necessary changes. To continue using v6, you can find the archived documentation.

Signature

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

Import

JavaScript

import { HitsPerPage } from "react-instantsearch";

See this widget in action

Preview this widget and its behavior.

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

JavaScript

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

items · 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.

JavaScript

<HitsPerPage
  items={[
    { label: "8 hits per page", value: 8, default: true },
    { label: "16 hits per page", value: 16 },
  ]}
/>;

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

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 and parameters from the helper, such as disjunctiveFacetsRefinements.

JavaScript

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

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

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 · Partial<HitsPerPageClassNames>

The CSS classes you can override and pass to the widget’s elements. It’s 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.

JavaScript

<HitsPerPage
  // ...
  classNames={{
    root: "MyCustomHitsPerPage",
    select: "MyCustomHitsPerPageSelect",
    option: "MyCustomHitsPerPageOption MyCustomHitsPerPageOption--subclass",
  }}
/>;

...props · React.ComponentProps<'div'>

Any <div> prop to forward to the root element of the widget.

JavaScript

<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. It must be used inside the <InstantSearch> component.

Usage

First, create your React component:

JavaScript

import { useHitsPerPage } from "react-instantsearch";

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

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

Then, render the widget:

JavaScript

<CustomHitsPerPage {...props} />;

Parameters

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

When passing functions to Hooks, ensure stable references to prevent unnecessary re-renders. Use useCallback() for memoization. Arrays and objects are automatically memoized.

items · 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.

JavaScript

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

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

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 and parameters from the helper, such as disjunctiveFacetsRefinements.

JavaScript

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

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

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

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.

items · 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.

JavaScript

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

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 · boolean

Indicates whether the search can be refined.

JavaScript

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 · (value: number) => void

Sets the number of hits per page and triggers a search.

JavaScript

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 · (value: number) => string

Generates a URL of the next search state.

JavaScript

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

JavaScript

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

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