GraphQL Cursor Pagination: The Connections Spec
On this page
Why GraphQL lists need connections
A field like posts: [Post!]! returns everything, with no way to page and no place to add metadata. Changing it later breaks clients. The connection pattern, from Facebook's Relay client and now a de-facto standard, gives every paginated list the same structure.
The Relay connection spec: edges, nodes and pageInfo
type PostConnection {
edges: [PostEdge!]!
pageInfo: PageInfo!
}
type PostEdge {
node: Post!
cursor: String!
}
type PageInfo {
hasNextPage: Boolean!
endCursor: String
}
type Query {
posts(first: Int = 10, after: String): PostConnection!
}The nesting looks heavy at first. Read it as: a connection is a page; each edge is one slot on that page, holding the item (the node) plus a bookmark (the cursor) for that exact spot; pageInfo says whether there's another page and where to start it.
edges: each item (node) with its own cursor.pageInfo: whether there are more items, and the cursor to continue from.- Arguments:
firstandafterpage forward; the full spec also defineslastandbeforefor paging backwards. - Edges can carry relationship data, like
roleon a team-membership edge oraddedAton a playlist edge, which belongs to the relationship, not to either object.
Implementing cursor pagination in a resolver
The resolver sorts newest first with the ID as a tiebreaker, and the cursor encodes the last item's sort values (the same keyset approach as REST, Day 7):
posts: (_, { first, after }) => {
if (first > 50) throw new GraphQLError('first must be 50 or less',
{ extensions: { code: 'BAD_USER_INPUT' } });
let list = [...posts].sort((a, b) =>
b.createdAt.localeCompare(a.createdAt) || Number(b.id) - Number(a.id));
if (after) {
const [ts, id] = decodeCursor(after);
list = list.filter(p => p.createdAt < ts || (p.createdAt === ts && Number(p.id) < Number(id)));
}
const page = list.slice(0, first);
return {
edges: page.map(node => ({ node, cursor: encodeCursor(node) })),
pageInfo: { hasNextPage: list.length > first,
endCursor: page.length ? encodeCursor(page.at(-1)) : null },
};
},Running posts(first: 3), then passing endCursor back as after, against a GraphQL Yoga server:
page 1: [ '30', '29', '28' ] { hasNextPage: true, endCursor: 'MjAyNi0xMC0wMVQwMDoyNzowMC4wMDBafDI4' }
page 2: [ '27', '26', '25' ]
first: 500 -> {"message":"first must be 50 or less","path":["posts"],"extensions":{"code":"BAD_USER_INPUT"}}The cursor is opaque to clients (here base64url of 2026-10-01T00:27:00.000Z|28). Capping first matters even more in GraphQL than in REST: without it, one query could request every post and every comment on each.
Practical notes on GraphQL pagination
totalCountis optional and can be expensive on large tables. Add it only when screens need it, possibly as an estimate.- Use connections for any list that can grow, even if it's small today. Short fixed lists (a user's three addresses) can stay plain lists.
- Client libraries understand connections: Relay and Apollo Client can merge pages automatically for infinite scrolling.
- Offset arguments (
page,limit) can be offered alongside for admin screens that need page numbers.
Check yourself
Edges wrap each item (the node) with its cursor and any relationship data; pageInfo says whether more items exist and where to continue.
It passes the previous response's pageInfo.endCursor as the after argument, with the same first size, and checks pageInfo.hasNextPage to know when to stop.
Without a cap, a single query can request a million items, and nested lists multiply the cost, such as 1,000 users each with 1,000 posts. Enforce a maximum, like 100, and reject or clamp larger values.
Counting all matching rows can be expensive on large tables. Offer it as an optional field so only clients that display totals pay for it.
To make them opaque, so clients treat them as tokens and the server can change their contents without breaking anyone.