> ## 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
```ts Signature theme={"system"}
hitsPerPage({
container: string | HTMLElement,
items: object[],
// Optional parameters
cssClasses?: object,
transformItems?: function,
});
```
## Import
```js Package manager theme={"system"}
import { hitsPerPage } from "instantsearch.js/es/widgets";
```
```js CDN theme={"system"}
const { hitsPerPage } = instantsearch.widgets;
// or directly use instantsearch.widgets.hitsPerPage()
```
Preview this widget and its behavior.
## About this widget
The `hitsPerPage` widget displays a menu for letting users change the number of displayed hits.
If you only want to configure the number of hits per page without displaying a widget,
you can use the [`configure`](/doc/api-reference/widgets/configure/js) widget with the [`hitsPerPage`](/doc/api-reference/api-parameters/hitsPerPage) search parameter.
## Examples
```js JavaScript icon=code theme={"system"}
hitsPerPage({
container: "#hits-per-page",
items: [
{ label: "8 hits per page", value: 8, default: true },
{ label: "16 hits per page", value: 16 },
],
});
```
## Options
The CSS Selector or `HTMLElement` to insert the widget into.
```js string theme={"system"}
hitsPerPage({
// ...
container: "#hits-per-page",
});
```
```js HTMLElement theme={"system"}
hitsPerPage({
// ...
container: document.querySelector("#hits-per-page"),
});
```
The list of available options, with each item:
* `label: string`. The label to display in the option.
* `value: number`. The number of hits to display per page.
* `default: boolean`. The default hits per page on first search.
```js JavaScript icon=code theme={"system"}
hitsPerPage({
// ...
items: [
{ label: "8 hits per page", value: 8, default: true },
{ label: "16 hits per page", value: 16 },
],
});
```
The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js#style-your-widgets):
* `root`. The root element of the widget.
* `select`. The `select` element.
* `option`. The `option` elements of the `select`.
```js JavaScript icon=code theme={"system"}
hitsPerPage({
// ...
cssClasses: {
root: "MyCustomHitsPerPage",
select: [
"MyCustomHitsPerPageSelect",
"MyCustomHitsPerPageSelect--subclass",
],
},
});
```
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`.
```js JavaScript icon=code theme={"system"}
hitsPerPage({
// ...
transformItems(items) {
return items.map((item) => ({
...item,
label: item.label.toUpperCase(),
}));
},
});
// or, combined with results
hitsPerPage({
// ...
transformItems(items, { results }) {
return items.map((item) => ({
...item,
label:
item.isRefined && results
? `${item.label} (${results.nbPages} pages in total)`
: item.label,
}));
},
});
```
## HTML output
```html HTML icon=code-xml theme={"system"}
```
## Customize the UI with `connectHitsPerPage`
If you want to create your own UI of the `hitsPerPage` widget, you can use connectors.
To use `connectHitsPerPage`, you can import it with the declaration relevant to how you installed InstantSearch.js.
```js Package manager theme={"system"}
import { connectHitsPerPage } from "instantsearch.js/es/connectors";
```
```js CDN theme={"system"}
const { connectHitsPerPage } = instantsearch.connectors;
// or directly use instantsearch.connectors.connectHitsPerPage()
```
Then it's a 3-step process:
```js JavaScript icon=code theme={"system"}
// 1. Create a render function
const renderHitsPerPage = (renderOptions, isFirstRender) => {
// Rendering logic
};
// 2. Create the custom widget
const customHitsPerPage = connectHitsPerPage(renderHitsPerPage);
// 3. Instantiate
search.addWidgets([
customHitsPerPage({
// instance params
}),
]);
```
### Create a render function
This rendering function is called before the first search (`init` lifecycle step)
and each time results come back from Algolia (`render` lifecycle step).
```js JavaScript icon=code theme={"system"}
const renderHitsPerPage = (renderOptions, isFirstRender) => {
const { items, canRefine, refine, widgetParams } = renderOptions;
if (isFirstRender) {
// Do some initial rendering and bind events
}
// Render the widget
};
```
#### Rendering options
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.
```js JavaScript icon=code theme={"system"}
const renderHitsPerPage = (renderOptions, isFirstRender) => {
const { items } = renderOptions;
document.querySelector("#hits-per-page").innerHTML = `
`;
};
```
Whether the search can be refined.
```js JavaScript icon=code theme={"system"}
const renderHitsPerPage = (renderOptions, isFirstRender) => {
// `canRefine` is only available from v4.45.0
// Use `hasNoResults` in earlier minor versions.
const { items, canRefine } = renderOptions;
document.querySelector("#hits-per-page").innerHTML = `
`;
};
```
Sets the number of hits per page and triggers a search.
```js JavaScript icon=code theme={"system"}
const renderHitsPerPage = (renderOptions, isFirstRender) => {
const { items, refine } = renderOptions;
const container = document.querySelector("#hits-per-page");
if (isFirstRender) {
const select = document.createElement("select");
select.addEventListener("change", (event) => {
refine(event.target.value);
});
container.appendChild(select);
}
container.querySelector("select").innerHTML = `
${items
.map(
(item) => `
`,
)
.join("")}
`;
};
```
All original widget options forwarded to the render function.
```js JavaScript icon=code theme={"system"}
const renderHitsPerPage = (renderOptions, isFirstRender) => {
const { widgetParams } = renderOptions;
widgetParams.container.innerHTML = "...";
};
// ...
search.addWidgets([
customHitsPerPage({
container: document.querySelector("#hits-per-page"),
}),
]);
```
### Create and instantiate the custom widget
First, create your custom widgets using a rendering function.
Then, instantiate them with parameters.
There are two kinds of parameters you can pass:
* **Instance parameters**. Predefined options that configure Algolia's behavior.
* **Custom parameters**. Parameters you define to make the widget reusable and adaptable.
Inside the `renderFunction`, both instance and custom parameters are accessible through `connector.widgetParams`.
```js JavaScript icon=code theme={"system"}
const customHitsPerPage = connectHitsPerPage(renderHitsPerPage);
search.addWidgets([
customHitsPerPage({
items,
transformItems,
}),
]);
```
#### Instance options
The list of available options, with each item:
* `label: string`. The label to display in the option.
* `value: number`. The number of hits to display per page.
* `default: boolean`. The default hits per page on first search.
```js JavaScript icon=code theme={"system"}
customHitsPerPage({
items: [
{ label: "8 hits per page", value: 8, default: true },
{ label: "16 hits per page", value: 16 },
],
});
```
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`.
```js JavaScript icon=code theme={"system"}
customHitsPerPage({
// ...
transformItems(items) {
return items.map((item) => ({
...item,
label: item.label.toUpperCase(),
}));
},
});
// or, combined with results
customHitsPerPage({
// ...
transformItems(items, { results }) {
return items.map((item) => ({
...item,
label:
item.isRefined && results
? `${item.label} (${results.nbPages} pages in total)`
: item.label,
}));
},
});
```
### Full example
```html HTML theme={"system"}
```
```js JavaScript theme={"system"}
// Create the render function
const renderHitsPerPage = (renderOptions, isFirstRender) => {
// `canRefine` is only available from v4.45.0
// Use `hasNoResults` in earlier minor versions.
const { items, canRefine, refine, widgetParams } = renderOptions;
if (isFirstRender) {
const select = document.createElement("select");
select.addEventListener("change", (event) => {
refine(event.target.value);
});
widgetParams.container.appendChild(select);
}
const select = widgetParams.container.querySelector("select");
select.disabled = !canRefine;
select.innerHTML = `
${items
.map(
(item) => `
`,
)
.join("")}
`;
};
// Create the custom widget
const customHitsPerPage = connectHitsPerPage(renderHitsPerPage);
// Instantiate the custom widget
search.addWidgets([
customHitsPerPage({
container: document.querySelector("#hits-per-page"),
items: [
{ label: "8 hits per page", value: 8, default: true },
{ label: "16 hits per page", value: 16 },
],
}),
]);
```