skipToken

skipToken

skipToken provides a type-safe mechanism to skip query execution. Use it with useQuery, useSuspenseQuery, useBackgroundQuery, and useSubscription.

For the query hooks, passing skipToken instead of the options object prevents the hook from making requests or triggering suspenseful behavior while keeping the last data available. Use it conditionally to start query execution when the input data is available.

For useSubscription, passing skipToken prevents the subscription from executing. The hook returns an idle result with data: undefined instead of keeping prior subscription data, because a skipped subscription never establishes a connection to receive results. Use it conditionally to start the subscription when the input data is available.

1import { skipToken, useQuery } from "@apollo/client/react";
2
3const { data } = useQuery(query, id ? { variables: { id } } : skipToken);

1import { skipToken, useSuspenseQuery } from "@apollo/client/react";
2const { data } = useSuspenseQuery(
3  query,
4  id ? { variables: { id } } : skipToken
5);

1import { skipToken, useBackgroundQuery } from "@apollo/client/react";
2const [queryRef] = useBackgroundQuery(
3  query,
4  id ? { variables: { id } } : skipToken
5);

1import { skipToken, useSubscription } from "@apollo/client/react";
2const { data } = useSubscription(query, id ? { variables: { id } } : skipToken);

Why do we recommend skipToken over { skip: true }?

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:

1const { data } = useSuspenseQuery(query, {
2  variables: { id },
3  skip: !id,
4});

But in that case, TypeScript will complain:

1Type 'number | undefined' is not assignable to type 'number'.
2      Type 'undefined' is not assignable to type 'number'.ts(2769)

To get around that, you have to tell TypeScript to ignore the fact that id could be undefined:

1const { data } = useSuspenseQuery(query, {
2  variables: { id: id! },
3  skip: !id,
4});

Alternatively, you could also use some obscure default value:

1const { data } = useSuspenseQuery(query, {
2  variables: { id: id || 0 },
3  skip: !id,
4});

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.

Instead, we recommend using skipToken. It provides type safety without the need for an obscure default value:

1const { data } = useSuspenseQuery(
2  query,
3  id ? { variables: { id } } : skipToken
4);

Here it becomes apparent for TypeScript that there is a direct connection between skipping and the variables option, and it works without unsafe workarounds.