API Reference / React InstantSearch Hooks / <Pagination>
Signature
<Pagination
  // Optional props
  totalPages={number}
  padding={number}
  showFirst={boolean}
  showPrevious={boolean}
  showNext={boolean}
  showLast={boolean}
  classNames={object}
  translations={object}
  ...props={ComponentProps<'div'>}
/>
Import
1
import { Pagination } from 'react-instantsearch-hooks-web';

About this widget

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

The Algolia search engine limits paginating to 1,000 hits per page.

You can also create your own UI with usePagination().

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
import React from 'react';
import algoliasearch from 'algoliasearch/lite';
import { InstantSearch, Pagination } from 'react-instantsearch-hooks-web';

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

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

Props

totalPages
type: number
Optional

The maximum number of pages to browse.

1
<Pagination totalPages={2} />
padding
type: number
default: 3
Optional

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

1
<Pagination padding={2} />
showFirst
default: true
Optional

Whether to display the first page link.

1
<Pagination showFirst={false} />
showPrevious
default: true
Optional

Whether to display the previous page link.

1
<Pagination showPrevious={false} />
showNext
default: true
Optional

Whether to display the next page link.

1
<Pagination showNext={false} />
showLast
default: true
Optional

Whether to display the last page link.

1
<Pagination showLast={false} />
classNames
type: Partial<PaginationClassNames>
Optional

CSS classes to pass to the widget’s elements. This is 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.
1
2
3
4
5
6
<Pagination
  classNames={{
    root: 'MyCustomPagination',
    list: 'MyCustomPaginationList MyCustomPaginationList--subclass',
  }}
/>
translations
type: Partial<PaginationTranslations>
Optional

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).
1
2
3
4
5
6
7
8
9
10
11
12
13
14
<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
type: React.ComponentProps<'div'>
Optional

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

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

Hook

React InstantSearch Hooks 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.

Usage

First, create your React component:

import { usePagination } from 'react-instantsearch-hooks-web';

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

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

Then, render the widget:

<CustomPagination {...props} />

Parameters

Hooks accept parameters. You can pass them manually, or forward the props from your custom component.

When you provide a function to Hooks, make sure to pass a stable reference to avoid rendering endlessly (for example, with useCallback()). Objects and arrays are memoized; you don’t need to stabilize them.

totalPages
type: number

The maximum number of pages to browse.

1
2
3
const paginationApi = usePagination({
  totalPages: 2,
});
padding
type: number
default: 3

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

1
2
3
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
type: number[]

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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
type: number

The current page number.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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
type: number

The number of hits (can be approximate).

1
2
3
4
5
6
7
8
9
function PageIndicator(props) {
  const { currentRefinement, nbPages, nbHits } = usePagination(props);

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

The number of pages for the total result set.

1
2
3
4
5
6
7
8
9
function PageIndicator(props) {
  const { currentRefinement, nbPages, nbHits } = usePagination(props);

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

Whether the current page is the first page.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
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
type: boolean

Whether the current page is the last page.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
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
type: boolean

Indicates if the pagination can be refined.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
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
type: (page: number) => void

Sets the current page and triggers a search.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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
type: (page: number) => string

Generates a URL of the next search state.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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

1
2
3
4
5
6
7
8
import React from 'react';
import { usePagination } from 'react-instantsearch-hooks-web';

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

  return <>{/* Your JSX */}</>;
}
Did you find this page helpful?