Hooks

ApolloClient<any>

The 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.

onCompleted (optional)

ErrorPolicy

Specifies 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.

(data: NoInfer<TData>) => void

A callback function that's called when your query successfully completes with zero errors (or if errorPolicy is ignore and partial data is returned).

This function is passed the query's result data.

(error: ApolloError) => void

A callback function that's called when the query encounters one or more errors (unless errorPolicy is ignore).

This function is passed an ApolloError object that contains either a networkError object or a graphQLErrors array, depending on the error(s) that occurred.

skip (optional)

boolean

If true, the query is not executed.

The default value is false.

NoInfer<TVariables>

An 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.

Networking options

notifyOnNetworkStatusChange (optional)

DefaultContext

If you're using Apollo Link, this object is the initial value of the context object that's passed along your link chain.

boolean

If true, the in-progress query's associated component re-renders whenever the network status changes or a network error occurs.

The default value is false.

pollInterval (optional)

number

Specifies the interval (in milliseconds) at which the query polls for updated results.

The default value is 0 (no polling).

skipPollAttempt (optional)

() => boolean

A callback function that's called whenever a refetch attempt occurs while polling. If the function returns true, the refetch is skipped and not reattempted until the next poll interval.

ssr (optional)

boolean

Pass false to skip executing the query during server-side rendering.

Caching options

initialFetchPolicy (optional)

WatchQueryFetchPolicy

Specifies 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.

WatchQueryFetchPolicy

Defaults to the initial value of options.fetchPolicy, but can be explicitly configured to specify the WatchQueryFetchPolicy to revert back to whenever variables change (unless nextFetchPolicy intervenes).

nextFetchPolicy (optional)

WatchQueryFetchPolicy | ((this: WatchQueryOptions<NoInfer<TVariables>, NoInfer<TData>>, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext<NoInfer<TData>, NoInfer<TVariables>>) => WatchQueryFetchPolicy)

Specifies the FetchPolicy to be used after this query has completed.

RefetchWritePolicy

Specifies whether a NetworkStatus.refetch operation should merge incoming field data with existing data, or overwrite the existing data. Overwriting is probably preferable, but merging is currently the default behavior, for backwards compatibility with Apollo Client 3.x.

boolean

If 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.

Other

partialRefetch (optional)

boolean

⚠️ Deprecated

Using canonizeResults can result in memory leaks so we generally do not recommend using this option anymore. A future version of Apollo Client will contain a similar feature without the risk of memory leaks.

Whether to canonize cache results before returning them. Canonization takes some extra time, but it speeds up future deep equality comparisons. Defaults to false.

boolean

⚠️ Deprecated

Setting this option is unnecessary in Apollo Client 3, thanks to a more consistent application of fetch policies. It might be removed in a future release.

If true, causes a query refetch if the query result is detected as partial.

The default value is false.

Result

Query result object

1
QueryResult<TData, TVariables>

Show/hide child attributes

Operation data

data

TData | undefined

An 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).

error (optional)

ApolloError

If the query produces one or more errors, this object contains either an array of graphQLErrors or a single networkError. Otherwise, this value is undefined.

For more information, see Handling operation errors.

previousData (optional)

TData

An object containing the result from the most recent previous execution of this query.

This value is undefined if this is the query's first execution.

variables

TVariables | undefined

An object containing the variables that were provided for the query.

Network info

called

boolean

If true, the associated lazy query has been executed.

This field is only present on the result object returned by useLazyQuery.

client

ApolloClient<any>

The instance of Apollo Client that executed the query. Can be useful for manually executing followup queries or writing data to the cache.

loading

boolean

If true, the query is still in flight and results have not yet been returned.

networkStatus

NetworkStatus

A number indicating the current network state of the query's associated request. See possible values.

Used in conjunction with the notifyOnNetworkStatusChange option.

Helper functions

fetchMore

<TFetchData = TData, TFetchVars extends OperationVariables = TVariables>(fetchMoreOptions: FetchMoreQueryOptions<TFetchVars, TFetchData> & {
        updateQuery?: (previousQueryResult: TData, options: {
            fetchMoreResult: TFetchData;
            variables: TFetchVars;
        }) => TData;
    }) => Promise<ApolloQueryResult<TFetchData>>

A function that helps you fetch the next set of results for a paginated list field.

refetch

(variables?: Partial<TVariables>) => Promise<ApolloQueryResult<TData>>

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).

`useLazyQuery`
Since 3.0.0

A hook for imperatively executing queries in an Apollo application, e.g. in response to user interaction.

Refer to the Queries - Manual execution with useLazyQuery section for a more in-depth overview of useLazyQuery.

Example

1
import { gql, useLazyQuery } from "@apollo/client";
2

3
const GET_GREETING = gql`
4
  query GetGreeting($language: String!) {
5
    greeting(language: $language) {
6
      message
7
    }
8
  }
9
`;
10

11
function Hello() {
12
  const [loadGreeting, { called, loading, data }] = useLazyQuery(
13
    GET_GREETING,
14
    { variables: { language: "english" } }
15
  );
16
  if (called && loading) return <p>Loading ...</p>
17
  if (!called) {
18
    return <button onClick={() => loadGreeting()}>Load greeting</button>
19
  }
20
  return <h1>Hello {data.greeting.message}!</h1>;
21
}

Signature

1
function useLazyQuery<TData, TVariables>(
2
  query: DocumentNode | TypedDocumentNode<TData, TVariables>,
3
  options?: LazyQueryHookOptions<NoInfer<TData>, NoInfer<TVariables>>
4
): LazyQueryResultTuple<TData, TVariables>

(src/react/hooks/useLazyQuery.ts)

Parameters

Name / Type

Description

query

DocumentNode | TypedDocumentNode<TData, TVariables>

A GraphQL query document parsed into an AST by gql.

options (optional)

LazyQueryHookOptions<NoInfer<TData>, NoInfer<TVariables>>

Default options to control how the query is executed.

Show/hide child attributes

Operation options

ApolloClient<any>

The 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.

onCompleted (optional)

ErrorPolicy

Specifies 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.

(data: NoInfer<TData>) => void

A callback function that's called when your query successfully completes with zero errors (or if errorPolicy is ignore and partial data is returned).

This function is passed the query's result data.

(error: ApolloError) => void

A callback function that's called when the query encounters one or more errors (unless errorPolicy is ignore).

This function is passed an ApolloError object that contains either a networkError object or a graphQLErrors array, depending on the error(s) that occurred.

NoInfer<TVariables>

An 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.

Networking options

notifyOnNetworkStatusChange (optional)

DefaultContext

If you're using Apollo Link, this object is the initial value of the context object that's passed along your link chain.

boolean

If true, the in-progress query's associated component re-renders whenever the network status changes or a network error occurs.

The default value is false.

pollInterval (optional)

number

Specifies the interval (in milliseconds) at which the query polls for updated results.

The default value is 0 (no polling).

skipPollAttempt (optional)

() => boolean

A callback function that's called whenever a refetch attempt occurs while polling. If the function returns true, the refetch is skipped and not reattempted until the next poll interval.

ssr (optional)

boolean

Pass false to skip executing the query during server-side rendering.

Caching options

initialFetchPolicy (optional)

WatchQueryFetchPolicy

Specifies 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.

WatchQueryFetchPolicy

nextFetchPolicy (optional)

WatchQueryFetchPolicy | ((this: WatchQueryOptions<NoInfer<TVariables>, NoInfer<TData>>, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext<NoInfer<TData>, NoInfer<TVariables>>) => WatchQueryFetchPolicy)

Specifies the FetchPolicy to be used after this query has completed.

RefetchWritePolicy

boolean

If 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.

Other

partialRefetch (optional)

boolean

⚠️ Deprecated

Whether to canonize cache results before returning them. Canonization takes some extra time, but it speeds up future deep equality comparisons. Defaults to false.

boolean

⚠️ Deprecated

Setting this option is unnecessary in Apollo Client 3, thanks to a more consistent application of fetch policies. It might be removed in a future release.

If true, causes a query refetch if the query result is detected as partial.

The default value is false.

Result

1
[execute: LazyQueryExecFunction<TData, TVariables>, result: QueryResult<TData, TVariables>]

A tuple of two values:

Name	Type	Description
execute	`(options?: LazyQueryHookOptions<TVariables>) => Promise<LazyQueryResult<TData, TVariables>>`	Function that can be triggered to execute the suspended query. After being called, `useLazyQuery` behaves just like `useQuery`. The `useLazyQuery` function returns a promise that fulfills with a query result when the query succeeds or fails.
result	`QueryResult<TData, TVariables>`	The result of the query. See the `useQuery` hook for more details.
Show/hide child attributes Operation data `data` `TData \| undefined` An 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`). `error` (optional) `ApolloError` If the query produces one or more errors, this object contains either an array of `graphQLErrors` or a single `networkError`. Otherwise, this value is `undefined`. For more information, see Handling operation errors. `previousData` (optional) `TData` An object containing the result from the most recent previous execution of this query. This value is `undefined` if this is the query's first execution. `variables` `TVariables \| undefined` An object containing the variables that were provided for the query. Network info `called` `boolean` If `true`, the associated lazy query has been executed. This field is only present on the result object returned by `useLazyQuery`. `client` `ApolloClient<any>` The instance of Apollo Client that executed the query. Can be useful for manually executing followup queries or writing data to the cache. `loading` `boolean` If `true`, the query is still in flight and results have not yet been returned. `networkStatus` `NetworkStatus` A number indicating the current network state of the query's associated request. See possible values. Used in conjunction with the `notifyOnNetworkStatusChange` option. Helper functions `fetchMore` `<TFetchData = TData, TFetchVars extends OperationVariables = TVariables>(fetchMoreOptions: FetchMoreQueryOptions<TFetchVars, TFetchData> & { updateQuery?: (previousQueryResult: TData, options: { fetchMoreResult: TFetchData; variables: TFetchVars; }) => TData; }) => Promise<ApolloQueryResult<TFetchData>>` A function that helps you fetch the next set of results for a paginated list field. `refetch` `(variables?: Partial<TVariables>) => Promise<ApolloQueryResult<TData>>` 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. `startPolling` `(pollInterval: number) => void` A function that instructs the query to begin re-executing at a specified interval (in milliseconds). `stopPolling` `() => void` A function that instructs the query to stop polling after a previous call to `startPolling`. `subscribeToMore` `<TSubscriptionData = TData, TSubscriptionVariables extends OperationVariables = TVariables>(options: SubscribeToMoreOptions<TData, TSubscriptionVariables, TSubscriptionData>) => () => void` 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. `updateQuery` `<TVars extends OperationVariables = TVariables>(mapFn: (previousQueryResult: TData, options: Pick<WatchQueryOptions<TVars, TData>, "variables">) => TData) => void` A function that enables you to update the query's cached result without executing a followup GraphQL operation. See using updateQuery and updateFragment for additional information. Other `observable` `ObservableQuery<TData, TVariables>` A reference to the internal `ObservableQuery` used by the hook.

`useMutation`
Since 3.0.0

Refer to the Mutations section for a more in-depth overview of useMutation.

Example

1
import { gql, useMutation } from '@apollo/client';
2

3
const ADD_TODO = gql`
4
  mutation AddTodo($type: String!) {
5
    addTodo(type: $type) {
6
      id
7
      type
8
    }
9
  }
10
`;
11

12
function AddTodo() {
13
  let input;
14
  const [addTodo, { data }] = useMutation(ADD_TODO);
15

16
  return (
17
    <div>
18
      <form
19
        onSubmit={e => {
20
          e.preventDefault();
21
          addTodo({ variables: { type: input.value } });
22
          input.value = '';
23
        }}
24
      >
25
        <input
26
          ref={node => {
27
            input = node;
28
          }}
29
        />
30
        <button type="submit">Add Todo</button>
31
      </form>
32
    </div>
33
  );
34
}

Signature

1
function useMutation<TData, TVariables, TContext, TCache>(
2
  mutation: DocumentNode | TypedDocumentNode<TData, TVariables>,
3
  options?: MutationHookOptions<NoInfer<TData>, NoInfer<TVariables>, TContext, TCache>
4
): MutationTuple<TData, TVariables, TContext, TCache>

(src/react/hooks/useMutation.ts)

Parameters

Name / Type

Description

mutation

DocumentNode | TypedDocumentNode<TData, TVariables>

A GraphQL mutation document parsed into an AST by gql.

options (optional)

MutationHookOptions<NoInfer<TData>, NoInfer<TVariables>, TContext, TCache>

Options to control how the mutation is executed.

Show/hide child attributes

Operation options

awaitRefetchQueries (optional)

boolean

If true, makes sure all queries included in refetchQueries are completed before the mutation is considered complete.

The default value is false (queries are refetched asynchronously).

ignoreResults (optional)

ErrorPolicy

Specifies how the mutation 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 mutation result includes error details but not partial results.

boolean

If true, the mutation's data property is not updated with the mutation's result.

The default value is false.

onCompleted (optional)

(data: NoInfer<TData>, clientOptions?: BaseMutationOptions) => void

A callback function that's called when your mutation successfully completes with zero errors (or if errorPolicy is ignore and partial data is returned).

This function is passed the mutation's result data and any options passed to the mutation.

onQueryUpdated (optional)

(error: ApolloError, clientOptions?: BaseMutationOptions) => void

A callback function that's called when the mutation encounters one or more errors (unless errorPolicy is ignore).

This function is passed an ApolloError object that contains either a networkError object or a graphQLErrors array, depending on the error(s) that occurred, as well as any options passed the mutation.

OnQueryUpdated<any>

Optional callback for intercepting queries whose cache data has been updated by the mutation, as well as any queries specified in the refetchQueries: [...] list passed to client.mutate.

Returning a Promise from onQueryUpdated will cause the final mutation Promise to await the returned Promise. Returning false causes the query to be ignored.

refetchQueries (optional)

((result: FetchResult<NoInfer<TData>>) => InternalRefetchQueriesInclude) | InternalRefetchQueriesInclude

An array (or a function that returns an array) that specifies which queries you want to refetch after the mutation occurs.

Each array value can be either:

An object containing the query to execute, along with any variables
A string indicating the operation name of the query to refetch

NoInfer<TVariables>

An object containing all of the GraphQL variables your mutation requires to execute.

Each key in the object corresponds to a variable name, and that key's value corresponds to the variable value.

Networking options

ApolloClient<object>

The instance of ApolloClient to use to execute the mutation.

By default, the instance that's passed down via context is used, but you can provide a different instance here.

notifyOnNetworkStatusChange (optional)

TContext

If you're using Apollo Link, this object is the initial value of the context object that's passed along your link chain.

boolean

If true, the in-progress mutation's associated component re-renders whenever the network status changes or a network error occurs.

The default value is false.

Caching options

optimisticResponse (optional)

MutationFetchPolicy

Provide no-cache if the mutation's result should not be written to the Apollo Client cache.

The default value is network-only (which means the result is written to the cache).

Unlike queries, mutations do not support fetch policies besides network-only and no-cache.

NoInfer<TData> | ((vars: NoInfer<TVariables>, { IGNORE }: {
        IGNORE: IgnoreModifier;
    }) => NoInfer<TData>)

By providing either an object or a callback function that, when invoked after a mutation, allows you to return optimistic data and optionally skip updates via the IGNORE sentinel object, Apollo Client caches this temporary (and potentially incorrect) response until the mutation completes, enabling more responsive UI updates.

For more information, see Optimistic mutation results.

update (optional)

MutationUpdaterFunction<NoInfer<TData>, NoInfer<TVariables>, TContext, TCache>

A function used to update the Apollo Client cache after the mutation completes.

For more information, see Updating the cache after a mutation.

Other

keepRootFields (optional)

boolean

To avoid retaining sensitive information from mutation root field arguments, Apollo Client v3.4+ automatically clears any ROOT_MUTATION fields from the cache after each mutation finishes. If you need this information to remain in the cache, you can prevent the removal by passing keepRootFields: true to the mutation. ROOT_MUTATION result data are also passed to the mutation update function, so we recommend obtaining the results that way, rather than using this option, if possible.

updateQueries (optional)

MutationQueryReducersMap<NoInfer<TData>>

A MutationQueryReducersMap, which is map from query names to mutation query reducers. Briefly, this map defines how to incorporate the results of the mutation into the results of queries that are currently being watched by your application.

Result

1
[
2
  mutate: (options?: MutationFunctionOptions<TData, TVariables>) => Promise<FetchResult<TData>>,
3
  result: MutationResult<TData>
4
]

A tuple of two values:

Name	Type	Description
mutate	`( options?: MutationFunctionOptions<TData, TVariables> ) => Promise<FetchResult<TData>>`	A function to trigger the mutation from your UI. You can optionally pass this function any of the following options: `awaitRefetchQueries` `context` `fetchPolicy` `onCompleted` `onError` `optimisticResponse` `refetchQueries` `onQueryUpdated` `update` `variables` `client` Any option you pass here overrides any existing value for that option that you passed to `useMutation`. The mutate function returns a promise that fulfills with your mutation result.
result	`MutationResult<TData>`	The result of the mutation.
Show/hide child attributes Other `called` `boolean` If `true`, the mutation's mutate function has been called. `client` `ApolloClient<object>` The instance of Apollo Client that executed the mutation. Can be useful for manually executing followup operations or writing data to the cache. `data` (optional) `TData \| null` The data returned from your mutation. Can be `undefined` if `ignoreResults` is `true`. `error` (optional) `ApolloError` If the mutation produces one or more errors, this object contains either an array of `graphQLErrors` or a single `networkError`. Otherwise, this value is `undefined`. For more information, see Handling operation errors. `loading` `boolean` If `true`, the mutation is currently in flight. `reset` `() => void` A function that you can call to reset the mutation's result to its initial, uncalled state.

`useSubscription`
Since 3.0.0

Refer to the Subscriptions section for a more in-depth overview of useSubscription.

Subscriptions and React 18 Automatic Batching

With React 18's automatic batching, multiple state updates may be grouped into a single re-render for better performance.

If your subscription API sends multiple messages at the same time or in very fast succession (within fractions of a millisecond), it is likely that only the last message received in that narrow time frame will result in a re-render.

Consider the following component:

1
export function Subscriptions() {
2
  const { data, error, loading } = useSubscription(query);
3
  const [accumulatedData, setAccumulatedData] = useState([]);
4

5
  useEffect(() => {
6
    setAccumulatedData((prev) => [...prev, data]);
7
  }, [data]);
8

9
  return (
10
    <>
11
      {loading && <p>Loading...</p>}
12
      {JSON.stringify(accumulatedData, undefined, 2)}
13
    </>
14
  );
15
}

If your subscription back-end emits two messages with the same timestamp, only the last message received by Apollo Client will be rendered. This is because React 18 will batch these two state updates into a single re-render.

Since the component above is using useEffect to push data into a piece of local state on each Subscriptions re-render, the first message will never be added to the accumulatedData array since its render was skipped.

Instead of using useEffect here, we can re-write this component to use the onData callback function accepted in useSubscription's options object:

1
export function Subscriptions() {
2
  const [accumulatedData, setAccumulatedData] = useState([]);
3
  const { data, error, loading } = useSubscription(
4
    query,
5
    {
6
      onData({ data }) {
7
        setAccumulatedData((prev) => [...prev, data])
8
      }
9
    }
10
  );
11

12
  return (
13
    <>
14
      {loading && <p>Loading...</p>}
15
      {JSON.stringify(accumulatedData, undefined, 2)}
16
    </>
17
  );
18
}

⚠️ Note: The useSubscription option onData is available in Apollo Client >= 3.7. In previous versions, the equivalent option is named onSubscriptionData.

Now, the first message will be added to the accumulatedData array since onData is called before the component re-renders. React 18 automatic batching is still in effect and results in a single re-render, but with onData we can guarantee each message received after the component mounts is added to accumulatedData.

Example

1
const COMMENTS_SUBSCRIPTION = gql`
2
  subscription OnCommentAdded($repoFullName: String!) {
3
    commentAdded(repoFullName: $repoFullName) {
4
      id
5
      content
6
    }
7
  }
8
`;
9

10
function DontReadTheComments({ repoFullName }) {
11
  const {
12
    data: { commentAdded },
13
    loading,
14
  } = useSubscription(COMMENTS_SUBSCRIPTION, { variables: { repoFullName } });
15
  return <h4>New comment: {!loading && commentAdded.content}</h4>;
16
}

Signature

1
function useSubscription<TData, TVariables>(
2
  subscription: DocumentNode | TypedDocumentNode<TData, TVariables>,
3
  options?: SubscriptionHookOptions<NoInfer<TData>, NoInfer<TVariables>>
4
): SubscriptionResult<TData, TVariables>

(src/react/hooks/useSubscription.ts)

Parameters

Name / Type

Description

subscription

DocumentNode | TypedDocumentNode<TData, TVariables>

A GraphQL subscription document parsed into an AST by gql.

options (optional)

SubscriptionHookOptions<NoInfer<TData>, NoInfer<TVariables>>

Options to control how the subscription is executed.

Show/hide child attributes

Other

ApolloClient<object>

An ApolloClient instance. By default useSubscription / Subscription uses the client passed down via context, but a different client can be passed in.

DefaultContext

Shared context between your component and your network interface (Apollo Link).

onComplete (optional)

FetchPolicy

How you want your component to interact with the Apollo cache. For details, see Setting a fetch policy.

Since 3.7.0

() => void

Allows the registration of a callback function that will be triggered each time the useSubscription Hook / Subscription component completes the subscription.

onData (optional)

Since 3.7.0

(options: OnDataOptions<NoInfer<TData>>) => any

Allows the registration of a callback function that will be triggered each time the useSubscription Hook / Subscription component receives data. The callback options object param consists of the current Apollo Client instance in client, and the received subscription data in data.

shouldResubscribe (optional)

Since 3.7.0

(error: ApolloError) => void

Allows the registration of a callback function that will be triggered each time the useSubscription Hook / Subscription component receives an error.

boolean | ((options: BaseSubscriptionOptions<NoInfer<TData>, NoInfer<TVariables>>) => boolean)

Determines if your subscription should be unsubscribed and subscribed again when an input to the hook (such as subscription or variables) changes.

skip (optional)

boolean

Determines if the current subscription should be skipped. Useful if, for example, variables depend on previous queries and are not ready yet.

onSubscriptionComplete (optional)

NoInfer<TVariables>

An object containing all of the variables your subscription needs to execute

() => void

⚠️ Deprecated

Use onComplete instead

Allows the registration of a callback function that will be triggered when the useSubscription Hook / Subscription component completes the subscription.

onSubscriptionData (optional)

(options: OnSubscriptionDataOptions<NoInfer<TData>>) => any

⚠️ Deprecated

Use onData instead

Result

Query result object

1
SubscriptionResult<TData, TVariables>

Show/hide child attributes

Other

data (optional)

TData

An object containing the result of your GraphQL subscription. Defaults to an empty object.

error (optional)

ApolloError

A runtime error with graphQLErrors and networkError properties

loading

boolean

A boolean that indicates whether any initial data has been returned

`useApolloClient`
Since 3.0.0

Example

1
import { useApolloClient } from '@apollo/client';
2

3
function SomeComponent() {
4
  const client = useApolloClient();
5
  // `client` is now set to the `ApolloClient` instance being used by the
6
  // application (that was configured using something like `ApolloProvider`)
7
}

Signature

1
function useApolloClient(
2
  override?: ApolloClient<object>
3
): ApolloClient<object>

(src/react/hooks/useApolloClient.ts)

Parameters

Name / Type

Description

override (optional)

ApolloClient<object>

Result

The `ApolloClient` instance being used by the application.

1
ApolloClient<object>

`useReactiveVar`
Since 3.2.0

Reads the value of a reactive variable and re-renders the containing component whenever that variable's value changes. This enables a reactive variable to trigger changes without relying on the useQuery hook.

Example

1
import { makeVar, useReactiveVar } from "@apollo/client";
2
export const cartItemsVar = makeVar([]);
3

4
export function Cart() {
5
  const cartItems = useReactiveVar(cartItemsVar);
6
  // ...
7
}

Signature

1
function useReactiveVar<T>(
2
  rv: ReactiveVar<T>
3
): T

(src/react/hooks/useReactiveVar.ts)

Parameters

Name / Type

Description

rv

ReactiveVar<T>

A reactive variable.

Show/hide child attributes

Other

attachCache

(
  cache: ApolloCache<any>
) => this

forgetCache

(
  cache: ApolloCache<any>
) => boolean

onNextChange

(
  listener: ReactiveListener<T>
) => () => void

Result

The current value of the reactive variable.

1
T

`useFragment`
Since 3.8.0

useFragment represents a lightweight live binding into the Apollo Client Cache and enables Apollo Client to broadcast very specific fragment results to individual components. This hook returns an always-up-to-date view of whatever data the cache currently contains for a given fragment. useFragment never triggers network requests of its own.

Note that the useQuery hook remains the primary hook responsible for querying and populating data in the cache (see the API reference). As a result, the component reading the fragment data via useFragment is still subscribed to all changes in the query data, but receives updates only when that fragment's specific data change.

Note: this hook was introduced in 3.7.0 as experimental but stabilized in 3.8.0. In 3.7.x and 3.8.0-alpha.x releases, this hook is exported as useFragment_experimental. Starting with 3.8.0-beta.0 and greater the _experimental suffix was removed in its named export.

Example

To view a useFragment example, see the Fragments page.

Function Signature

1
function useFragment<
2
  TData = any,
3
  TVars = OperationVariables
4
>({
5
  from: string | StoreObject | Reference;
6
  fragment: DocumentNode | TypedDocumentNode<TData, TVars>;
7
  fragmentName?: string;
8
  optimistic?: boolean;
9
  variables?: TVars;
10
  returnPartialData?: boolean;
11
}): UseFragmentResult<TData> {}

Params

`options`

Name / Type	Description
Operation options
`from` `string \| StoreObject \| Reference`	Required. An object containing a `__typename` and primary key fields (such as `id`) identifying the entity object from which the fragment will be retrieved, or a `{ __ref: "..." }` reference, or a `string` ID (uncommon).
`fragment` `DocumentNode`	Required. A GraphQL fragment document parsed into an AST with the `gql` template literal.
`fragmentName` `string`	The name of the fragment defined in the `fragment` document to use in the call. Required if the `fragment` document includes more than one fragment, optional otherwise.
`optimistic` `boolean`	If `true`, `readFragment` returns optimistic results. The default value is `true`.
`variables` `{ [key: string]: any }`	An object containing all of the GraphQL variables your fragment requires. Each key in the object corresponds to a variable name, and that key's value corresponds to the variable value.
`canonizeResults` `boolean`	⚠️ Deprecated: Using `canonizeResults` can result in memory leaks so we generally do not recommend using this option anymore. A future version of Apollo Client will contain a similar feature without the risk of memory leaks. If `true`, result objects read from the cache will be canonized, which means deeply-equal objects will also be `===` (literally the same object), allowing much more efficient comparison of past/present results. The default value is `false`.

Result

Name / Type	Description
Operation result
`data` `TData`	An object containing the data for a given GraphQL fragment. This value might be `undefined` if a query results in one or more errors (depending on the query's `errorPolicy`).
`complete` `boolean`	A boolean indicating whether the data returned for the fragment is complete. When `false`, the `missing` field should explain which fields were responsible for the incompleteness.
`missing` `MissingTree`	A tree of all `MissingFieldError` messages reported during fragment reading, where the branches of the tree indicate the paths of the errors within the query result.

`useSuspenseQuery`
Since 3.8.0

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 => <Item key={item.id} id={item.id}/>)}
26
    </ol>
27
  );
28
}

Signature

1
function useSuspenseQuery<TData, TVariables>(
2
  query: DocumentNode,
3
  options?: SuspenseQueryHookOptions<TData, TVariables> | SkipToken,
4
): UseSuspenseQueryResult<TData, TVariables>

Params

`query`

Param	Type	Description
`query`	(Typed)DocumentNode	A GraphQL query document parsed into an AST by `gql`.

`options`

Instead of passing a SuspenseQueryHookOptions object into the hook, you can also pass a skipToken to prevent the useSuspenseQuery hook from executing the query or suspending.

`SuspenseQueryHookOptions`

Properties

Name / Type

Description

TVariables

An 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.

ErrorPolicy

Specifies 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.

skip (optional)

boolean

⚠️ Deprecated

We recommend using skipToken in place of the skip option 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.

If true, the query is not executed. The default value is false.

Operation options

ApolloClient<any>

The 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.

queryKey (optional)

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.

Networking options

DefaultContext

If you're using Apollo Link, this object is the initial value of the context object that's passed along your link chain.

Caching options

SuspenseQueryHookFetchPolicy

Specifies 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.

RefetchWritePolicy

Watched queries must opt into overwriting existing data on refetch, by passing refetchWritePolicy: "overwrite" in their WatchQueryOptions.

The default value is "overwrite".

boolean

If 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.

Other

(src/react/hooks/useLoadableQuery.ts)

boolean

⚠️ Deprecated

Whether to canonize cache results before returning them. Canonization takes some extra time, but it speeds up future deep equality comparisons. Defaults to false.

Result

Name / Type	Description
Operation result
`data` `TData`	An 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`).
`error` `ApolloError`	If the query produces one or more errors, this object contains either an array of `graphQLErrors` or a single `networkError`. Otherwise, this value is `undefined`. This property can be ignored when using the default `errorPolicy` or an `errorPolicy` of `none`. The hook will throw the error instead of setting this property.
`networkStatus` `NetworkStatus`	A number indicating the current network state of the query's associated request. See possible values.
Client
`client` `ApolloClient`	The instance of Apollo Client that executed the query. Can be useful for manually executing followup queries or writing data to the cache.
Helper functions
`refetch` `(variables?: Partial<TVariables>) => Promise<ApolloQueryResult>`	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). Calling this function will cause the component to re-suspend, unless the call site is wrapped in `startTransition`.
`fetchMore` `({ query?: DocumentNode, variables?: TVariables, updateQuery: Function}) => Promise<ApolloQueryResult>`	A function that helps you fetch the next set of results for a paginated list field. Calling this function will cause the component to re-suspend, unless the call site is wrapped in `startTransition`.
`subscribeToMore` `(options: { document: DocumentNode, variables?: TVariables, updateQuery?: Function, onError?: Function}) => () => void`	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.

`useBackgroundQuery`
Since 3.8.0

For a detailed explanation of useBackgroundQuery, see the fetching with Suspense reference.

Example

1
import { Suspense } from 'react';
2
import {
3
  ApolloClient,
4
  InMemoryCache,
5
  useBackgroundQuery,
6
  useReadQuery,
7
} from '@apollo/client';
8

9
const query = gql`
10
  foo {
11
    bar
12
  }
13
`;
14

15
const client = new ApolloClient({
16
  uri: "http://localhost:4000/graphql",
17
  cache: new InMemoryCache()
18
});
19

20
function SuspenseFallback() {
21
  return <div>Loading...</div>;
22
}
23

24
function Child({ queryRef }) {
25
  const { data } = useReadQuery(queryRef);
26

27
  return <div>{data.foo.bar}</div>;
28
}
29

30
function Parent() {
31
  const [queryRef] = useBackgroundQuery(query);
32

33
  return (
34
    <Suspense fallback={<SuspenseFallback />}>
35
      <Child queryRef={queryRef} />
36
    </Suspense>
37
  );
38
}
39

40
function App() {
41
  return (
42
    <ApolloProvider client={client}>
43
      <Parent />
44
    </ApolloProvider>
45
  );
46
}

Signature

1
function useBackgroundQuery<TData, TVariables>(
2
  query: DocumentNode | TypedDocumentNode<TData, TVariables>,
3
  options: BackgroundQueryHookOptions<TData, TVariables> | SkipToken,
4
): [
5
  // Will return `undefined` here if no query has been executed yet and the query
6
  // is currently skipped using `skipToken` or { skip: true }
7
  QueryReference<TData> | undefined,
8
  {
9
    fetchMore: FetchMoreFunction<TData, TVariables>;
10
    refetch: RefetchFunction<TData, TVariables>;
11
  }
12
]

Params

`query`

Param	Type	Description
`query`	(Typed)DocumentNode	A GraphQL query document parsed into an AST by `gql`.

`options`

Instead of passing a BackgroundQueryHookOptions object into the hook, you can also pass a skipToken to prevent the useBackgroundQuery hook from executing the query.

If no query has been executed yet and you skip the query, the hook will return undefined instead of a queryRef.

Name / Type	Description
Operation options
`variables` `{ [key: string]: any }`	An 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.
`errorPolicy` `ErrorPolicy`	Specifies 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`, which causes the `useReadQuery` hook to throw the error.
Networking options
`context` `Record<string, any>`	If you're using Apollo Link, this object is the initial value of the `context` object that's passed along your link chain.
`canonizeResults` `Boolean`	⚠️ Deprecated: Using `canonizeResults` can result in memory leaks so we generally do not recommend using this option anymore. A future version of Apollo Client will contain a similar feature without the risk of memory leaks. If `true`, result objects read from the cache will be canonized, which means deeply-equal objects will also be `===` (literally the same object), allowing much more efficient comparison of past/present results. The default value is `false`.
`client` `ApolloClient`	The 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.
Caching options
`fetchPolicy` `SuspenseQueryHookFetchPolicy`	Specifies 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. This hook only supports the `cache-first`, `network-only`, `no-cache`, and `cache-and-network` fetch policies. The default value is `cache-first`.
`returnPartialData` `boolean`	If `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`.
`refetchWritePolicy` `"merge" \| "overwrite"`	Watched queries must opt into overwriting existing data on refetch, by passing `refetchWritePolicy: "overwrite"` in their `WatchQueryOptions`. The default value is `"overwrite"`.
`skip` (deprecated) `boolean`	If `true`, the query is not executed. The default value is `false`. This option is deprecated and only supported to ease the migration from `useQuery`. It will be removed in a future release. Please use `skipToken` instead of the `skip` option as it is more type-safe.

Result

Name / Type	Description
Query reference
`queryRef` `QueryReference<TData>`	In order to link a query initiated by a specific `useBackgroundQuery` call to the place its data is consumed—which can be uniquely identified not only by the query and variables passed, but also the optional `queryKey` supplied by the user—the hook returns a `queryRef` that can later be read by `useReadQuery`.
Helper functions
`refetch` `(variables?: Partial<TVariables>) => Promise<ApolloQueryResult>`	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). Calling this function will cause the component to re-suspend, unless the call site is wrapped in `startTransition`.
`fetchMore` `({ query?: DocumentNode, variables?: TVariables, updateQuery: Function}) => Promise<ApolloQueryResult>`	A function that helps you fetch the next set of results for a paginated list field. Calling this function will cause the component to re-suspend, unless the call site is wrapped in `startTransition`.

`useReadQuery`
Since 3.8.0

For a detailed explanation of useReadQuery, see the fetching with Suspense reference.

Example

See the example in the useBackgroundQuery section above.

Signature

1
function useReadQuery<TData>(
2
  queryRef: QueryReference<TData>
3
): {
4
  data: TData;
5
  networkStatus: NetworkStatus;
6
  error: ApolloError | undefined;
7
} {}

Params

`queryRef`

Param	Type	Description
`queryRef`	QueryReference	The `queryRef` that was generated via `useBackgroundQuery`.

Result

Name / Type	Description
Operation result
`data` `TData`	An 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`).
`error` `ApolloError`	If the query produces one or more errors, this object contains either an array of `graphQLErrors` or a single `networkError`. Otherwise, this value is `undefined`. This property can be ignored when using the default `errorPolicy` or an `errorPolicy` of `none`. The hook will throw the error instead of setting this property.
`networkStatus` `NetworkStatus`	A number indicating the current network state of the query's associated request. See possible values.

`useLoadableQuery`
Since 3.9.0

A hook for imperatively loading a query, such as responding to a user interaction.

Refer to the Suspense - Fetching in response to user interaction section for a more in-depth overview of useLoadableQuery.

Example

1
import { gql, useLoadableQuery } from "@apollo/client";
2

3
const GET_GREETING = gql`
4
  query GetGreeting($language: String!) {
5
    greeting(language: $language) {
6
      message
7
    }
8
  }
9
`;
10

11
function App() {
12
  const [loadGreeting, queryRef] = useLoadableQuery(GET_GREETING);
13

14
  return (
15
    <>
16
      <button onClick={() => loadGreeting({ language: "english" })}>
17
        Load greeting
18
      </button>
19
      <Suspense fallback={<div>Loading...</div>}>
20
        {queryRef && <Hello queryRef={queryRef} />}
21
      </Suspense>
22
    </>
23
  );
24
}
25

26
function Hello({ queryRef }) {
27
  const { data } = useReadQuery(queryRef);
28

29
  return <div>{data.greeting.message}</div>;
30
}

Signature

1
function useLoadableQuery<TData, TVariables>(
2
  query: DocumentNode | TypedDocumentNode<TData, TVariables>,
3
  options?: LoadableQueryHookOptions
4
): UseLoadableQueryResult<TData, TVariables>

Parameters

Name / Type

Description

query

DocumentNode | TypedDocumentNode<TData, TVariables>

A GraphQL query document parsed into an AST by gql.

options (optional)

LoadableQueryHookOptions

Options to control how the query is executed.

Show/hide child attributes

Operation options

ApolloClient<any>

The 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.

ErrorPolicy

Specifies 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.

queryKey (optional)

string | number | any[]

A unique identifier for the query. Each item in the array must be a stable identifier to prevent infinite fetches.

Networking options

DefaultContext

If you're using Apollo Link, this object is the initial value of the context object that's passed along your link chain.

Caching options

LoadableQueryHookFetchPolicy

Specifies 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.

RefetchWritePolicy

boolean

If 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.

Other