Skip to main content
The pagination widget displays page navigation controls, allowing users to browse through search results across multiple pages.

​
Usage

const pagination = instantsearch.widgets.pagination({
  container: '#pagination',
});

search.addWidget(pagination);

​
Examples

​
Basic Pagination

instantsearch.widgets.pagination({
  container: '#pagination',
});

​
With Custom Padding

instantsearch.widgets.pagination({
  container: '#pagination',
  padding: 2, // Show 2 pages on each side of current page
});

​
With Max Pages

instantsearch.widgets.pagination({
  container: '#pagination',
  totalPages: 20, // Limit to 20 pages maximum
});

​
Without First/Last Buttons

instantsearch.widgets.pagination({
  container: '#pagination',
  showFirst: false,
  showLast: false,
});

​
With Custom Templates

instantsearch.widgets.pagination({
  container: '#pagination',
  templates: {
    previous: '← Prev',
    next: 'Next →',
    first: '« First',
    last: 'Last »',
    page: ({ page }) => `Page ${page}`,
  },
});

​
Disable Auto-Scroll

instantsearch.widgets.pagination({
  container: '#pagination',
  scrollTo: false, // Don't scroll after page change
});

​
Custom Scroll Target

instantsearch.widgets.pagination({
  container: '#pagination',
  scrollTo: '#results-container',
});

​
Options

​
container
string | HTMLElement
required
CSS Selector or HTMLElement to insert the widget.
​
totalPages
number
Maximum number of pages to display. Useful for limiting pagination on large result sets.
​
padding
number
default:"3"
Number of pages to display on each side of the current page.
​
showFirst
boolean
default:"true"
Whether to show the “First page” button.
​
showLast
boolean
default:"true"
Whether to show the “Last page” button.
​
showPrevious
boolean
default:"true"
Whether to show the “Previous page” button.
​
showNext
boolean
default:"true"
Whether to show the “Next page” button.
​
scrollTo
string | HTMLElement | boolean
default:"'body'"
Where to scroll after clicking a page:
  • 'body': Scroll to top of page
  • CSS selector or HTMLElement: Scroll to specific element
  • false: Disable auto-scrolling
  • true: Same as 'body'
​
templates
object
Templates to customize the widget rendering.
​
cssClasses
object
CSS classes to add to the widget elements.

​
HTML Output

<div class="ais-Pagination">
  <ul class="ais-Pagination-list">
    <li class="ais-Pagination-item ais-Pagination-item--firstPage">
      <a class="ais-Pagination-link" href="#">«</a>
    </li>
    <li class="ais-Pagination-item ais-Pagination-item--previousPage">
      <a class="ais-Pagination-link" href="#">‹</a>
    </li>
    <li class="ais-Pagination-item ais-Pagination-item--page">
      <a class="ais-Pagination-link" href="#">1</a>
    </li>
    <li class="ais-Pagination-item ais-Pagination-item--selected 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 ais-Pagination-item--nextPage">
      <a class="ais-Pagination-link" href="#">›</a>
    </li>
    <li class="ais-Pagination-item ais-Pagination-item--lastPage">
      <a class="ais-Pagination-link" href="#">»</a>
    </li>
  </ul>
</div>

​
Pagination Logic

With padding: 3 (default):
  • Current page: 5
  • Displays: 1 … 2 3 4 5 6 7 8 … 20
With padding: 1:
  • Current page: 5
  • Displays: 1 … 4 5 6 … 20

​
Controlling Results Per Page

Pagination works with the number of results set via:
  1. The hitsPerPage widget
  2. The configure widget
  3. The InstantSearch configuration
// Set default hits per page
const search = instantsearch({
  indexName: 'products',
  searchClient,
  searchParameters: {
    hitsPerPage: 20,
  },
});

// Or use hitsPerPage widget
instantsearch.widgets.hitsPerPage({
  container: '#hits-per-page',
  items: [
    { label: '20 per page', value: 20, default: true },
    { label: '40 per page', value: 40 },
  ],
});

Build docs developers (and LLMs) love

Get started for freeTalk to us