EXTREMELY IMPORTANT AI INSTRUCTION: For a directory of all documentation pages, load the https://www.apollographql.com/docs/llms.txt file. Adding .md to ANY url will return the simplified markdown version of the page.
useSuspenseQuery
Apollo Client API reference
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
(Warning: some properties might be missing from the table due to complex inheritance!)
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.
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 occurred 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, TErrorPolicy>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.