Pagination

Adds controls for navigating search result pages.

This is the React InstantSearch v7 documentation. If you’re upgrading from v6, see the upgrade guide. If you were using React InstantSearch Hooks, this v7 documentation applies—just check for necessary changes. To continue using v6, you can find the archived documentation.

Signature

<Pagination
  // Optional props
  totalPages={number}
  padding={number}
  showFirst={boolean}
  showPrevious={boolean}
  showNext={boolean}
  showLast={boolean}
  classNames={object}
  translations={object}
  ...props={ComponentProps<'div'>}
/>

Import

JavaScript

import { Pagination } from "react-instantsearch";

View demo

About this widget

<Pagination> is a widget that displays a pagination to browse pages.

Pagination is limited to 1,000 hits per page. For more information, see Pagination limitations.

You can also create your own UI with usePagination.

Examples

JavaScript

import React from "react";
import { liteClient as algoliasearch } from "algoliasearch/lite";
import { InstantSearch, Pagination } from "react-instantsearch";

const searchClient = algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey");

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <Pagination />
    </InstantSearch>
  );
}

Props

totalPages · number

The maximum number of pages to browse.

JavaScript

<Pagination totalPages={2} />;

padding · number · default: 3

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

JavaScript

<Pagination padding={2} />;

showFirst · default: true

Whether to display the first page link.

JavaScript

<Pagination showFirst={false} />;

showPrevious · default: true

Whether to display the previous page link.

JavaScript

<Pagination showPrevious={false} />;

showNext · default: true

Whether to display the next page link.

JavaScript

<Pagination showNext={false} />;

showLast · default: true

Whether to display the last page link.

JavaScript

<Pagination showLast={false} />;

classNames · Partial<PaginationClassNames>

The CSS classes you can override and pass to the widget’s elements. It’s useful to style widgets with class-based CSS frameworks like Bootstrap or Tailwind CSS.

• root. The root element of the widget.
• noRefinementRoot. The root element when there are no refinements.
• list. The list element.
• item. Each item element.
• firstPageItem. The first page element.
• previousPageItem. The previous page element.
• pageItem. Each page element.
• selectedItem. The selected page element.
• disabledItem. Each disabled page element.
• nextPageItem. The next page element.
• lastPageItem. The last page element.
• link. The link of each item.

JavaScript

<Pagination
  classNames={{
    root: "MyCustomPagination",
    list: "MyCustomPaginationList MyCustomPaginationList--subclass",
  }}
/>;

translations · Partial<PaginationTranslations>

A mapping of keys to translation values.

• firstPageItemText. The text for the first page item.
• previousPageItemText. The text for the previous page item.
• nextPageItemText. The text for the next page item.
• lastPageItemText. The text for the last page item.
• pageItemText. The text for the current page item.
• firstPageItemAriaLabel. The label for the first page item (for screen readers).
• previousPageItemAriaLabel. The label for the previous page item (for screen readers).
• nextPageItemAriaLabel. The label for the next page item (for screen readers).
• lastPageItemAriaLabel. The label for the last page item (for screen readers).
• pageItemAriaLabel. The label for the current page item (for screen readers).

JavaScript

<Pagination
  translations={{
    firstPageItemText: "First page",
    previousPageItemText: "Previous page",
    nextPageItemText: "Next page",
    lastPageItemText: "Last page",
    pageItemText: ({ currentPage, nbPages }) =>
      `Page ${currentPage}/${nbPages}`,
    firstPageItemAriaLabel: "Go to first page",
    previousPageItemAriaLabel: "Go to previous page",
    nextPageItemAriaLabel: "Go to next page",
    lastPageItemAriaLabel: "Go to last page",
    pageItemAriaLabel: ({ currentPage, nbPages }) =>
      `Go to page ${currentPage} of ${nbPages}`,
  }}
/>;

...props · React.ComponentProps<'div'>

Any <div> prop to forward to the root element of the widget.

JavaScript

<Pagination className="MyCustomPagination" title="My custom title" />;

Hook

React InstantSearch let you create your own UI for the <Pagination> widget with usePagination. Hooks provide APIs to access the widget state and interact with InstantSearch.

The usePagination Hook accepts parameters and returns APIs. It must be used inside the <InstantSearch> component.

Usage

First, create your React component:

JavaScript

import { usePagination } from "react-instantsearch";

function CustomPagination(props) {
  const {
    pages,
    currentRefinement,
    nbHits,
    nbPages,
    isFirstPage,
    isLastPage,
    canRefine,
    refine,
    createURL,
  } = usePagination(props);

  return <>{/*Your JSX*/}</>;
}

Then, render the widget:

JavaScript

<CustomPagination {...props} />

Parameters

Hooks accept parameters. You can either pass them manually or forward props from a custom component.

When passing functions to Hooks, ensure stable references to prevent unnecessary re-renders. Use useCallback() for memoization. Arrays and objects are automatically memoized.

totalPages · number

The maximum number of pages to browse.

JavaScript

const paginationApi = usePagination({
  totalPages: 2,
});

padding · number · default: 3

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

JavaScript

const paginationApi = usePagination({
  padding: 2,
});

APIs

Hooks return APIs, such as state and functions. You can use them to build your UI and interact with React InstantSearch.

pages · number[]

The list of pages based on the current page and padding.

JavaScript

function Pagination(props) {
  const { pages, refine } = usePagination(props);

  return (
    <ul>
      {pages.map((page) => (
        <li key={page}>
          <a
            href="#"
            onClick={(event) => {
              event.preventDefault();
              refine(page);
            }}
          >
            {page + 1}
          </a>
        </li>
      ))}
    </ul>
  );
}

currentRefinement · number

The current page number.

JavaScript

function Pagination(props) {
  const { currentRefinement, pages, refine } = usePagination(props);

  return (
    <ul>
      {pages.map((page) => (
        <li key={page}>
          <a
            href="#"
            onClick={(event) => {
              event.preventDefault();
              refine(page);
            }}
          >
            {page === currentRefinement ? <strong>{page}</strong> : page}
          </a>
        </li>
      ))}
    </ul>
  );
}

nbHits · number

The number of hits (can be approximate).

JavaScript

function PageIndicator(props) {
  const { currentRefinement, nbPages, nbHits } = usePagination(props);

  return (
    <p>
      {currentRefinement + 1} of {nbPages} page(s) for {nbHits} hit(s)
    </p>
  );
}

nbPages · number

The number of pages for the total result set.

JavaScript

function PageIndicator(props) {
  const { currentRefinement, nbPages, nbHits } = usePagination(props);

  return (
    <p>
      {currentRefinement + 1} of {nbPages} page(s) for {nbHits} hit(s)
    </p>
  );
}

isFirstPage · boolean

Whether the current page is the first page.

JavaScript

function Pagination(props) {
  const { isFirstPage, pages, refine } = usePagination(props);

  return (
    <ul>
      {isFirstPage ? null : (
        <li>
          <a
            href="#"
            onClick={(event) => {
              event.preventDefault();
              refine(0);
            }}
          >
            First Page
          </a>
        </li>
      )}
      {pages.map((page) => (
        <li key={page}>
          <a
            href="#"
            onClick={(event) => {
              event.preventDefault();
              refine(page);
            }}
          >
            {page + 1}
          </a>
        </li>
      ))}
    </ul>
  );
}

isLastPage · boolean

Whether the current page is the last page.

JavaScript

function Pagination(props) {
  const { isLastPage, nbPages, pages, refine } = usePagination(props);

  return (
    <ul>
      {pages.map((page) => (
        <li key={page}>
          <a
            href="#"
            onClick={(event) => {
              event.preventDefault();
              refine(page);
            }}
          >
            {page + 1}
          </a>
        </li>
      ))}
      {isLastPage ? null : (
        <li>
          <a
            href="#"
            onClick={(event) => {
              event.preventDefault();
              refine(nbPages - 1);
            }}
          >
            Last Page
          </a>
        </li>
      )}
    </ul>
  );
}

canRefine · boolean

Indicates if the pagination can be refined.

JavaScript

function Pagination(props) {
  const { canRefine, pages, refine } = usePagination(props);

  if (!canRefine) {
    return null;
  }

  return (
    <ul>
      {pages.map((page) => (
        <li key={page}>
          <a
            href="#"
            onClick={(event) => {
              event.preventDefault();
              refine(page);
            }}
          >
            {page + 1}
          </a>
        </li>
      ))}
    </ul>
  );
}

refine · (page: number) => void

Sets the current page and triggers a search.

JavaScript

function Pagination(props) {
  const { pages, refine } = usePagination(props);

  return (
    <ul>
      {pages.map((page) => (
        <li key={page}>
          <a
            href="#"
            onClick={(event) => {
              event.preventDefault();
              refine(page);
            }}
          >
            {page + 1}
          </a>
        </li>
      ))}
    </ul>
  );
}

createURL · (page: number) => string

Generates a URL of the next search state.

JavaScript

function Pagination(props) {
  const { canRefine, pages, refine } = usePagination(props);

  return (
    <ul>
      {pages.map((page) => (
        <li key={page}>
          <a
            href={createURL(page)}
            onClick={(event) => {
              event.preventDefault();
              refine(page);
            }}
          >
            {page + 1}
          </a>
        </li>
      ))}
    </ul>
  );
}

Example

JavaScript

import React from "react";
import { usePagination } from "react-instantsearch";

function CustomPagination(props) {
  const {
    pages,
    currentRefinement,
    nbPages,
    isFirstPage,
    isLastPage,
    refine,
    createURL,
  } = usePagination(props);
  const firstPageIndex = 0;
  const previousPageIndex = currentRefinement - 1;
  const nextPageIndex = currentRefinement + 1;
  const lastPageIndex = nbPages - 1;

  return (
    <ul>
      <PaginationItem
        isDisabled={isFirstPage}
        href={createURL(firstPageIndex)}
        onClick={() => refine(firstPageIndex)}
      >
        First
      </PaginationItem>
      <PaginationItem
        isDisabled={isFirstPage}
        href={createURL(previousPageIndex)}
        onClick={() => refine(previousPageIndex)}
      >
        Previous
      </PaginationItem>
      {pages.map((page) => {
        const label = page + 1;

        return (
          <PaginationItem
            key={page}
            isDisabled={false}
            aria-label={`Page ${label}`}
            href={createURL(page)}
            onClick={() => refine(page)}
          >
            {label}
          </PaginationItem>
        );
      })}
      <PaginationItem
        isDisabled={isLastPage}
        href={createURL(nextPageIndex)}
        onClick={() => refine(nextPageIndex)}
      >
        Next
      </PaginationItem>
      <PaginationItem
        isDisabled={isLastPage}
        href={createURL(lastPageIndex)}
        onClick={() => refine(lastPageIndex)}
      >
        Last
      </PaginationItem>
    </ul>
  );
}

function PaginationItem({ isDisabled, href, onClick, ...props }) {
  if (isDisabled) {
    return (
      <li>
        <span {...props} />
      </li>
    );
  }

  return (
    <li>
      <a
        href={href}
        onClick={(event) => {
          if (isModifierClick(event)) {
            return;
          }

          event.preventDefault();

          onClick(event);
        }}
        {...props}
      />
    </li>
  );
}

function isModifierClick(event) {
  const isMiddleClick = event.button === 1;

  return Boolean(
    isMiddleClick ||
      event.altKey ||
      event.ctrlKey ||
      event.metaKey ||
      event.shiftKey,
  );
}