API Reference / React InstantSearch Widgets / Pagination
Apr. 24, 2019

Pagination

Widget 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

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

Examples

Copy
1
2
3

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

<Pagination />

Parameters

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}`;
    },
  }}
/>

Customize the UI - connectPagination

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);

HTML output

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>

Did you find this page helpful?

React InstantSearch v5