How it works

The explanation, with examples you can run.

The shape

1type Query {2  posts(first: Int = 20, after: String, last: Int, before: String): PostConnection!3}4 5type PostConnection {6  edges: [PostEdge!]!7  pageInfo: PageInfo!8  totalCount: Int          # optional, and can be expensive9}10 11type PostEdge {12  cursor: String!13  node: Post!14}15 16type PageInfo {17  hasNextPage: Boolean!18  hasPreviousPage: Boolean!19  startCursor: String20  endCursor: String21}

1query Feed($after: String) {2  posts(first: 20, after: $after) {3    edges { cursor node { id title } }4    pageInfo { hasNextPage endCursor }5  }6}

first/after page forwards and last/before page backwards. The spec for this pattern grew out of Relay, but it is used well beyond Relay. Fields that describe the relationship rather than either side belong on the edge: TeamMemberEdge.role or joinedAt.

A toy connection

Your code

// A cursor connection over a sorted list: first/after, edges, pageInfo.
const posts = Array.from({ length: 7 }, (_, i) => ({ id: `p${i + 1}`, title: `Post ${i + 1}` }))

const encode = (id) => btoa(`Post:${id}`)              // opaque to the client
const decode = (cursor) => atob(cursor).split(":")[1]

function postsConnection({ first, after }) {
  if (first > 3) throw new Error("first may be at most 3")  // a server-side cap
  const start = after ? posts.findIndex((p) => p.id === decode(after)) + 1 : 0
  const slice = posts.slice(start, start + first)
  const edges = slice.map((node) => ({ cursor: encode(node.id), node }))
  return {
    edges,
    pageInfo: {
      hasNextPage: start + first < posts.length,
      endCursor: edges.length ? edges[edges.length - 1].cursor : null,
    },
  }
}

// The client loop: ask for a page, continue after its endCursor.
let after = null
let page = 1
do {
  const { edges, pageInfo } = postsConnection({ first: 3, after })
  console.log(`page ${page++}: ${edges.map((e) => e.node.id).join(", ")}  endCursor=${pageInfo.endCursor} hasNextPage=${pageInfo.hasNextPage}`)
  after = pageInfo.hasNextPage ? pageInfo.endCursor : null
} while (after)

// Insert a post at the start while paging: cursors keep their place, offsets would not.
posts.unshift({ id: "p0", title: "New" })
console.log("after an insert, continuing from p3:", postsConnection({ first: 3, after: encode("p3") }).edges.map((e) => e.node.id).join(", "))
try { postsConnection({ first: 1000 }) } catch (e) { console.log("first: 1000 ->", e.message) }

⌘/Ctrl + Enter

OutputNot run yet

Press Run to see what your code prints, in order.

Runs in this browser, in an isolated frame with no access to this page. console.log, info, warn and error are shown; code runs as a classic script, so use an async function for await.

The toy finds the cursor's item by scanning an array; a real server decodes the cursor into the sort key and asks the database for rows after it, using an index. It should also reject a cursor it can't decode rather than starting from the beginning.

Choices to make

Maximum page size: document it and enforce it; it is also an input to query cost limits.
totalCount: a COUNT(*) over a large filtered set can cost more than the page itself. Offer it only where it is cheap, or approximate it.
Stable order: cursors need a total order, so add a unique tie-breaker (usually the id) to any sort key.
Normalised caches on the client merge pages by the connection's field and arguments, so keep argument names consistent across the schema.

Check yourself

3 questions. Get them all right to finish this topic.

1.Why are cursors opaque (for example base64 strings) rather than plain row ids?
2.A feed paged with `offset: 20, limit: 10` gets a new item at the top between two requests. What does the user see?
3.What should the server do with `friends(first: 100000)`?

0 of 3 right so far. Get all three to finish this topic.

Pagination with cursor connections

How it works

The shape

A toy connection

Choices to make

Check yourself

Go deeper