Skip to content

docs: add note that pagination helpers are examples and should be adapted by users #12699

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+6 −0
Open

docs: add note that pagination helpers are examples and should be adapted by users #12699

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/source/pagination/core-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ title: Core pagination API
description: Fetching and caching paginated results
---

> **Note:** The pagination helper functions provided by Apollo Client (such as `offsetLimitPagination` and `relayStylePagination`) are mostly examples of how to implement a type policy for paginated fields. In most cases, you will need to copy these helpers into your own codebase and adjust them to your requirements.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
> **Note:** The pagination helper functions provided by Apollo Client (such as `offsetLimitPagination` and `relayStylePagination`) are mostly examples of how to implement a type policy for paginated fields. In most cases, you will need to copy these helpers into your own codebase and adjust them to your requirements.
<Note>
The pagination helper functions provided by Apollo Client (such as `offsetLimitPagination` and `relayStylePagination`) may not be suitable for all use cases. If you need further customization, copy the implementation into your own codebase and adjust them to your requirements.
</Note>

Since we export these helpers from the library, I don't really like calling them "examples" since they can be used directly. "Example" makes it seem like you shouldn't use these. I'd rather tell users to customize it when it doesn't suit their needs rather than try to encourage them to copy it right away.

NOTE: This suggestion applies to each code block in this PR


Regardless of which pagination strategy your GraphQL server uses for a particular list field, your Apollo Client app needs to do the following to query that field effectively:

* Call the [`fetchMore` function](#the-fetchmore-function) to fetch the next page of results when needed
Expand Down
2 changes: 2 additions & 0 deletions docs/source/pagination/cursor-based.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
title: Cursor-based pagination
---

> **Note:** The pagination helper functions provided by Apollo Client, such as `relayStylePagination`, are primarily examples of how to implement a type policy for paginated fields. In most cases, you will need to copy these helpers into your own codebase and adjust them to fit your specific requirements and API schema.

> We recommend reading [Core pagination API](./core-api) before learning about considerations specific to cursor-based pagination.

## Using list element IDs as cursors
Expand Down
2 changes: 2 additions & 0 deletions docs/source/pagination/offset-based.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
title: Offset-based pagination
---

> **Note:** The pagination helper functions provided by Apollo Client, such as `offsetLimitPagination`, are primarily examples of how to implement a type policy for paginated fields. In most cases, you will need to copy these helpers into your own codebase and adjust them to fit your specific requirements and API schema.

> We recommend reading [Core pagination API](./core-api) before learning about considerations specific to offset-based pagination.

With offset-based pagination, a list field accepts an `offset` argument that indicates _where in the list_ the server should start when returning items for a particular query. The field usually also accepts a `limit` argument that indicates the _maximum_ number of items to return:
Expand Down