useSuspenseQuery
Apollo Client API reference
Test
For a detailed explanation of useSuspenseQuery, see the fetching with Suspense reference.
Example
1 import { Suspense } from "react";
2 import { useSuspenseQuery } from "@apollo/client";
3
4 const listQuery = gql`
5 query {
6 list {
7 id
8 }
9 }
10 `;
11
12 function App() {
13 return (
14 <Suspense fallback={<Spinner />}>
15 <List />
16 </Suspense>
17 );
18 }
19
20 function List() {
21 const { data } = useSuspenseQuery(listQuery);
22
23 return (
24 <ol>
25 {data.list.map((item) => (
26 <Item key={item.id} id={item.id} />
27 ))}
28 </ol>
29 );
30 }Signature
1useSuspenseQuery<TData, TVariables>(
2 query: DocumentNode | TypedDocumentNode<TData, TVariables>,
3 options?: useSuspenseQuery.Options<TVariables>
4): useSuspenseQuery.Result<TData, TVariables>Parameters
A GraphQL query document parsed into an AST by gql.
An optional object containing options for the query. Instead of passing a useSuspenseQuery.Options object into the hook, you can also pass a skipToken to prevent the useSuspenseQuery hook from executing the query or suspending.
Show/hide child attributes
ApolloClientThe instance of ApolloClient to use to execute the query.
By default, the instance that's passed down via context is used, but you can provide a different instance here.
ErrorPolicySpecifies how the query handles a response that returns both GraphQL errors and partial results.
For details, see GraphQL error policies.
The default value is none, meaning that the query result includes error details but not partial results.
string | number | any[]A unique identifier for the query. Each item in the array must be a stable identifier to prevent infinite fetches.
This is useful when using the same query and variables combination in more than one component, otherwise the components may clobber each other. This can also be used to force the query to re-evaluate fresh.
TVariablesAn object containing all of the GraphQL variables your query requires to execute.
Each key in the object corresponds to a variable name, and that key's value corresponds to the variable value.
boolean⚠️ Deprecated
We recommend using
skipTokenin place of theskipoption as it is more type-safe.This option is deprecated and only supported to ease the migration from
useQuery. It will be removed in a future release. Please useskipTokeninstead of theskipoption as it is more type-safe.
If true, the query is not executed. The default value is false.
Recommended usage of skipToken:
1import { skipToken, useSuspenseQuery } from "@apollo/client";
2
3const { data } = useSuspenseQuery(
4 query,
5 id ? { variables: { id } } : skipToken
6);DefaultContextIf you're using Apollo Link, this object is the initial value of the context object that's passed along your link chain.
FetchPolicySpecifies how the query interacts with the Apollo Client cache during execution (for example, whether it checks the cache for results before sending a request to the server).
For details, see Setting a fetch policy.
The default value is cache-first.
RefetchWritePolicyWatched queries must opt into overwriting existing data on refetch, by passing refetchWritePolicy: "overwrite" in their WatchQueryOptions.
The default value is "overwrite".
booleanIf true, the query can return partial results from the cache if the cache doesn't contain results for all queried fields.
The default value is false.
Result
useSuspenseQuery.Result<TData, TVariables>Show/hide child attributes
DataValue.Complete<TData> | DataValue.Streaming<TData> | DataValue.Partial<TData> | undefinedAn object containing the result of your GraphQL query after it completes.
This value might be undefined if a query results in one or more errors (depending on the query's errorPolicy).
"complete" | "streaming" | "partial" | "empty"Describes the completeness of data.
empty: No data could be fulfilled from the cache or the result is incomplete.dataisundefined.partial: Some data could be fulfilled from the cache butdatais incomplete. This is only possible whenreturnPartialDataistrue.streaming:datais incomplete as a result of a deferred query and the result is still streaming in.complete:datais a fully satisfied query result fulfilled either from the cache or network.
ErrorLike | undefinedA single ErrorLike object describing the error that occured during the latest query execution.
For more information, see Handling operation errors.
ApolloClientThe instance of ApolloClient to use to execute the query.
By default, the instance that's passed down via context is used, but you can provide a different instance here.
NetworkStatusA number indicating the current network state of the query's associated request. See possible values.
Used in conjunction with the notifyOnNetworkStatusChange option.
FetchMoreFunction<TData, TVariables>A function that helps you fetch the next set of results for a paginated list field.
Read more...
Calling this function will cause the component to re-suspend, unless the call site is wrapped in startTransition.
RefetchFunction<TData, TVariables>A function that enables you to re-execute the query, optionally passing in new variables.
To guarantee that the refetch performs a network request, its fetchPolicy is set to network-only (unless the original query's fetchPolicy is no-cache or cache-and-network, which also guarantee a network request).
See also Refetching.
Returns a ResultPromise with an additional .retain() method. Calling
.retain() keeps the network operation running even if the ObservableQuery
no longer requires the result.
Read more...
Calling this function will cause the component to re-suspend, unless the call site is wrapped in startTransition.
SubscribeToMoreFunction<TData, TVariables>A function that enables you to execute a subscription, usually to subscribe to specific fields that were included in the query.
This function returns another function that you can call to terminate the subscription.