Pagination - Algolia

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";

See this widget in action

Preview this widget and its behavior.

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

number

The maximum number of pages to browse.

JavaScript

<Pagination totalPages={2} />;

number

default:3

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

JavaScript

<Pagination padding={2} />;

default:true

Whether to display the first page link.

JavaScript

<Pagination showFirst={false} />;

default:true

Whether to display the previous page link.

JavaScript

<Pagination showPrevious={false} />;

default:true

Whether to display the next page link.

JavaScript

<Pagination showNext={false} />;

default:true

Whether to display the last page link.

JavaScript

<Pagination showLast={false} />;

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 page element when it’s unavailable.
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",
  }}
/>;

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}`,
  }}
/>;

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() to keep function references stable. You don’t need to do this for arrays and objects.

number

The maximum number of pages to browse.

JavaScript

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

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.

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

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

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

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

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

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

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

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

(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

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

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

function CustomPagination(props: UsePaginationProps) {
  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>
  );
}

type PaginationItemProps = Omit<React.ComponentProps<"a">, "onClick"> & {
  onClick: NonNullable<React.ComponentProps<"a">["onClick"]>;
  isDisabled: boolean;
};

function PaginationItem({
  isDisabled,
  href,
  onClick,
  ...props
}: PaginationItemProps) {
  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: React.MouseEvent) {
  const isMiddleClick = event.button === 1;

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

Import

See this widget in action

About this widget

Examples

Props

Hook

Usage

Parameters

APIs

Example