Pagination

Often, you will have some views in your application where you need to display a list that contains too much data to be either fetched or displayed at once. Pagination is the most common solution to this problem, and Apollo Client has built-in functionality that makes it quite easy to do.

There are basically two ways of fetching paginated data: numbered pages, and cursors. There are also two ways for displaying paginated data: discrete pages, and infinite scrolling. For a more in-depth explanation of the difference and when you might want to use one vs. the other, we recommend that you read our blog post on the subject: Understanding Pagination.

In this article, we’ll cover the technical details of using Apollo to implement both approaches.

Using fetchMore

In Apollo, the easiest way to do pagination is with a function called fetchMore, which is provided on the data prop by the graphql higher order component. This basically allows you to do a new GraphQL query and merge the result into the original result.

You can specify what query and variables to use for the new query, and how to merge the new query result with the existing data on the client. How exactly you do that will determine what kind of pagination you are implementing.

Offset-based

Offset-based pagination — also called numbered pages — is a very common pattern, found on many websites, because it is usually the easiest to implement on the backend. In SQL for example, numbered pages can easily be generated by using OFFSET and LIMIT.

Here is an example with numbered pages taken from GitHunt:

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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

const FEED_QUERY = gql`
  query Feed($type: FeedType!, $offset: Int, $limit: Int) {
    currentUser {
      login
    }
    feed(type: $type, offset: $offset, limit: $limit) {
      id
      # ...
    }
  }
`;
const ITEMS_PER_PAGE = 10;
const FeedWithData = graphql(FEED_QUERY, {
  options(props) {
    return {
      variables: {
        type: (
          props.params &&
          props.params.type &&
          props.params.type.toUpperCase()
        ) || 'TOP',
        offset: 0,
        limit: ITEMS_PER_PAGE,
      },
      fetchPolicy: 'network-only',
    };
  },
  props({ data: { loading, feed, currentUser, fetchMore } }) {
    return {
      loading,
      feed,
      currentUser,
      loadMoreEntries() {
        return fetchMore({
          // query: ... (you can specify a different query. FEED_QUERY is used by default)
          variables: {
            // We are able to figure out which offset to use because it matches
            // the feed length, but we could also use state, or the previous
            // variables to calculate this (see the cursor example below)
            offset: feed.length,
          },
          updateQuery: (previousResult, { fetchMoreResult }) => {
            if (!fetchMoreResult) { return previousResult; }
            return Object.assign({}, previousResult, {
              // Append the new feed results to the old one
              feed: [...previousResult.feed, ...fetchMoreResult.feed],
            });
          },
        });
      },
    };
  },
})(Feed);

See this code in context in GitHunt.

As you can see, fetchMore is accessible through the data argument to the props function. So that our presentational component can remain unaware of Apollo, we use props to define a simple “load more” function, named loadMoreEntries, that can be called by the child component, Feed. This way we don’t need to change the Feed component at all if we need to change our pagination logic.

In the example above, loadMoreEntries is a function which calls fetchMore with the length of the current feed as a variable. By default, fetchMore more will use the original query, so we just pass in new variables. Once the new data is returned from the server, the updateQuery function is used to merge it with the existing data, which will cause a re-render of your UI component with an expanded list.

Here is how the loadMoreEntries function from above is called from the UI component:

1
2
3
4
5
6
7
8
9
10
11
12
13

const Feed = ({ vote, loading, currentUser, feed, loadMoreEntries }) => {
  return (
    <div>
      <FeedContent
        entries={feed || []}
        currentUser={currentUser}
        onVote={vote}
      />
      <a onClick={loadMoreEntries}>Load more</a>
      {loading ? <Loading /> : null}
    </div>
  );
}

The above approach works great for limit/offset pagination. One downside of pagination with numbered pages or offsets is that an item can be skipped or returned twice when items are inserted into or removed from the list at the same time. That can be avoided with cursor-based pagination.

Cursor-based

In cursor-based pagination, a “cursor” is used to keep track of where in the data set the next items should be fetched from. Sometimes the cursor can be quite simple and just refer to the ID of the last object fetched, but in some cases — for example lists sorted according to some criteria — the cursor needs to encode the sorting criteria in addition to the ID of the last object fetched.

Implementing cursor-based pagination on the client isn’t all that different from offset-based pagination, but instead of using an absolute offset, we keep a reference to the last object fetched and information about the sort order used.

In the example below, we use a fetchMore query to continuously load new comments, which will be prepended to the list. The cursor to be used in the fetchMore query is provided in the initial server response, and is updated whenever more data is fetched.

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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

const MoreCommentsQuery = gql`
  query MoreComments($cursor: String) {
    moreComments(cursor: $cursor) {
      cursor
      comments {
        author
        text
      }
    }
  }
`;
const CommentsWithData = graphql(CommentsQuery, {
  // This function re-runs every time `data` changes, including after `updateQuery`,
  // meaning our loadMoreEntries function will always have the right cursor
  props({ data: { loading, cursor, comments, fetchMore } }) {
    return {
      loading,
      comments,
      loadMoreEntries: () => {
        return fetchMore({
          query: MoreCommentsQuery,
          variables: {
            cursor: cursor,
          },
          updateQuery: (previousResult, { fetchMoreResult }) => {
            const previousEntry = previousResult.entry;
            const newComments = fetchMoreResult.moreComments.comments;
            const newCursor = fetchMoreResult.moreComments.cursor;
            return {
              // By returning `cursor` here, we update the `loadMore` function
              // to the new cursor.
              cursor: newCursor,
              entry: {
                // Put the new comments in the front of the list
                comments: [...newComments, ...previousEntry.comments],
              },
            };
          },
        });
      },
    };
  },
})(Comments);

Relay-style cursor pagination

Relay, another popular GraphQL client, is opinionated about the input and output of paginated queries, so people sometimes build their server’s pagination model around Relay’s needs. If you have a server that is designed to work with the Relay Cursor Connections spec, you can also call that server from Apollo Client with no problems.

Using Relay-style cursors is very similar to basic cursor-based pagination. The main difference is in the format of the query response which affects where you get the cursor.

Relay provides a pageInfo object on the returned cursor connection which contains the cursor of the first and last items returned as the properties startCursor and endCursor respectively. This object also contains a boolean property hasNextPage which can be used to determine if there are more results available.

The following example specifies a request of 10 items at a time and that results should start after the provided cursor. If null is passed for the cursor relay will ignore it and provide results starting from the beginning of the data set which allows the use of the same query for both initial and subsequent requests.

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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

const CommentsQuery = gql`
  query Comments($cursor: String) {
    Comments(first: 10, after: $cursor) {
      comments {
        edges {
          node {
            author
            text
          }
        }
        pageInfo {
          endCursor
          hasNextPage
        }
      }
    }
  }
`;
const CommentsWithData = graphql(CommentsQuery, {
  // This function re-runs every time `data` changes, including after `updateQuery`,
  // meaning our loadMoreEntries function will always have the right cursor
  props({ data: { loading, comments, fetchMore } }) {
    return {
      loading,
      comments,
      loadMoreEntries: () => {
        return fetchMore({
          query: CommentsQuery,
          variables: {
            cursor: comments.pageInfo.endCursor,
          },
          updateQuery: (previousResult, { fetchMoreResult }) => {
            const newEdges = fetchMoreResult.comments.edges;
            const pageInfo = fetchMoreResult.comments.pageInfo;
            return {
              // Put the new comments at the end of the list and update `pageInfo`
              // so we have the new `endCursor` and `hasNextPage` values
              comments: {
                edges: [...previousResult.comments.edges, ...newEdges],
                pageInfo,
              },
            };
          },
        });
      },
    };
  },
})(Feed);

The @connection directive

1
2
3
4
5
6
7
8
9
10
11

const FEED_QUERY = gql`
  query Feed($type: FeedType!, $offset: Int, $limit: Int) {
    currentUser {
      login
    }
    feed(type: $type, offset: $offset, limit: $limit) @connection(key: "feed", filter: ["type"]) {
      id
      # ...
    }
  }
`;

This would result in the accumulated feed in every query or fetchMore being placed in the store under the feed key, which we could later use of imperative store updates. In this example, we also use the @connection directive’s optional filter argument, which allows us to include some arguments of the query in the store key. In this case, we want to include the type query argument in the store key, which results in multiple store values that accumulate pages from each type of feed.