InstantSearch / React / V6 / Guides

Paginate Results in React InstantSearch

Deprecated content
This documentation is for a deprecated version of React InstantSearch. Some features and settings may be missing or their usage may have changed. Refer to the documentation for the latest version of React InstantSearch for up-to-date information.

Pagination gives you complete control over how you retrieve query results. You can:

  • Implement standard paging
  • Retrieve specific record subsets that ignore page boundaries.
  • Set pagination defaults at indexing time
  • Override pagination default settings at query time.

Pagination at indexing time

At indexing time, you can set up two defaults:

Pagination at query time

You can:

  • Retrieve a specific page with the page parameter
  • Specify specific record subsets by using the offset and length parameters
  • 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 (this value starts at 0)
  • 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. If there are no hits for important query strings,
  • exhaustiveNbHits returns a boolean indicating if the nbHits count was exhaustive or approximate
  • exhaustiveTypo returns a boolean indicating if the typo-tolerance search was exhaustive or approximate (only included when typo-tolerance is enabled)

No hits or is the search still in progress?

You should cater for situations when there are no hits (nbHits = 0) by displaying a message to users and clearing filters so they can start over.

Sometimes, though, no hits can be reported if the user’s device can’t access the network or the network connection is slow. To determine if there are no hits for a query or if the search is still in progress, examine the value of InstantSearch’s status property (JS), onLoadingChanged event (Android), or isLoading event (iOS). You should also consider adding a loading indicator to inform users on a slow connection that their search is still in progress.

Exhaustive hits

Usually, Algolia returns an accurate number of total hits. However, if a query returns many hits, Algolia approximates the count to avoid scanning the whole index. This approximation protects other search and indexing operations. If your API response includes the exhaustive.nbHits parameter, the number of hits is approximate.

Retrieving specific pages

At query time, you can pass in the page parameter to access a specific results page. 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 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 retrieved from a paginated query to 20,000. This restriction ensures optimal performance and hinders third parties from extracting your data. Usually, the default of 1,000 hits is more than enough.

Overriding the default limits

To retrieve more hits (for example, for an ecommerce category page or an infinite scroll experience), you can raise the default pagination limit:

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

Increasing the pagination limit might decrease performance. Only set this number as large as 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)

In most cases, you only need page and hitsPerPage to add pagination. However, if you want to insert items, such as ads, into the results without affecting pagination, use the offset and length parameters. They allow you to specify the records to retrieve, not the page.

The offset parameter lets you specify the starting record, and length sets the number of records returned. For example, if you have 100 records in your result set, broken down into 10 pages (hitsPerPage=10), retrieve these 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).
Did you find this page helpful?