GraphQL Cursor Connections

Contract

When a GraphQL field exposes a list that clients page through, model it with the Cursor Connections structure: a {Type}Connection return type wrapping an edges list (each edge carrying node + cursor) and a pageInfo object, paged by first/after arguments with opaque string cursors. Apply this to any field that returns a browsable, scrollable, or "load-more" collection — never a bare list with offset arguments.

Rules

1. Return a connection, not a list. A pageable field returns a dedicated object type whose

name is the entity plus the Connection suffix (Article -> ArticleConnection). Never return [Article!]! directly for a field the caller pages.

1. The connection has two core fields. edges: [{Type}Edge!]! and pageInfo: PageInfo!.

A totalCount: Int may be added alongside them, but it never replaces either one.

1. Edges wrap the record. The edge type is {Type}Edge and holds two fields: node: {Type}!

(the record itself) and cursor: String! (the position marker). The cursor lives on the EDGE, never on the record/node type.

1. PageInfo carries the paging flags. At minimum hasNextPage: Boolean! and

endCursor: String for forward paging. Add hasPreviousPage: Boolean! and startCursor: String when backward paging is offered. These stay inside the PageInfo object; they are never flattened onto the connection root.

1. Arguments are first/after. Forward paging takes first: Int (how many) and

after: String (the cursor to resume past). Backward paging takes last: Int and before: String. Never limit/offset, page/pageSize, skip/take, or perPage.

1. Cursors are opaque strings. A cursor is a String — an opaque token (commonly base64),

not a raw integer offset, page number, or exposed database id. Callers treat it as a black box.

Worked examples

BEFORE — the base's reflexive REST-style default (offset list):

graphql
type Query {
  articles(limit: Int, offset: Int): [Article!]!
}

AFTER — the Cursor Connections form:

graphql
type Query {
  articles(first: Int, after: String): ArticleConnection!
}

type ArticleConnection {
  edges: [ArticleEdge!]!
  pageInfo: PageInfo!
}

type ArticleEdge {
  node: Article!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  endCursor: String
}

BEFORE — an ad-hoc wrapper with the wrong field names:

graphql
type EmployeePage {
  items: [Employee!]!
  nextCursor: String
  hasMore: Boolean!
  total: Int
}

AFTER — rename to the spec fields; items becomes edges, and the flat flags move into pageInfo:

graphql
type EmployeeConnection {
  edges: [EmployeeEdge!]!
  pageInfo: PageInfo!
  totalCount: Int
}

type EmployeeEdge {
  node: Employee!
  cursor: String!
}

BEFORE — cursor placed on the record type:

graphql
type Book {
  id: ID!
  title: String!
  cursor: String!
}

AFTER — the position marker belongs to the edge, not the record:

graphql
type BookEdge {
  node: Book!
  cursor: String!
}

Edge cases & exceptions

• Forward-only feed. Still return a full connection; you may omit hasPreviousPage and

startCursor, but keep hasNextPage and endCursor.

• Empty result. Return a connection with edges: [] and pageInfo.hasNextPage: false — not

null and not an empty bare list.

• Need a running total. Add totalCount: Int to the connection ALONGSIDE edges/pageInfo;

do not swap the connection for { items, total }.

• Filtering and sorting. Filter inputs and an orderBy argument sit next to first/after

on the same field and do not change the connection shape.

• Convenience shortcut. A flat nodes: [{Type}!]! helper is acceptable only IN ADDITION to

edges, never as a replacement — clients still need edge cursors to page.

Do / Don't

• DO name the wrapper {Type}Connection and the edge {Type}Edge.
• DON'T return [{Type}!]! directly for a field the caller pages.
• DO define cursor on the edge.
• DON'T put cursor on the record/node type.
• DO page with first/after (and last/before for backward paging).
• DON'T use limit/offset, page/pageSize, skip/take, or perPage.
• DO expose hasNextPage and endCursor inside a pageInfo object.
• DON'T flatten them onto the connection as hasMore/nextCursor.
• DO keep the cursor an opaque String.
• DON'T expose an integer offset, page index, or database id as the cursor.

Common mistakes

• Returning [{Type}!]! with limit/offset arguments — the reflexive HTTP/REST carry-over.
• Naming fields items, results, hasMore, nextCursor, or totalPages instead of the spec

field names.

• Hoisting hasNextPage/endCursor to the connection root instead of nesting them in PageInfo.
• Attaching cursor to the record type rather than to the edge.
• Using an integer or offset as the cursor, which leaks position and breaks under insertions.
• Dropping the Connection/Edge type-name suffixes.

Quick checklist

• ] Field returns {Type}Connection!, not a bare list.
• ] Connection has edges: [{Type}Edge!]! and pageInfo: PageInfo!.
• ] Edge has node plus cursor: String! (cursor on the edge).
• ] PageInfo has hasNextPage and endCursor.
• ] Arguments are first/after (and last/before).
• ] Cursor is an opaque string, not an offset or id.