Paginate Results in React InstantSearch Hooks

Pagination gives you full control over how you retrieve query results. You can implement standard paging or retrieve specific record subsets that ignore page boundaries.

You can set pagination defaults at indexing time and override them at query time.

Pagination at indexing time

At indexing time you can set up two defaults:

• hitsPerPage - the number of hits returned for every page
• paginationLimitedTo - controls the overall number of hits you can potentially retrieve for a given query

Pagination at query time

• You can retrieve a specific page by using the page parameter
• You can specify specific record subsets by using the offset and length parameters
• You can override the default for hitsPerPage

Response details

To help paginate results, Algolia provides information about the current state of the pagination in the JSON response.

1
2
3
4
5
6
7
8
{
  [...],
  "page": 0,
  "nbHits": 40,
  "nbPages": 2,
  "hitsPerPage": 20,
  "exhaustiveNbHits": true
}

• page returns the current page (note: this value is zero-based)
• hitsPerPage returns the maximum number of hits returned for each page
• nbPages returns the number of pages available for the current query
• nbHits returns the number of hits that the search query matched
• exhaustiveNbHits returns a boolean indicating if the nbHits count was exhaustive or approximate
• exhaustiveTypo returns a boolean indicating if the typo-tolerence search was exhaustive or approximate (only included when typo-tolerance is enabled)

Exhaustivity

If possible, Algolia will return an accurate number of total hits. However, there are some cases where performance needs to be favored over exhaustivity. If a query returns a huge number of results, the engine will approximate the hits count to avoid having to scan the full results set. This approximation has been put in place to protect other search and indexing operations. As an alternative, you can leverage the boolean exhaustiveNbHits to either hide or tweak the display of the hits count in this case. You can also use the frequent occurrence of this value to consider fine-tuning your data and index settings to improve performance.

Retrieving specific pages

At query time, you can pass in the page parameter to access directly the nth page of results. The hitsPerPage parameter provides a way to set the default number of hits returned for each page. By default, its value is 20; however, this can be overridden either as an index setting or as a query parameter.

1
2
3
4
5
6
index.search('query', {
  page: 2,
  hitsPerPage: 5
}).then(({ hits }) => {
  console.log(hits);
});

Pagination limitations

Default number of hits per query

By default, Algolia limits the maximum number of hits that can be retrieved from a query to 1000. This restriction not only guarantees optimal performance, but also ensures your data can’t be easily extracted. Usually, the default of 1000 hits is more than enough.

Overriding the default limits

In the event of a specific use case that requires being able to retrieve a higher number of hits (for example, powering an ecommerce category page or developing an infinite scroll type of experience), it’s possible to raise the default pagination limit via the paginationLimitedTo index setting.

1
2
3
index.setSettings({
  paginationLimitedTo: 5000
});

Increasing the pagination limit may impact performance. We highly recommend setting this number only as large as is actually necessary.

Paging beyond the limit

If you send a request for a page that doesn’t exist, or is out-of-range, that is, when page >= nbPages, Algolia doesn’t return an error. Instead, it returns 0 results.

Retrieving a subset of records (with offset and length)

Leveraging page and hitsPerPage is best practice for adding pagination functionality. However, there are some cases where you will want to conditionally insert items into the results (for example, ads) without impacting the pagination. In this situation, while you can still use page and hitsPerPage, you can also use offset and length.

Note that with InstantSearch, all pagination use cases are implemented with page and hitsPerPage.

The parameters offset and length provide an alternative to paging by letting you specify the records to retrieve, not the page. You may want to do this for a variety of reasons, one of which is mentioned above - to mix ads within a small subset of results.

offset lets you specify the starting hit (or record) and length sets the number of records returned.

For example, if you have 100 records in your result set, which are broken down into 10 pages (hitsPerPage=10), you can ignore the pages and retrieve record subsets, as follows (offset is zero-based):

• records 50 to 80 (offset=49 and length = 30).
• records 21 to 25 (offset=20 and length = 5).