connectPagination

Build a custom widget for navigating between result pages

The Pagination connector provides the logic to build a custom widget that lets users choose the current page of the results.

When using pagination with Algolia, you should be aware that the engine won’t provide pages beyond the 1000th hit by default. You can find more information in the Algolia documentation.

Usage

import { connectPagination } from 'instantsearch.js/es/connectors';

const customPagination = connectPagination(
  (renderOptions, isFirstRender) => {
    const { pages, currentRefinement, nbPages, isFirstPage, isLastPage, refine, widgetParams } = renderOptions;
    const { container } = widgetParams;
    
    container.innerHTML = `
      <div>
        <button ${isFirstPage ? 'disabled' : ''} data-page="${currentRefinement - 1}">
          Previous
        </button>
        ${pages.map(page => `
          <button 
            data-page="${page}"
            style="${page === currentRefinement ? 'font-weight: bold' : ''}"
          >
            ${page + 1}
          </button>
        `).join('')}
        <button ${isLastPage ? 'disabled' : ''} data-page="${currentRefinement + 1}">
          Next
        </button>
      </div>
    `;
    
    container.querySelectorAll('button').forEach(button => {
      button.addEventListener('click', (e) => {
        const page = parseInt(e.target.dataset.page);
        if (!isNaN(page)) {
          refine(page);
        }
      });
    });
  }
);

search.addWidgets([
  customPagination({
    container: document.querySelector('#pagination'),
  }),
]);

Connector Options

totalPages · number

The total number of pages to browse.

padding · number · default: "3"

The padding of pages to show around the current page.

Render Options

currentRefinement · number

The number of the page currently displayed.

nbPages · number

The number of pages for the result set.

nbHits · number

The number of hits computed for the last query (can be approximated).

pages · number[]

The actual pages relevant to the current situation and padding.

isFirstPage · boolean

true if the current page is also the first page.

isLastPage · boolean

true if the current page is also the last page.

canRefine · boolean

true if this search returned more than one page.

refine · (page: number) => void

Sets the current page and triggers a search.

createURL · (page: number) => string

Creates URLs for the next state. The number is the page to generate the URL for.

widgetParams · object

The options passed to the connector.