Mirror: The highly customizable and versatile GraphQL client with which you add on features like normalized caching as you grow.
docs: Add more extensive infinite pagination example code (#3258)
authored by
Phil Pluckthun
and committed by
GitHub
00c840ff
7a11714f
+344
-6
+4
-2
docs/basics/ui-patterns.md
+4
-2
docs/basics/ui-patterns.md
···
87
87
88
88
Here we keep an array of all `variables` we've encountered and use them to render their
89
89
respective `result` page. This only rerenders the additional page rather than having a long
90
-
list that constantly changes. [You can find a full code example of this pattern in our example folder on the topic of Graphcache pagination.](https://github.com/urql-graphql/urql/tree/main/examples/with-graphcache-pagination)
90
+
list that constantly changes. [You can find a full code example of this pattern in our example folder on the topic of pagination.](https://github.com/urql-graphql/urql/tree/main/examples/with-pagination)
91
91
92
-
We also do not need to use our normalized cache to achieve this. As long as we're able to split individual lists up into chunks across components, we can also solve this problem entirely in UI code. [Read our example code on how to achieve this.](https://github.com/urql-graphql/urql/tree/main/examples/with-pagination)
92
+
This code doesn't take changing variables into account, which will affect the cursors. For an
93
+
example that takes full infinite scrolling into account, [you can find a full code example of an
94
+
extended pattern in our example folder on the topic of infinite pagination.](https://github.com/urql-graphql/urql/tree/main/examples/with-infinite--pagination)
93
95
94
96
## Prefetching data
95
97
+8
docs/graphcache/local-resolvers.md
+8
docs/graphcache/local-resolvers.md
···
452
452
with separate components per page in environments like React Native, where a `FlatList` would
453
453
require a flat, infinite list of items.
454
454
455
+
> **Note:** If you don't need a flat array of results, you can also achieve infinite pagination
456
+
> with only UI code. [You can find a code example of UI infinite pagination in our example folder.](https://github.com/urql-graphql/urql/tree/main/examples/with-pagination)
457
+
458
+
[You can find a code example of infinite pagination with Graphcahce in our example folder.](https://github.com/urql-graphql/urql/tree/main/examples/with-graphcache-pagination).
459
+
Please keep in mind that this patterns has some limitations when you're handling cache updates.
460
+
Deleting old pages from the cache selectively may be difficult, so the UI pattern in the above
461
+
note is preferred.
462
+
455
463
### Simple Pagination
456
464
457
465
Given we have a schema that uses some form of `offset` and `limit` based pagination, we can use the
+3
-1
examples/README.md
+3
-1
examples/README.md
···
5
5
| [`with-svelte`](./with-svelte) | Shows a basic query in `@urql/svelte` with Svelte. |
6
6
| [`with-vue3`](./with-vue3) | Shows a basic query in `@urql/vue` with Vue 3. |
7
7
| [`with-next`](./with-next) | Shows some examples with `next-urql` in Next.js with the default, `getStaticProps` and `getServerSideProps`. |
8
-
| [`with-pagination`](./with-pagination) | Shows how to generically set up infinite pagination with `urql` in UI code. |
8
+
| [`with-pagination`](./with-pagination) | Shows how to generically set up pagination with `urql` in UI code. |
9
+
| [`with-infinite-pagination`](./with-infinite-pagination) | Shows how to generically set up infinite scrolling pagination with `urql` in UI code. |
9
10
| [`with-apq`](./with-apq) | Shows Automatic Persisted Queries with `@urql/exchange-persisted-fetch`. |
10
11
| [`with-graphcache-updates`](./with-graphcache-updates) | Shows manual cache updates with `@urql/exchange-graphcache`. |
11
12
| [`with-graphcache-pagination`](./with-graphcache-pagination) | Shows the automatic infinite pagination helpers from `@urql/exchange-graphcache`. |
···
13
14
| [`with-refresh-auth`](./with-refresh-auth) | Shows an example of authentication with refresh tokens using `@urql/exchange-auth`. |
14
15
| [`with-retry`](./with-retry) | Shows how to set up `@urql/exchange-retry` for retrying failed operations. |
15
16
| [`with-defer-stream-directives`](./with-defer-stream-directives) | Demonstrates `urql` and `@urql/exchange-graphcache` with built-in support for `@defer` and `@stream`. |
17
+
| [`with-subscriptions-via-fetch`](./with-subscriptions-via-fetch) | Demonstrates `urql` executing subscriptions with a GraphQL Yoga API via the `fetchExchange`. |
+41
examples/with-infinite-pagination/README.md
+41
examples/with-infinite-pagination/README.md
···
1
+
# With Infinite Pagination (in React)
2
+
3
+
This example shows how to implement **infinite scroll** pagination with `urql`
4
+
in your React UI code.
5
+
6
+
It's slightly different than the [`with-pagination`](../with-pagination) example
7
+
and shows how to implement a full infinitely scrolling list with only your UI code,
8
+
while fulfilling the following requirements:
9
+
10
+
- Unlike with [`with-graphcache-pagination`](../with-graphcache-pagination),
11
+
the `urql` cache doesn't have to know about your infinite list, and this works
12
+
with any cache, even the document cache
13
+
- Unlike with [`with-pagination`](../with-pagination), your list can use cursors,
14
+
and each page can update, while keeping the variables for the next page dynamic.
15
+
- It uses no added state, no extra processing of lists, and you need no effects.
16
+
17
+
In other words, unless you need a flat array of items
18
+
(e.g. unless you’re using React Native’s `FlatList`), this is the simplest way
19
+
to implement an infinitely scrolling, paginated list.
20
+
21
+
This example is also reapplicable to other libraries, like Svelte or Vue.
22
+
23
+
To run this example install dependencies and run the `start` script:
24
+
25
+
```sh
26
+
yarn install
27
+
yarn run start
28
+
# or
29
+
npm install
30
+
npm run start
31
+
```
32
+
33
+
This example contains:
34
+
35
+
- The `urql` bindings and a React app with a client set up in [`src/App.js`](src/App.jsx)
36
+
- This also contains a search input which is used as input for the GraphQL queries
37
+
- All pagination components are in [`src/SearchResults.jsx`](src/SearchResults.jsx)
38
+
- The `SearchRoot` component loads the first page of results and renders `SearchPage`
39
+
- The `SearchPage` displays cached results, and otherwise only starts a network request on
40
+
a button press
41
+
- The `Package` component is used for each result item
+27
examples/with-infinite-pagination/index.html
+27
examples/with-infinite-pagination/index.html
···
1
+
<!DOCTYPE html>
2
+
<html lang="en">
3
+
<head>
4
+
<meta charset="UTF-8">
5
+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+
<title>with-pagination</title>
7
+
<style>
8
+
body {
9
+
margin: 0;
10
+
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
11
+
'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
12
+
sans-serif;
13
+
-webkit-font-smoothing: antialiased;
14
+
-moz-osx-font-smoothing: grayscale;
15
+
}
16
+
17
+
code {
18
+
font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New',
19
+
monospace;
20
+
}
21
+
</style>
22
+
</head>
23
+
<body>
24
+
<div id="root"></div>
25
+
<script type="module" src="/src/index.jsx"></script>
26
+
</body>
27
+
</html>
+19
examples/with-infinite-pagination/package.json
+19
examples/with-infinite-pagination/package.json
···
1
+
{
2
+
"name": "with-pagination",
3
+
"version": "0.0.0",
4
+
"private": true,
5
+
"scripts": {
6
+
"start": "vite"
7
+
},
8
+
"dependencies": {
9
+
"@urql/core": "^4.0.10",
10
+
"graphql": "^16.6.0",
11
+
"react": "^18.2.0",
12
+
"react-dom": "^18.2.0",
13
+
"urql": "^4.0.3"
14
+
},
15
+
"devDependencies": {
16
+
"@vitejs/plugin-react": "^3.1.0",
17
+
"vite": "^4.2.0"
18
+
}
19
+
}
+52
examples/with-infinite-pagination/src/App.jsx
+52
examples/with-infinite-pagination/src/App.jsx
···
1
+
import React, { useState } from 'react';
2
+
import { Client, Provider, cacheExchange, fetchExchange } from 'urql';
3
+
4
+
import SearchRoot from './SearchResults';
5
+
6
+
const client = new Client({
7
+
// The GraphQL API we use here uses the NPM registry
8
+
// We'll use it to display search results for packages
9
+
url: 'https://trygql.formidable.dev/graphql/relay-npm',
10
+
exchanges: [cacheExchange, fetchExchange],
11
+
});
12
+
13
+
// We will be able to enter a search term, and this term
14
+
// will render search results
15
+
function PaginatedNpmSearch() {
16
+
const [search, setSearch] = useState('urql');
17
+
18
+
const setSearchValue = event => {
19
+
event.preventDefault();
20
+
setSearch(event.currentTarget.value);
21
+
};
22
+
23
+
return (
24
+
<>
25
+
<header>
26
+
<h4>Type to search for npm packages</h4>
27
+
{/* Try changing the search input, then changing it back... */}
28
+
{/* If you do this, all cached pages will display immediately! */}
29
+
<input
30
+
type="search"
31
+
value={search}
32
+
onChange={setSearchValue}
33
+
placeholder="npm package name"
34
+
/>
35
+
</header>
36
+
<main>
37
+
{/* The <SearchRoot> component contains all querying logic */}
38
+
<SearchRoot searchTerm={search} />
39
+
</main>
40
+
</>
41
+
);
42
+
}
43
+
44
+
function App() {
45
+
return (
46
+
<Provider value={client}>
47
+
<PaginatedNpmSearch />
48
+
</Provider>
49
+
);
50
+
}
51
+
52
+
export default App;
+172
examples/with-infinite-pagination/src/SearchResults.jsx
+172
examples/with-infinite-pagination/src/SearchResults.jsx
···
1
+
import React, { useCallback } from 'react';
2
+
import { gql, useQuery } from 'urql';
3
+
4
+
// We define a fragment, just to define the data
5
+
// that our item component will use in the results list
6
+
const packageFragment = gql`
7
+
fragment SearchPackage on Package {
8
+
id
9
+
name
10
+
latest: version(selector: "latest") {
11
+
version
12
+
}
13
+
}
14
+
`;
15
+
16
+
// The main query fetches the first page of results and gets our `PageInfo`
17
+
// This tells us whether more pages are present which we can query.
18
+
const rootQuery = gql`
19
+
query SearchRoot($searchTerm: String!, $resultsPerPage: Int!) {
20
+
search(query: $searchTerm, first: $resultsPerPage) {
21
+
edges {
22
+
cursor
23
+
node {
24
+
...SearchPackage
25
+
}
26
+
}
27
+
pageInfo {
28
+
hasNextPage
29
+
endCursor
30
+
}
31
+
}
32
+
}
33
+
34
+
${packageFragment}
35
+
`;
36
+
37
+
// We split the next pages we load into a separate query. In this example code,
38
+
// both queries could be the same, but we keep them separate for educational
39
+
// purposes.
40
+
// In a real app, your "root query" would often fetch more data than the search page query.
41
+
const pageQuery = gql`
42
+
query SearchPage(
43
+
$searchTerm: String!
44
+
$resultsPerPage: Int!
45
+
$afterCursor: String!
46
+
) {
47
+
search(query: $searchTerm, first: $resultsPerPage, after: $afterCursor) {
48
+
edges {
49
+
cursor
50
+
node {
51
+
...SearchPackage
52
+
}
53
+
}
54
+
pageInfo {
55
+
hasNextPage
56
+
endCursor
57
+
}
58
+
}
59
+
}
60
+
61
+
${packageFragment}
62
+
`;
63
+
64
+
// This is the <SearchRoot> component that we render in `./App.jsx`.
65
+
// It accepts our variables as props.
66
+
const SearchRoot = ({ searchTerm = 'urql', resultsPerPage = 10 }) => {
67
+
const [rootResult] = useQuery({
68
+
query: rootQuery,
69
+
variables: {
70
+
searchTerm,
71
+
resultsPerPage,
72
+
},
73
+
});
74
+
75
+
if (rootResult.fetching) {
76
+
return <em>Loading...</em>;
77
+
}
78
+
79
+
// Here, we render the results as a list into a fragment, and if `hasNextPage`
80
+
// is truthy, we immediately render <SearchPage> for the next page.
81
+
const connection = rootResult.data?.search;
82
+
return (
83
+
<>
84
+
{connection?.edges?.length === 0 ? <strong>No Results</strong> : null}
85
+
86
+
{connection?.edges.map(edge => (
87
+
<Package key={edge.cursor} node={edge.node} />
88
+
))}
89
+
90
+
{/* The <SearchPage> component receives the same props, plus the `afterCursor` for its variables */}
91
+
{connection?.pageInfo.hasNextPage ? (
92
+
<SearchPage
93
+
searchTerm={searchTerm}
94
+
resultsPerPage={resultsPerPage}
95
+
afterCursor={connection.pageInfo.endCursor}
96
+
/>
97
+
) : rootResult.fetching ? (
98
+
<em>Loading...</em>
99
+
) : null}
100
+
</>
101
+
);
102
+
};
103
+
104
+
// The <SearchPage> is rendered for each page of results, except for the root query.
105
+
// It renders *itself* recursively, for the next page of results.
106
+
const SearchPage = ({ searchTerm, resultsPerPage, afterCursor }) => {
107
+
// Each <SearchPage> fetches its own page results!
108
+
const [pageResult, executeQuery] = useQuery({
109
+
query: pageQuery,
110
+
// Initially, we *only* want to display results if, they're cached
111
+
requestPolicy: 'cache-only',
112
+
// We don't want to run the query if we don't have a cursor (in this example, this will never happen)
113
+
pause: !afterCursor,
114
+
variables: {
115
+
searchTerm,
116
+
resultsPerPage,
117
+
afterCursor,
118
+
},
119
+
});
120
+
121
+
// We only load more results, by allowing the query to make a network request, if
122
+
// a button has pressed.
123
+
// In your app, you may want to do this automatically if the user can see the end of
124
+
// your list, e.g. via an IntersectionObserver.
125
+
const onLoadMore = useCallback(() => {
126
+
// This tells the query above to execute and instead of `cache-only`, which forbids
127
+
// network requests, we now allow them.
128
+
executeQuery({ requestPolicy: 'cache-first' });
129
+
}, [executeQuery]);
130
+
131
+
if (pageResult.fetching) {
132
+
return <em>Loading...</em>;
133
+
}
134
+
135
+
const connection = pageResult.data?.search;
136
+
return (
137
+
<>
138
+
{/* If our query has nodes, we render them here. The page renders its own results */}
139
+
{connection?.edges.map(edge => (
140
+
<Package key={edge.cursor} node={edge.node} />
141
+
))}
142
+
143
+
{/* If we have a next page, we now render it recursively! */}
144
+
{/* As before, the next <SearchPage> will not fetch immediately, but only query from cache */}
145
+
{connection?.pageInfo.hasNextPage ? (
146
+
<SearchPage
147
+
searchTerm={searchTerm}
148
+
resultsPerPage={resultsPerPage}
149
+
afterCursor={connection.pageInfo.endCursor}
150
+
/>
151
+
) : pageResult.fetching ? (
152
+
<em>Loading...</em>
153
+
) : null}
154
+
155
+
{!connection && !pageResult.fetching ? (
156
+
<button type="button" onClick={onLoadMore}>
157
+
Load more
158
+
</button>
159
+
) : null}
160
+
</>
161
+
);
162
+
};
163
+
164
+
// This is the component that then renders each result item
165
+
const Package = ({ node }) => (
166
+
<section>
167
+
<strong>{node.name}</strong>
168
+
<em>@{node.latest.version}</em>
169
+
</section>
170
+
);
171
+
172
+
export default SearchRoot;
+6
examples/with-infinite-pagination/src/index.jsx
+6
examples/with-infinite-pagination/src/index.jsx
+7
examples/with-infinite-pagination/vite.config.js
+7
examples/with-infinite-pagination/vite.config.js
+5
-3
examples/with-pagination/README.md
+5
-3
examples/with-pagination/README.md
···
1
1
# With Pagination (in React)
2
2
3
-
This example shows how to implement infinite pagination with `urql` in your React UI code. It
4
-
renders several pages as fragments with one component managing the variables for the page queries.
5
-
This example is also reapplicable to other libraries, like Svelte or Vue.
3
+
This example shows how to implement pagination with `urql` in your React UI code.
4
+
5
+
It renders several pages as fragments with one component managing the variables
6
+
for the page queries. This example is also reapplicable to other libraries,
7
+
like Svelte or Vue.
6
8
7
9
To run this example install dependencies and run the `start` script:
8
10