You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
// Use `skipToken` in place of `skip: true` for better type safety
11
+
// for required variables
12
+
const { data } =useQuery(QUERY, id? { variables: { id } } :skipToken);
13
+
```
14
+
15
+
Note: this change is provided as a patch within the 4.0 minor version because the changes to TypeScript validation with required variables in version 4.0 made using the `skip` option more difficult.
Copy file name to clipboardExpand all lines: docs/source/api/react/skipToken.mdx
+8-6Lines changed: 8 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,9 +7,15 @@ description: Apollo Client API reference
7
7
8
8
## `skipToken`
9
9
10
-
`skipToken` provides a type-safe mechanism to skip query execution. It is currently supported with `useSuspenseQuery` and `useBackgroundQuery`.
10
+
`skipToken` provides a type-safe mechanism to skip query execution. It is currently supported with `useQuery`, `useSuspenseQuery` and `useBackgroundQuery`.
11
11
When you pass a `skipToken` to one of the supported hooks instead of the `options` object, the hook will not cause any requests or suspenseful behavior and keeps the last `data` available. It is typically used conditionally to start query execution when the input data is available.
12
12
13
+
```js title="Recommended usage of skipToken with useQuery"
Note: **Why do we recommend `skipToken` over `{ skip: true }`?**
35
+
### Why do we recommend `skipToken` over `{ skip: true }`?
32
36
33
37
Imagine this very common scenario for `skip`: You want to skip your query if a certain required variable is not set. You might be tempted to write something like this:
34
38
@@ -76,5 +80,3 @@ const { data } = useSuspenseQuery(
76
80
```
77
81
78
82
Here it becomes apparent for TypeScript that there is a direct connection between skipping and the `variables` option - and it will work without unsafe workarounds.
Copy file name to clipboardExpand all lines: docs/source/data/queries.mdx
+58Lines changed: 58 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -799,6 +799,64 @@ Uses the same logic as `cache-first`, except this query does _not_ automatically
799
799
</tbody>
800
800
</table>
801
801
802
+
<MinVersion version="4.0.4">
803
+
804
+
## Skipping queries with `skipToken`
805
+
806
+
</MinVersion>
807
+
808
+
`skipToken` provides a type-safe mechanism to skip query execution. When you pass `skipToken` to `useQuery` instead of the options object, the hook will not execute the query and keeps the last `data` available. It is typically used conditionally to start query execution when the input data is available.
809
+
810
+
```js title="Recommended usage of skipToken with useQuery"
const { data } =useQuery(query, id ? { variables: { id } } : skipToken);
814
+
```
815
+
816
+
Imagine this common scenario: You want to skip your query if a certain required variable is not set. You might be tempted to write something like this:
817
+
818
+
```ts
819
+
const { data } =useQuery(query, {
820
+
variables: { id },
821
+
skip:!id,
822
+
});
823
+
```
824
+
825
+
But in that case, TypeScript will complain:
826
+
827
+
```
828
+
Type 'number | undefined' is not assignable to type 'number'.
829
+
Type 'undefined' is not assignable to type 'number'.ts(2769)
830
+
```
831
+
832
+
To get around that, you have to tell TypeScript to ignore the fact that `id` could be `undefined`:
833
+
834
+
```ts
835
+
const { data } =useQuery(query, {
836
+
variables: { id: id! },
837
+
skip:!id,
838
+
});
839
+
```
840
+
841
+
Alternatively, you could also use some obscure default value:
842
+
843
+
```ts
844
+
const { data } =useQuery(query, {
845
+
variables: { id: id ||0 },
846
+
skip:!id,
847
+
});
848
+
```
849
+
850
+
Both of these solutions hide a potential bug. If your `skip` logic becomes more complex, you might accidentally introduce a bug that causes your query to execute, even when `id` is still `undefined`. In that case, TypeScript cannot warn you about it.
851
+
852
+
Instead we recommend using `skipToken`. It provides type safety without the need for an obscure default value:
853
+
854
+
```ts
855
+
const { data } =useQuery(query, id ? { variables: { id } } : skipToken);
856
+
```
857
+
858
+
Here it becomes apparent for TypeScript that there is a direct connection between skipping and the `variables` option - and it will work without unsafe workarounds.
859
+
802
860
## `useQuery` API
803
861
804
862
Supported options and result fields for the `useQuery` hook are listed below.
0 commit comments