Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL Federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Start for Free

Pagination in Apollo Client


enables you to fetch exactly the you need from your graph, with no unnecessary overhead. This helps keep network responses small and fast.

However, GraphQL doesn't automatically guarantee small responses. This is especially apparent when you a that contains a list. A list can contain infinitely many elements, which can result in an enormous response from a seemingly small query like this one:

query GetBookTitles {
books {

If your includes thousands or millions of books, this query probably returns much more data than you need. To resolve this issue, can paginate their list fields.

When a client queries a paginated list field, the server returns only a portion (or "page") of the list's elements. The client's query includes that indicate which page the server should return:

GraphQL serverClient appGraphQL serverClient appquery GetBookTitles(offset=0 limit=20)Returns the first 20 list elementsquery GetBookTitles(offset=20 limit=10)Returns the next 10 list elements

This diagram shows offset-based pagination, in which a client requests a page based on an absolute index in the list (offset) and the maximum number of elements to return (limit).

There are many different pagination strategies a server can use for a particular list field: offset-based, cursor-based, page-number-based, forwards, backwards, and so on. Each strategy requires a slightly different set of arguments. Because these strategies can each be useful in different situations, neither Apollo nor the GraphQL specification prescribes a canonical pagination strategy.

The Apollo Client approach

Instead of recommending a particular pagination strategy, provides flexible cache APIs that help you merge results from a paginated list field, regardless of which pagination strategy your uses. And because you can represent these custom pagination strategies with stateless functions, you can reuse a single function for every list field that uses the same strategy.

Ready to start paginating? Start by learning about the Core pagination API.

Advanced topics
Core API
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc., d/b/a Apollo GraphQL.

Privacy Policy