Hooks

Apollo Client react hooks API reference

Installation

Apollo Client >= 3 includes React hooks functionality out of the box. You don't need to install any additional packages.

The `ApolloProvider` component

The ApolloProvider component leverages React's Context API to make a configured Apollo Client instance available throughout a React component tree. This component can be imported directly from the @apollo/client package.

1
import { ApolloProvider } from '@apollo/client';

Props

Option	Type	Description
`client`	ApolloClient<TCache>	An `ApolloClient` instance.

Example

1
const client = new ApolloClient({
2
  cache: new InMemoryCache(),
3
  uri: "http://localhost:4000/graphql"
4
});
5

6
ReactDOM.render(
7
  <ApolloProvider client={client}>
8
    <MyRootComponent />
9
  </ApolloProvider>,
10
  document.getElementById('root'),
11
);

The `ApolloConsumer` component

One way to access the configured Apollo Client instance directly is to create an ApolloConsumer component and provide a render prop function as its child. The render prop function will be called with your ApolloClient instance as its only argument. You can think of the ApolloConsumer component as similar to the Consumer component from the React Context API.

Example

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

3
function WithApolloClient() {
4
  return (
5
    <ApolloConsumer>
6
      {client => 'We have access to the client!' /* do stuff here */}
7
    </ApolloConsumer>
8
  );
9
}

`useQuery`

Example

1
import { gql, useQuery } 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 { loading, error, data } = useQuery(GET_GREETING, {
13
    variables: { language: 'english' },
14
  });
15
  if (loading) return <p>Loading ...</p>;
16
  return <h1>Hello {data.greeting.message}!</h1>;
17
}

Refer to the Queries section for a more in-depth overview of useQuery.

Signature

1
function useQuery<TData = any, TVariables = OperationVariables>(
2
  query: DocumentNode,
3
  options?: QueryHookOptions<TData, TVariables>,
4
): QueryResult<TData, TVariables> {}

Params

`query`

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

`options`

Name / Type	Description
Operation options
`query` `DocumentNode`	A GraphQL query string parsed into an AST with the `gql` template literal. Optional for the `useQuery` hook, because the query can be provided as the first parameter to the hook. Required for the `Query` component.
`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`, meaning that the query result includes error details but not partial results.
`onCompleted` `(data: 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`.
`onError` `(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` `boolean`	If `true`, the query is not executed. Not available with `useLazyQuery`. This property is part of Apollo Client's React integration, and it is not available in the core `ApolloClient` API. The default value is `false`.
Networking options
`pollInterval` `number`	Specifies the interval (in milliseconds) at which the query polls for updated results. The default value is `0` (no polling).
`notifyOnNetworkStatusChange` `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`.
`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.
`ssr` `boolean`	Pass `false` to skip executing the query during server-side rendering.
`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` `FetchPolicy`	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`.
`nextFetchPolicy` `FetchPolicy`	Specifies the `fetchPolicy` to use for all executions of this query after this execution. For example, you can use this to switch back to a `cache-first` fetch policy after using `cache-and-network` or `network-only` for a single execution.
`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`.
Deprecated options
`partialRefetch` `boolean`	Deprecated. If `true`, causes a query `refetch` if the query result is detected as partial. 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. The default value is `false`.

Result

Name / Type	Description
Operation data
`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`).
`previousData` `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.
`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`. For more information, see Handling operation errors.
`variables` `{ [key: string]: any }`	An object containing the variables that were provided for the query.
Network info
`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.
`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.
`called` `boolean`	If `true`, the associated lazy query has been executed. This field is only present on the result object returned by `useLazyQuery`.
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). See also Refetching.
`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.
`startPolling` `(interval: 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` `(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.
`updateQuery` `(mapFn: (previousResult: TData, options: { variables: TVariables }) => 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.

`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
}

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

Signature

1
function useLazyQuery<TData = any, TVariables = OperationVariables>(
2
  query: DocumentNode,
3
  options?: LazyQueryHookOptions<TData, TVariables>,
4
): [
5
  (options?: LazyQueryHookOptions<TData, TVariables>) => Promise<LazyQueryResult<TData, TVariables>>,
6
  LazyQueryResult<TData, TVariables>
7
] {}

Params

`query`

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

`options`

Name / Type	Description
Operation options
`query` `DocumentNode`	A GraphQL query string parsed into an AST with the `gql` template literal. Optional for the `useQuery` hook, because the query can be provided as the first parameter to the hook. Required for the `Query` component.
`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`, meaning that the query result includes error details but not partial results.
`onCompleted` `(data: 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`.
`onError` `(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` `boolean`	If `true`, the query is not executed. Not available with `useLazyQuery`. This property is part of Apollo Client's React integration, and it is not available in the core `ApolloClient` API. The default value is `false`.
Networking options
`pollInterval` `number`	Specifies the interval (in milliseconds) at which the query polls for updated results. The default value is `0` (no polling).
`notifyOnNetworkStatusChange` `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`.
`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.
`ssr` `boolean`	Pass `false` to skip executing the query during server-side rendering.
`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` `FetchPolicy`	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`.
`nextFetchPolicy` `FetchPolicy`	Specifies the `fetchPolicy` to use for all executions of this query after this execution. For example, you can use this to switch back to a `cache-first` fetch policy after using `cache-and-network` or `network-only` for a single execution.
`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`.
Deprecated options
`partialRefetch` `boolean`	Deprecated. If `true`, causes a query `refetch` if the query result is detected as partial. 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. The default value is `false`.

Result tuple

Execute function (first tuple item)

Param	Type	Description
Execute function	`(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.

LazyQueryResult<TData, TVariables> object (second tuple item)

Name / Type	Description
Operation data
`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`).
`previousData` `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.
`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`. For more information, see Handling operation errors.
`variables` `{ [key: string]: any }`	An object containing the variables that were provided for the query.
Network info
`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.
`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.
`called` `boolean`	If `true`, the associated lazy query has been executed. This field is only present on the result object returned by `useLazyQuery`.
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). See also Refetching.
`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.
`startPolling` `(interval: 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` `(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.
`updateQuery` `(mapFn: (previousResult: TData, options: { variables: TVariables }) => 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.

`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
}

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

Signature

1
function useMutation<TData = any, TVariables = OperationVariables>(
2
  mutation: DocumentNode,
3
  options?: MutationHookOptions<TData, TVariables>,
4
): MutationTuple<TData, TVariables> {}

Params

`mutation`

Param	Type	Description
`mutation`	DocumentNode	A GraphQL mutation document parsed into an AST by `gql`.

`options`

Name / Type	Description
Operation options
`mutation` `DocumentNode`	A GraphQL query string parsed into an AST with the `gql` template literal. Optional for the `useMutation` hook, because the mutation can also be provided as the first parameter to the hook. Required for the `Mutation` component.
`variables` `{ [key: string]: any }`	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.
`errorPolicy` `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.
`onCompleted` `(data?: 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.
`onError` `(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` `(observableQuery: ObservableQuery, diff: Cache.DiffResult, lastDiff: Cache.DiffResult \| undefined) => boolean \| TResult`	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` `Array<string \| { query: DocumentNode, variables?: TVariables}> \| ((mutationResult: FetchResult) => Array<string \| { query: DocumentNode, variables?: TVariables}>)`	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
`awaitRefetchQueries` `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` `boolean`	If `true`, the mutation's `data` property is not updated with the mutation's result. The default value is `false`.
Networking options
`notifyOnNetworkStatusChange` `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`.
`client` `ApolloClient`	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.
`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.
Caching options
`update` `(cache: ApolloCache, mutationResult: FetchResult) => void`	A function used to update the Apollo Client cache after the mutation completes. For more information, see Updating the cache after a mutation.
`optimisticResponse` `Object`	If provided, 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.
`fetchPolicy` `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`.

`MutationTuple<TData, TVariables>` result tuple

Mutate function:

Name / Type	Description
`mutate` `(options?: MutationOptions) => Promise<FetchResult>`	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.

Mutation result:

Name / Type	Description
`data` `TData`	The data returned from your mutation. Can be `undefined` if `ignoreResults` is `true`.
`loading` `boolean`	If `true`, the mutation is currently in flight.
`error` `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.
`called` `boolean`	If `true`, the mutation's mutate function has been called.
`client` `ApolloClient`	The instance of Apollo Client that executed the mutation. Can be useful for manually executing followup operations or writing data to the cache.
`reset` `() => void`	A function that you can call to reset the mutation's result to its initial, uncalled state.

`useSubscription`

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
}

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.

Signature

1
function useSubscription<TData = any, TVariables = OperationVariables>(
2
  subscription: DocumentNode,
3
  options?: SubscriptionHookOptions<TData, TVariables>,
4
): {
5
  variables: TVariables;
6
  loading: boolean;
7
  data?: TData;
8
  error?: ApolloError;
9
} {}

Params

`subscription`

Param	Type	Description
`subscription`	DocumentNode	A GraphQL subscription document parsed into an AST by `gql`.

`options`

Option	Type	Description
`subscription`	DocumentNode	A GraphQL subscription document parsed into an AST by `graphql-tag`. Optional for the `useSubscription` Hook since the subscription can be passed in as the first parameter to the Hook. Required for the `Subscription` component.
`variables`	{ [key: string]: any }	An object containing all of the variables your subscription needs to execute
`shouldResubscribe`	boolean	Determines if your subscription should be unsubscribed and subscribed again when an input to the hook (such as `subscription` or `variables`) changes.
`skip`	boolean	Determines if the current subscription should be skipped. Useful if, for example, variables depend on previous queries and are not ready yet.
`onSubscriptionData`	Deprecated. (options: OnSubscriptionDataOptions<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 `subscriptionData`.
`onData`	(options: OnDataOptions<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`.
`onError`	(error: ApolloError) => void	Allows the registration of a callback function that will be triggered each time the `useSubscription` Hook / `Subscription` component receives an error.
`onSubscriptionComplete`	Deprecated. () => void	Allows the registration of a callback function that will be triggered when the `useSubscription` Hook / `Subscription` component completes the subscription.
`onComplete`	() => void	Allows the registration of a callback function that will be triggered each time the `useSubscription` Hook / `Subscription` component completes the subscription.
`fetchPolicy`	FetchPolicy	How you want your component to interact with the Apollo cache. For details, see Setting a fetch policy.
`context`	Record<string, any>	Shared context between your component and your network interface (Apollo Link).
`client`	ApolloClient	An `ApolloClient` instance. By default `useSubscription` / `Subscription` uses the client passed down via context, but a different client can be passed in.

Result

Property	Type	Description
`data`	TData	An object containing the result of your GraphQL subscription. Defaults to an empty object.
`loading`	boolean	A boolean that indicates whether any initial data has been returned
`error`	ApolloError	A runtime error with `graphQLErrors` and `networkError` properties

`useApolloClient`

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(): ApolloClient<object> {}

Result

Param	Type	Description
Apollo Client instance	ApolloClient<object>	The `ApolloClient` instance being used by the application.

`useReactiveVar`

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

Signature

1
function useReactiveVar<T>(rv: ReactiveVar<T>): 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
  canonizeResults?: boolean;
12
}): 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`	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.

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 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`	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.
`queryKey` `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.
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
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`	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.

`skipToken`
Since 3.8.0

While not a hook by itself, skipToken is designed to be used with useSuspenseQuery and useBackgroundQuery. If a skipToken is passed into one of those hooks instead of the options object, that hook will not cause any requests or suspenseful behavior, while keeping the last data available.

Recommended usage of skipToken with useSuspenseQuery

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

Recommended usage of skipToken with useBackgroundQuery

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

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

Imagine this very common scenario for skip: You want to skip your query if a certain variable is not set. You might be tempted to write something like this:

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

But in that case, TypeScript will complain:

1
Type '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:

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

Alternatively, you could also use some obscure default value:

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

What both of these solutions have in common: They hide a potential bug. If your skip logic becomes more complex in the future, you might accidentally introduce a bug that causes your query not to be skipped, even though id is still undefined - and TypeScript won't be able to warn you about it.

So instead, we recommend using skipToken, as that will work without a lie to the compiler or an obscure default value:

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

In this case, it becomes apparent for TypeScript that there is a direct connection between skipping and the variables option - and it will work without unsafe workarounds.

ObservableQuery

Testing

Hooks

Apollo Client react hooks API reference

useSuspenseQuerySince 3.8.0

`useSuspenseQuery`
Since 3.8.0