API Reference / React InstantSearch / Pagination

Pagination

A
Signature 
<Pagination
  // Optional parameters
  defaultRefinement={number}
  showFirst={boolean}
  showPrevious={boolean}
  showNext={boolean}
  showLast={boolean}
  padding={number}
  totalPages={number}
  translations={object}
/>
See code examples
See live example

About this widget # A

We released React InstantSearch Hooks, a new InstantSearch library for React. We recommend using React InstantSearch Hooks in new projects or upgrading from React InstantSearch.

The Pagination widget displays a pagination system allowing the user to change the current page.

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

Examples # A

Copy 
1
2
3

import { Pagination } from 'react-instantsearch-dom';

<Pagination />

Parameters # A

defaultRefinement #
type: number
Optional

The value of the page selected by default.
Copy 
1

<Pagination defaultRefinement={2} />
showFirst #
type: boolean
default: true
Optional

Whether to display the first page link.
Copy 
1

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

Whether to display the previous page link.
Copy 
1

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

Whether to display the next page link.
Copy 
1

<Pagination showNext={false} />
showLast #
type: boolean
default: false
Optional

Whether to display the last page link.
Copy 
1

<Pagination showLast />
padding #
type: number
default: 3
Optional

How many page links to display around the current page.
Copy 
1

<Pagination padding={5} />
totalPages #
type: number
default: Infinity
Optional

The maximum number of pages to display (and to allow navigating to).
Copy 
1

<Pagination totalPages={10} />
translations #
type: object
Optional

A mapping of keys to translation values.

  • previous: the label value for the previous page link.
  • next: the label value for the next page link.
  • first: the label value for the first page link.
  • last: the label value for the last page link.
  • page: the label value for a page item. It also accepts a function with the current page.
  • ariaPrevious: the accessibility label value for the previous page link.
  • ariaNext: the accessibility label value for the previous page link.
  • ariaFirst: the accessibility label value for the first page link.
  • ariaLast: the accessibility label value for the previous page link.
  • ariaPage: the accessibility label value for a page item. It also accepts a function with the current page.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

<Pagination
  translations={{
    previous: '‹',
    next: '›',
    first: '«',
    last: '»',
    page(currentRefinement) {
      return currentRefinement;
    },
    ariaPrevious: 'Previous page',
    ariaNext: 'Next page',
    ariaFirst: 'First page',
    ariaLast: 'Last page',
    ariaPage(currentRefinement) {
      return `Page ${currentRefinement}`;
    },
  }}
/>

HTML output# A

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

<div class="ais-Pagination">
  <ul class="ais-Pagination-list">
    <li class="ais-Pagination-item ais-Pagination-item--firstPage ais-Pagination-item--disabled">
      <span class="ais-Pagination-link" aria-label="First">‹‹</span>
    </li>
    <li class="ais-Pagination-item ais-Pagination-item--previousPage ais-Pagination-item--disabled">
      <span class="ais-Pagination-link" aria-label="Previous">‹</span>
    </li>
    <li class="ais-Pagination-item ais-Pagination-item--selected">
      <a class="ais-Pagination-link" href="#">1</a>
    </li>
    <li class="ais-Pagination-item ais-Pagination-item--page">
      <a class="ais-Pagination-link" href="#">2</a>
    </li>
    <li class="ais-Pagination-item ais-Pagination-item--page">
      <a class="ais-Pagination-link" href="#">3</a>
    </li>
    <li class="ais-Pagination-item">
      <a class="ais-Pagination-link" href="#">4</a>
    </li>
    <li class="ais-Pagination-item ais-Pagination-item--nextPage">
      <a class="ais-Pagination-link" aria-label="Next" href="#">›</a>
    </li>
    <li class="ais-Pagination-item ais-Pagination-item--lastPage">
      <a class="ais-Pagination-link" aria-label="Last" href="#">››</a>
    </li>
  </ul>
</div>

Customize the UI with connectPagination# A

If you want to create your own UI of the Pagination widget or use another UI library, you can use connectors.

Connectors are higher-order components. They encapsulate the logic for a specific kind of widget and they provide a way to interact with the InstantSearch context.

They have an outer component API that we call exposed props, and they provide some other props to the wrapped components which are called the provided props.

It’s a 3-step process:

// 1. Create a React component
const Pagination = () => {
  // return the DOM output
};

// 2. Connect the component using the connector
const CustomPagination = connectPagination(Pagination);

// 3. Use your connected widget
<CustomPagination />

See code examples

Create a React component#

const Pagination = ({
  number currentRefinement,
  number nbPages,
  function refine,
  function createURL,
}) => {
  // return the DOM output
};

Provided Props#

currentRefinement #
type: number

The position of the current page.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

const Pagination = ({ currentRefinement, nbPages }) => (
  <ul>
    {new Array(nbPages).fill(null).map((_, index) => {
      const page = index + 1;
      const style = {
        fontWeight: currentRefinement === page ? 'bold' : '',
      };

      return (
        <li key={index}>
          <a href="#" style={style}>
            {page}
          </a>
        </li>
      );
    })}
  </ul>
);
nbPages #
type: number

The total number of existing pages.
Copy 
1
2
3
4
5
6
7
8
9

const Pagination = ({ nbPages }) => (
  <ul>
    {new Array(nbPages).fill(null).map((_, index) => (
      <li key={index}>
        <a href="#">{index + 1}</a>
      </li>
    ))}
  </ul>
);
refine #
type: function

Selects a 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

const Pagination = ({ currentRefinement, nbPages, refine }) => (
  <ul>
    {new Array(nbPages).fill(null).map((_, index) => {
      const page = index + 1;
      const style = {
        fontWeight: currentRefinement === page ? 'bold' : '',
      };

      return (
        <li key={index}>
          <a
            href="#"
            style={style}
            onClick={event => {
              event.preventDefault();
              refine(page);
            }}
          >
            {page}
          </a>
        </li>
      );
    })}
  </ul>
);
createURL #
type: function

Generates a URL for the corresponding search state.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

const Pagination = ({ currentRefinement, nbPages, createURL }) => (
  <ul>
    {new Array(nbPages).fill(null).map((_, index) => {
      const page = index + 1;

      return (
        <li key={index}>
          <a href={createURL(page)}>{page}</a>
        </li>
      );
    })}
  </ul>
);

Create and instantiate your connected widget#

const CustomPagination = connectPagination(Pagination);

<CustomPagination
  // optional parameters
  defaultRefinement={number}
/>

Exposed Props#

defaultRefinement #
type: number
Optional

The value of the page selected by default.
Copy 
1

<CustomPagination defaultRefinement={2} />

If SEO is critical to your search page, your custom HTML markup needs to be parsable:

  • use plain <a> tags with href attributes for search engines bots to follow them,
  • use semantic markup with structured data when relevant, and test it.

Refer to our SEO checklist for building SEO-ready search experiences.

Full 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

import { connectPagination } from 'react-instantsearch-dom';

const Pagination = ({ currentRefinement, nbPages, refine, createURL }) => (
  <ul>
    {new Array(nbPages).fill(null).map((_, index) => {
      const page = index + 1;
      const style = {
        fontWeight: currentRefinement === page ? 'bold' : '',
      };

      return (
        <li key={index}>
          <a
            href={createURL(page)}
            style={style}
            onClick={event => {
              event.preventDefault();
              refine(page);
            }}
          >
            {page}
          </a>
        </li>
      );
    })}
  </ul>
);

const CustomPagination = connectPagination(Pagination);
Did you find this page helpful?
React InstantSearch v6