> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# HitsPerPage
> Lets users change the number of search results per page.
export const FlavorSwitcher = ({current, baseHref = "", options = [], label = "InstantSearch framework"}) => {
if (options.length === 0) {
return
This is the **React InstantSearch v7** documentation.
If you're upgrading from v6, see the [upgrade guide](/doc/guides/building-search-ui/upgrade-guides/react/#migrate-from-react-instantsearch-v6-to-react-instantsearch-v7).
If you were using React InstantSearch Hooks,
this v7 documentation applies—just check for [necessary changes](/doc/guides/building-search-ui/upgrade-guides/react/#migrate-from-react-instantsearch-hooks-to-react-instantsearch-v7).
To continue using v6, you can find the [archived documentation](https://algolia.com/old-docs/deprecated/instantsearch/react/v6/api-reference/instantsearch/).
```tsx Signature theme={"system"}
}
/>
```
## Import
```jsx JavaScript icon=code theme={"system"}
import { HitsPerPage } from "react-instantsearch";
```
Preview this widget and its behavior.
## About this widget
`` 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 [``](/doc/api-reference/widgets/configure/react)
widget with the [`hitsPerPage`](/doc/api-reference/api-parameters/hitsPerPage) search parameter.
You can also create your own UI with [`useHitsPerPage`](#hook).
## Examples
```jsx JavaScript icon=code theme={"system"}
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 (
);
}
```
## Props
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.
```jsx JavaScript theme={"system"}
;
```
```ts TypeScript theme={"system"}
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;
};
```
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](/doc/guides/building-search-ui/going-further/backend-search/in-depth/understanding-the-api-response/)
and [parameters from the helper](https://community.algolia.com/algoliasearch-helper-js/reference.html#query-parameters),
such as `disjunctiveFacetsRefinements`.
```jsx JavaScript theme={"system"}
const transformItems = (items) => {
return items.map((item) => ({
...item,
label: item.label.toUpperCase(),
}));
};
function Search() {
return (
);
}
```
```tsx TypeScript theme={"system"}
import type { HitsPerPageProps } from 'react-instantsearch';
const transformItems: HitsPerPageProps['transformItems'] = (items) => {
return items.map((item) => ({
...item,
label: item.label.toUpperCase(),
}));
};
function Search() {
return (
);
}
```
The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/react#style-your-widgets) and pass to the widget's elements.
It's useful to style widgets with class-based CSS frameworks like [Bootstrap](https://getbootstrap.com) or [Tailwind CSS](https://tailwindcss.com).
* `root`. The root element of the widget.
* `select`. The `select` element.
* `option`. The `option` element.
```jsx JavaScript icon=code theme={"system"}
;
```
Any `
` prop to forward to the root element of the widget.
```jsx JavaScript icon=code theme={"system"}
;
```
## Hook
React InstantSearch let you create your own UI for the `` widget with `useHitsPerPage`.
Hooks provide APIs to access the widget state and interact with InstantSearch.
The `useHitsPerPage` Hook accepts [parameters](#parameters) and returns [APIs](#hook).
It must be used inside the [``](/doc/api-reference/widgets/instantsearch/react) component.
### Usage
First, create your React component:
```jsx JavaScript icon=code theme={"system"}
import { useHitsPerPage } from "react-instantsearch";
function CustomHitsPerPage(props) {
const { items, refine, createURL, canRefine } = useHitsPerPage(props);
return <>{/*Your JSX*/};
}
```
Then, render the widget:
```jsx JavaScript icon=code theme={"system"}
;
```
### 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()`](https://reactjs.org/docs/hooks-reference.html#usecallback) for memoization.
Arrays and objects are automatically memoized.
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.
```jsx JavaScript theme={"system"}
const hitsPerPageApi = useHitsPerPage({
items: [
{ label: "8 hits per page", value: 8, default: true },
{ label: "16 hits per page", value: 16 },
],
});
```
```tsx TypeScript theme={"system"}
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;
};
```
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](/doc/guides/building-search-ui/going-further/backend-search/in-depth/understanding-the-api-response/)
and [parameters from the helper](https://community.algolia.com/algoliasearch-helper-js/reference.html#query-parameters),
such as `disjunctiveFacetsRefinements`.
```jsx JavaScript theme={"system"}
const transformItems = (items) => {
return items.map((item) => ({
...item,
label: item.label.toUpperCase(),
}));
};
function HitsPerPage() {
const hitsPerPageApi = useHitsPerPage({
// ...
transformItems,
});
return <>{/* Your JSX */};
}
```
```tsx TypeScript theme={"system"}
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.
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.
```jsx JavaScript theme={"system"}
function HitsPerPage(props) {
const { items, refine } = useHitsPerPage(props);
const { value } = items.find(({ isRefined }) => isRefined) || {};
return (
);
}
```
```ts TypeScript theme={"system"}
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;
};
```
Indicates whether the search can be refined.
```jsx JavaScript icon=code theme={"system"}
function HitsPerPage(props) {
const { items, canRefine, refine } = useHitsPerPage(props);
const { value } = items.find(({ isRefined }) => isRefined) || {};
return (
);
}
```
Sets the number of hits per page and triggers a search.
```jsx JavaScript icon=code theme={"system"}
function HitsPerPage(props) {
const { items, refine } = useHitsPerPage(props);
const { value } = items.find(({ isRefined }) => isRefined) || {};
return (
);
}
```
Generates a URL of the next search state.
```jsx JavaScript icon=code theme={"system"}
function HitsPerPage(props) {
const { items, refine, createURL } = useHitsPerPage(props);
return (