API Reference / React InstantSearch Hooks / <Pagination>

<Pagination>

A
Signature 
<Pagination
  // Optional props
  totalPages={number}
  padding={number}
  showFirst={boolean}
  showPrevious={boolean}
  showNext={boolean}
  showLast={boolean}
  classNames={Partial<PaginationClassNames>}
  ...props={React.ComponentProps<'div'>}
/>
See code examples
See live example

About this widget # A

<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 # A

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-hooks-web';

const searchClient = algoliasearch('AJ0P3S7DWQ', '90dfaaf5755e694f341fe68f6e41a6d4');

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

Props # A

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

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.
Copy 
1
2
3
4
5
6

<Pagination
  classNames={{
    root: 'MyCustomPagination',
    list: 'MyCustomPaginationList MyCustomPaginationList--subclass',
  }}
/>
...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# A

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.

See code examples

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 with useCallback() to avoid rendering endlessly. Objects and arrays are memoized so you don’t have to stabilize them.

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.

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

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?
React InstantSearch Hooks v6