pagination

Adds controls for navigating search result pages.

Signature

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,
});

Package manager

import { pagination } from 'instantsearch.js/es/widgets';

const { pagination } = instantsearch.widgets;
// or directly use instantsearch.widgets.pagination()

See live example

See this widget in action

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.

Examples

JavaScript

pagination({
  container: "#pagination",
});

Options

container · string | HTMLElement · required

The CSS Selector or HTMLElement to insert the widget into.

string

pagination({
  container: '#pagination',
});

pagination({
  container: document.querySelector("#pagination"),
});

showFirst · boolean · default: true

Whether to display the first page link.

JavaScript

pagination({
  // ...
  showFirst: false,
});

showPrevious · boolean · default: true

Whether to display the previous page link.

JavaScript

pagination({
  // ...
  showPrevious: false,
});

showNext · boolean · default: true

Whether to display the next page link.

JavaScript

pagination({
  // ...
  showNext: false,
});

showLast · boolean · default: true

Whether to display the last page link.

JavaScript

pagination({
  // ...
  showLast: false,
});

padding · number · default: 3

The number of pages to display on each side of the current page.

JavaScript

pagination({
  // ...
  padding: 2,
});

totalPages · number

The maximum number of pages to browse.

JavaScript

pagination({
  // ...
  totalPages: 2,
});

scrollTo · string | HTMLElement | boolean · default: "body"

Where to scroll after a click. Set to false to disable.

string

pagination({
  // ...
  scrollTo: 'header',
});

pagination({
  // ...
  scrollTo: document.querySelector(".header"),
});

pagination({
  // ...
  scrollTo: false,
});

templates · object

The templates to use for the widget.

JavaScript

pagination({
  // ...
  templates: {
    // ...
  },
});

cssClasses · object · default: "{}"

The CSS classes you can override:

• 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.

JavaScript

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. This function safely renders templates as HTML strings and works directly in the browser—no build step required. For details, see Templating your UI.

The html function is available in InstantSearch.js version 4.46.0 or later.

first · string | function

The template for the first page.

string

pagination({
  // ...
  templates: {
    first: '«',
  },
});

pagination({
  // ...
  templates: {
    first() {
      return "«";
    },
  },
});

previous · string | function

The template for the previous page.

string

pagination({
  // ...
  templates: {
    previous: '‹',
  },
});

pagination({
  // ...
  templates: {
    previous() {
      return "‹";
    },
  },
});

next · string | function

The template for the next page.

string

pagination({
  // ...
  templates: {
    next: '›',
  },
});

pagination({
  // ...
  templates: {
    next() {
      return "›";
    },
  },
});

last · string | function

The template for the last page.

string

pagination({
  // ...
  templates: {
    last: '»',
  },
});

pagination({
  // ...
  templates: {
    last() {
      return "»";
    },
  },
});

HTML output

HTML

<div class="ais-Pagination">
  <ul class="ais-Pagination-list">
    <li
      class="ais-Pagination-item ais-Pagination-item--firstPage ais-Pagination-item--disabled"
    >
      <span class="ais-Pagination-link" aria-label="First">‹‹</span>
    </li>
    <li
      class="ais-Pagination-item ais-Pagination-item--previousPage ais-Pagination-item--disabled"
    >
      <span class="ais-Pagination-link" aria-label="Previous">‹</span>
    </li>
    <li class="ais-Pagination-item ais-Pagination-item--selected">
      <a class="ais-Pagination-link" href="#">1</a>
    </li>
    <li class="ais-Pagination-item ais-Pagination-item--page">
      <a class="ais-Pagination-link" href="#">2</a>
    </li>
    <li class="ais-Pagination-item ais-Pagination-item--page">
      <a class="ais-Pagination-link" href="#">3</a>
    </li>
    <li class="ais-Pagination-item">
      <a class="ais-Pagination-link" href="#">4</a>
    </li>
    <li class="ais-Pagination-item ais-Pagination-item--nextPage">
      <a class="ais-Pagination-link" aria-label="Next" href="#">›</a>
    </li>
    <li class="ais-Pagination-item ais-Pagination-item--lastPage">
      <a class="ais-Pagination-link" aria-label="Last" href="#">››</a>
    </li>
  </ul>
</div>

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.

Package manager

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

const { connectPagination } = instantsearch.connectors;
// or directly use instantsearch.connectors.connectPagination()

Then it’s a 3-step process:

JavaScript

// 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).

JavaScript

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 <a> tags with href attributes to allow search engine bots to follow links.
• Use semantic HTML and include structured data when relevant.

For more guidance, see the SEO checklist.

Rendering options

pages · number[]

The pages relevant to the current situation and padding.

JavaScript

const renderPagination = (renderOptions, isFirstRender) => {
  const { pages } = renderOptions;

  document.querySelector('#pagination').innerHTML = `
    <ul>
      ${pages
        .map(
          page => `
            <li>
              <a href="#">${page + 1}</a>
            </li>
          `
        )
        .join('')}
    </ul>
  `;
};

currentRefinement · number

The number of the page currently displayed.

JavaScript

const renderPagination = (renderOptions, isFirstRender) => {
  const { pages, currentRefinement } = renderOptions;

  document.querySelector("#pagination").innerHTML = `
    <ul>
      ${pages
        .map(
          (page) => `
            <li>
              <a
                href="#"
                style="font-weight: ${currentRefinement === page ? "bold" : ""}"
              >
                ${page + 1}
              </a>
            </li>
          `,
        )
        .join("")}
    </ul>
  `;
};

nbHits · number

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

JavaScript

const renderPagination = (renderOptions, isFirstRender) => {
  const { currentRefinement, nbPages, nbHits } = renderOptions;

  document.querySelector("#pagination").innerHTML = `    <span>
      ${currentRefinement + 1} of ${nbPages} page(s) for ${nbHits} hit(s)
    </span>
 `;
};

nbPages · number

The number of pages for the result set.

JavaScript

const renderPagination = (renderOptions, isFirstRender) => {
  const { currentRefinement, nbPages, nbHits } = renderOptions;

  document.querySelector("#pagination").innerHTML = `
    <span>
      ${currentRefinement + 1} of ${nbPages} page(s) for ${nbHits} hit(s)
    </span>
  `;
};

isFirstPage · boolean

Whether the current page is the first page.

JavaScript

const renderPagination = (renderOptions, isFirstRender) => {
  const { pages, isFirstPage, isLastPage } = renderOptions;

  document.querySelector("#pagination").innerHTML = `
    <ul>
      ${
        !isFirstPage
          ? `
            <li>
              <a href="#">Previous</a>
            </li>
            `
          : ""
      }
      ${pages
        .map(
          (page) => `
            <li>
              <a href="#">
                ${page + 1}
              </a>
            </li>
          `,
        )
        .join("")}
      ${
        !isLastPage
          ? `
            <li>
              <a href="#">Next</a>
            </li>
            `
          : ""
      }
    </ul>
  `;
};

isLastPage · boolean

Whether the current page is the last page.

JavaScript

const renderPagination = (renderOptions, isFirstRender) => {
  const { pages, isFirstPage, isLastPage } = renderOptions;

  document.querySelector("#pagination").innerHTML = `
    <ul>
      ${
        !isFirstPage
          ? `
            <li>
              <a href="#">Previous</a>
            </li>
            `
          : ""
      }
      ${pages
        .map(
          (page) => `
            <li>
              <a href="#">
                ${page + 1}
              </a>
            </li>
          `,
        )
        .join("")}
      ${
        !isLastPage
          ? `
            <li>
              <a href="#">Next</a>
            </li>
            `
          : ""
      }
    </ul>
  `;
};

canRefine · boolean · required

Indicates if search state can be refined.

JavaScript

const renderPagination = (renderOptions, isFirstRender) => {
  const { canRefine } = renderOptions;

  if (!canRefine) {
    document.querySelector("#pagination").innerHTML = "";
    return;
  }
};

refine · function

Sets the current page and triggers a search.

JavaScript

const renderPagination = (renderOptions, isFirstRender) => {
  const { pages, currentRefinement, refine } = renderOptions;

  const container = document.querySelector("#pagination");

  container.innerHTML = `
    <ul>
      ${pages
        .map(
          (page) => `
            <li>
              <a
                href="#"
                data-value="${page}"
                style="font-weight: ${currentRefinement === page ? "bold" : ""}"
              >
                ${page + 1}
              </a>
            </li>
          `,
        )
        .join("")}
    </ul>
  `;

  [...container.querySelectorAll("a")].forEach((element) => {
    element.addEventListener("click", (event) => {
      event.preventDefault();
      refine(event.currentTarget.dataset.value);
    });
  });
};

createURL · function

Generates a URL for the next state. The number is the page to generate the URL for.

JavaScript

const renderPagination = (renderOptions, isFirstRender) => {
  const { pages, createURL } = renderOptions;

  document.querySelector("#pagination").innerHTML = `
    <ul>
      ${pages
        .map(
          (page) => `
            <li>
              <a href="${createURL(page)}">
                ${page + 1}
              </a>
            </li>
          `,
        )
        .join("")}
    </ul>
  `;
};

widgetParams · function

All original widget options forwarded to the render function.

JavaScript

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.

JavaScript

const customPagination = connectPagination(renderPagination);

search.addWidgets([customPagination({ totalPages: number, padding: number })]);

Instance options

totalPages · number

The total number of pages to browse.

JavaScript

customPagination({
  totalPages: 4,
});

padding · number · default: 3

The padding of pages to show around the current page

JavaScript

customPagination({
  padding: 2,
});

Full example

HTML

<div id="pagination"></div>

// Create the render function
const renderPagination = (renderOptions, isFirstRender) => {
  const {
    pages,
    currentRefinement,
    nbPages,
    isFirstPage,
    isLastPage,
    refine,
    createURL,
  } = renderOptions;

  const container = document.querySelector("#pagination");

  container.innerHTML = `
    <ul>
      ${
        !isFirstPage
          ? `
            <li>
              <a
                href="${createURL(0)}"
                data-value="${0}"
              >
                First
              </a>
            </li>
            <li>
              <a
                href="${createURL(currentRefinement - 1)}"
                data-value="${currentRefinement - 1}"
              >
                Previous
              </a>
            </li>
            `
          : ""
      }
      ${pages
        .map(
          (page) => `
            <li>
              <a
                href="${createURL(page)}"
                data-value="${page}"
                style="font-weight: ${currentRefinement === page ? "bold" : ""}"
              >
                ${page + 1}
              </a>
            </li>
          `,
        )
        .join("")}
        ${
          !isLastPage
            ? `
              <li>
                <a
                  href="${createURL(currentRefinement + 1)}"
                  data-value="${currentRefinement + 1}"
                >
                  Next
                </a>
              </li>
              <li>
                <a
                  href="${createURL(nbPages - 1)}"
                  data-value="${nbPages - 1}"
                >
                  Last
                </a>
              </li>
              `
            : ""
        }
    </ul>
  `;

  [...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"),
  }),
]);