hitsPerPage
hitsPerPage({ container: string|HTMLElement, items: object[], // Optional parameters cssClasses: object, transformItems: function, });
1
import { hitsPerPage } from 'instantsearch.js/es/widgets';
About this widget
The hitsPerPage
widget displays a dropdown menu to let 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
widget with the hitsPerPage
search parameter.
Examples
1
2
3
4
5
6
7
hitsPerPage({
container: '#hits-per-page',
items: [
{ label: '8 hits per page', value: 8, default: true },
{ label: '16 hits per page', value: 16 },
],
});
Options
container
|
type: string|HTMLElement
Required
The CSS Selector or |
||
Copy
|
|||
items
|
type: object[]
Required
The list of available options, with each item:
|
||
Copy
|
|||
cssClasses
|
type: object
default: {}
Optional
The CSS classes you can override:
|
||
Copy
|
|||
transformItems
|
type: function
default: items => items
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 |
||
Copy
|
HTML output
1
2
3
4
5
6
<div class="ais-HitsPerPage">
<select class="ais-HitsPerPage-select">
<option class="ais-HitsPerPage-option" value="8">8 per page</option>
<option class="ais-HitsPerPage-option" value="16">16 per page</option>
</select>
</div>
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.
1
import { connectHitsPerPage } from 'instantsearch.js/es/connectors';
Then it’s a 3-step process:
// 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).
const renderHitsPerPage = (renderOptions, isFirstRender) => {
const {
object[] items,
boolean canRefine,
function refine,
object widgetParams,
} = renderOptions;
if (isFirstRender) {
// Do some initial rendering and bind events
}
// Render the widget
}
Rendering options
items
|
type: object[]
The list of items the widget can display, with each item:
|
||
Copy
|
|||
canRefine
|
since: v4.45.0
type: boolean
Whether the search can be refined. |
||
Copy
|
|||
refine
|
type: function
Sets the number of hits per page and triggers a search. |
||
Copy
|
|||
widgetParams
|
type: object
All original widget options forwarded to the render function. |
||
Copy
|
Create and instantiate the custom widget
We first create custom widgets from our rendering function, then we instantiate them. When doing that, there are two types of parameters you can give:
- Instance parameters: they are predefined parameters that you can use to configure the behavior of Algolia.
- Your own parameters: to make the custom widget generic.
Both instance and custom parameters are available in connector.widgetParams
, inside the renderFunction
.
const customHitsPerPage = connectHitsPerPage(
renderHitsPerPage
);
search.addWidgets([
customHitsPerPage({
object[] items,
function transformItems,
})
]);
Instance options
items
|
type: object[]
Required
The list of available options, with each item:
|
||
Copy
|
|||
transformItems
|
type: function
default: items => items
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 |
||
Copy
|
Full example
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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
// 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 => `
<option
value="${item.value}"
${item.isRefined ? 'selected' : ''}
>
${item.label}
</option>
`
)
.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 },
],
})
]);