UI libraries / React InstantSearch / Widgets

<Pagination>

This is the React InstantSearch v7 documentation. React InstantSearch v7 is the latest version of React InstantSearch and the stable version of React InstantSearch Hooks.

If you were using React InstantSearch v6, you can upgrade to v7.

If you were using React InstantSearch Hooks, you can still use the React InstantSearch v7 documentation, but you should check the upgrade guide for necessary changes.

If you want to keep using React InstantSearch 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
Copy 
1

import { Pagination } from 'react-instantsearch';
See code examples
See live example

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

Copy 
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';

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

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

Props

Parameter Description
totalPages
type: number
Optional

The maximum number of pages to browse.
Copy 
1

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

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

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

Whether to display the first page link.
Copy 
1

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

Whether to display the previous page link.
Copy 
1

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

Whether to display the next page link.
Copy 
1

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

Whether to display the last page link.
Copy 
1

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

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.
Copy 
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).
Copy 
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.
Copy 
1

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

See code examples

Usage

First, create your React component:

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:

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

Parameter Description
totalPages
type: number

The maximum number of pages to browse.
Copy 
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.
Copy 
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.

Parameter Description
pages
type: number[]

The list of pages based on the current page and padding.
Copy 
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.
Copy 
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).
Copy 
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.
Copy 
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.
Copy 
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.
Copy 
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.
Copy 
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.
Copy 
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.
Copy 
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

Copy 
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
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

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
  );
}
Did you find this page helpful?
React InstantSearch v7