API Reference / React InstantSearch Hooks / <Pagination>

<Pagination>

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

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

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