> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# pagination
> Adds controls for navigating search result pages.
```ts Signature theme={"system"}
pagination({
container: string | HTMLElement,
// Optional parameters
showFirst: boolean,
showPrevious: boolean,
showNext: boolean,
showLast: boolean,
padding: number,
totalPages: number,
scrollTo: string | HTMLElement | boolean,
templates: object,
cssClasses: object,
});
```
```js Package manager theme={"system"}
import { pagination } from 'instantsearch.js/es/widgets';
```
```js CDN theme={"system"}
const { pagination } = instantsearch.widgets;
// or directly use instantsearch.widgets.pagination()
```
[See live example]()
Preview this widget and its behavior.
## About this widget
The `pagination` widget displays a pagination system which lets users change the current page of search results.
Pagination is limited to 1,000 hits per page.
For more information, see [Pagination limitations](/doc/guides/building-search-ui/ui-and-ux-patterns/pagination/js#pagination-limitations).
## Examples
```js JavaScript icon=code theme={"system"}
pagination({
container: "#pagination",
});
```
## Options
The CSS Selector or `HTMLElement` to insert the widget into.
```js string theme={"system"}
pagination({
container: '#pagination',
});
```
```js HTMLElement theme={"system"}
pagination({
container: document.querySelector("#pagination"),
});
```
Whether to display the first page link.
```js JavaScript icon=code theme={"system"}
pagination({
// ...
showFirst: false,
});
```
Whether to display the previous page link.
```js JavaScript icon=code theme={"system"}
pagination({
// ...
showPrevious: false,
});
```
Whether to display the next page link.
```js JavaScript icon=code theme={"system"}
pagination({
// ...
showNext: false,
});
```
Whether to display the last page link.
```js JavaScript icon=code theme={"system"}
pagination({
// ...
showLast: false,
});
```
The number of pages to display on each side of the current page.
```js JavaScript icon=code theme={"system"}
pagination({
// ...
padding: 2,
});
```
The maximum number of pages to browse.
```js JavaScript icon=code theme={"system"}
pagination({
// ...
totalPages: 2,
});
```
Where to scroll after a click. Set to `false` to disable.
```js string theme={"system"}
pagination({
// ...
scrollTo: 'header',
});
```
```js HTMLElement theme={"system"}
pagination({
// ...
scrollTo: document.querySelector(".header"),
});
```
```js boolean theme={"system"}
pagination({
// ...
scrollTo: false,
});
```
The [templates](#templates) to use for the widget.
```js JavaScript icon=code theme={"system"}
pagination({
// ...
templates: {
// ...
},
});
```
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.
* `noRefinementRoot`. The root container without results.
* `list`. The list of results.
* `item`. The item in the list of results.
* `firstPageItem`. The first item.
* `lastPageItem`. The last item.
* `previousPageItem`. The previous item.
* `nextPageItem`. The next item.
* `pageItem`. The page items.
* `selectedItem`. The selected item.
* `disabledItem`. The disabled item.
* `link`. The link elements.
```js JavaScript icon=code theme={"system"}
pagination({
// ...
cssClasses: {
root: "MyCustomPagination",
list: ["MyCustomPaginationList", "MyCustomPaginationList--subclass"],
},
});
```
## Templates
You can customize parts of a widget’s UI using the Templates API.
Each template includes an `html` function,
which you can use as a [tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates).
This function safely renders templates as HTML strings and works directly in the browser—no build step required.
For details, see [Templating your UI](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js/#templating-your-ui).
The `html` function is available in InstantSearch.js version 4.46.0 or later.
The template for the first page.
```js string theme={"system"}
pagination({
// ...
templates: {
first: '«',
},
});
```
```js function theme={"system"}
pagination({
// ...
templates: {
first() {
return "«";
},
},
});
```
The template for the previous page.
```js string theme={"system"}
pagination({
// ...
templates: {
previous: '‹',
},
});
```
```js function theme={"system"}
pagination({
// ...
templates: {
previous() {
return "‹";
},
},
});
```
The template for the next page.
```js string theme={"system"}
pagination({
// ...
templates: {
next: '›',
},
});
```
```js function theme={"system"}
pagination({
// ...
templates: {
next() {
return "›";
},
},
});
```
The template for the last page.
```js string theme={"system"}
pagination({
// ...
templates: {
last: '»',
},
});
```
```js function theme={"system"}
pagination({
// ...
templates: {
last() {
return "»";
},
},
});
```
## HTML output
```html HTML icon=code-xml theme={"system"}
```
## Customize the UI with `connectPagination`
If you want to create your own UI of the `pagination` widget, you can use connectors.
To use `connectPagination`, you can import it with the declaration relevant to how you installed InstantSearch.js.
```js Package manager theme={"system"}
import { connectPagination } from 'instantsearch.js/es/connectors';
```
```js CDN theme={"system"}
const { connectPagination } = instantsearch.connectors;
// or directly use instantsearch.connectors.connectPagination()
```
Then it's a 3-step process:
```js JavaScript icon=code theme={"system"}
// 1. Create a render function
const renderPagination = (renderOptions, isFirstRender) => {
// Rendering logic
};
// 2. Create the custom widget
const customPagination = connectPagination(renderPagination);
// 3. Instantiate
search.addWidgets([
customPagination({
// 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 renderPagination = (renderOptions, isFirstRender) => {
const {
pages,
currentRefinement,
nbHits,
nbPages,
isFirstPage,
isLastPage,
canRefine,
refine,
createURL,
widgetParams,
} = renderOptions;
if (isFirstRender) {
// Do some initial rendering and bind events
}
// Render the widget
};
```
If SEO is important for your search page, ensure that your custom HTML is optimized for search engines:
* Use `` tags with `href` attributes to allow search engine bots to follow links.
* Use semantic HTML and include [structured data](https://developers.google.com/search/docs/appearance/structured-data) when relevant.
For more guidance, see the [SEO checklist](/doc/guides/building-search-ui/resources/seo/js).
#### Rendering options
The pages relevant to the current situation and padding.
```js JavaScript icon=code theme={"system"}
const renderPagination = (renderOptions, isFirstRender) => {
const { pages } = renderOptions;
document.querySelector('#pagination').innerHTML = `
`;
};
```
The number of the page currently displayed.
```js JavaScript icon=code theme={"system"}
const renderPagination = (renderOptions, isFirstRender) => {
const { pages, currentRefinement } = renderOptions;
document.querySelector("#pagination").innerHTML = `
`;
};
```
The number of hits computed for the last query (can be approximate).
```js JavaScript icon=code theme={"system"}
const renderPagination = (renderOptions, isFirstRender) => {
const { currentRefinement, nbPages, nbHits } = renderOptions;
document.querySelector("#pagination").innerHTML = `
${currentRefinement + 1} of ${nbPages} page(s) for ${nbHits} hit(s)
`;
};
```
The number of pages for the result set.
```js JavaScript icon=code theme={"system"}
const renderPagination = (renderOptions, isFirstRender) => {
const { currentRefinement, nbPages, nbHits } = renderOptions;
document.querySelector("#pagination").innerHTML = `
${currentRefinement + 1} of ${nbPages} page(s) for ${nbHits} hit(s)
`;
};
```
Whether the current page is the first page.
```js JavaScript icon=code theme={"system"}
const renderPagination = (renderOptions, isFirstRender) => {
const { pages, isFirstPage, isLastPage } = renderOptions;
document.querySelector("#pagination").innerHTML = `
${
!isFirstPage
? `
-
Previous
`
: ""
}
${pages
.map(
(page) => `
-
${page + 1}
`,
)
.join("")}
${
!isLastPage
? `
-
Next
`
: ""
}
`;
};
```
Whether the current page is the last page.
```js JavaScript icon=code theme={"system"}
const renderPagination = (renderOptions, isFirstRender) => {
const { pages, isFirstPage, isLastPage } = renderOptions;
document.querySelector("#pagination").innerHTML = `
${
!isFirstPage
? `
-
Previous
`
: ""
}
${pages
.map(
(page) => `
-
${page + 1}
`,
)
.join("")}
${
!isLastPage
? `
-
Next
`
: ""
}
`;
};
```
Indicates if search state can be refined.
```js JavaScript icon=code theme={"system"}
const renderPagination = (renderOptions, isFirstRender) => {
const { canRefine } = renderOptions;
if (!canRefine) {
document.querySelector("#pagination").innerHTML = "";
return;
}
};
```
Sets the current page and triggers a search.
```js JavaScript icon=code theme={"system"}
const renderPagination = (renderOptions, isFirstRender) => {
const { pages, currentRefinement, refine } = renderOptions;
const container = document.querySelector("#pagination");
container.innerHTML = `
`;
[...container.querySelectorAll("a")].forEach((element) => {
element.addEventListener("click", (event) => {
event.preventDefault();
refine(event.currentTarget.dataset.value);
});
});
};
```
Generates a URL for the next state.
The number is the page to generate the URL for.
```js JavaScript icon=code theme={"system"}
const renderPagination = (renderOptions, isFirstRender) => {
const { pages, createURL } = renderOptions;
document.querySelector("#pagination").innerHTML = `
`;
};
```
All original widget options forwarded to the render function.
```js JavaScript icon=code theme={"system"}
const renderPagination = (renderOptions, isFirstRender) => {
const { widgetParams } = renderOptions;
widgetParams.container.innerHTML = "...";
};
// ...
search.addWidgets([
customPagination({
container: document.querySelector("#pagination"),
}),
]);
```
### 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 customPagination = connectPagination(renderPagination);
search.addWidgets([customPagination({ totalPages: number, padding: number })]);
```
#### Instance options
The total number of pages to browse.
```js JavaScript icon=code theme={"system"}
customPagination({
totalPages: 4,
});
```
The padding of pages to show around the current page
```js JavaScript icon=code theme={"system"}
customPagination({
padding: 2,
});
```
### Full example
```html HTML theme={"system"}
```
```js JavaScript theme={"system"}
// Create the render function
const renderPagination = (renderOptions, isFirstRender) => {
const {
pages,
currentRefinement,
nbPages,
isFirstPage,
isLastPage,
refine,
createURL,
} = renderOptions;
const container = document.querySelector("#pagination");
container.innerHTML = `
`;
[...container.querySelectorAll("a")].forEach((element) => {
element.addEventListener("click", (event) => {
event.preventDefault();
refine(event.currentTarget.dataset.value);
});
});
};
// Create the custom widget
const customPagination = connectPagination(renderPagination);
// Instantiate the custom widget
search.addWidgets([
customPagination({
container: document.querySelector("#pagination"),
}),
]);
```