> ## 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. export const FlavorSwitcher = ({current, baseHref = "", options = [], label = "InstantSearch framework"}) => { if (options.length === 0) { return
FlavorSwitcher requires at least one option.
; } const selected = options.find(option => option.value === current) ?? options[0]; return
{selected.label}
; };
```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 = ` `; }; ``` 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 = ` `; }; ``` 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"), }), ]); ```