Components

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.

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.

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.

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.

If true, the query is not executed.

The default value is false.

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.

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

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.

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

The default value is 0 (no polling).

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.

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

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.

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

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

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.

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.

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

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

The default value is false.

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

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.

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.

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

If true, the associated lazy query has been executed.

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

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

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

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

Used in conjunction with the notifyOnNetworkStatusChange option.

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

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.

A function that instructs the query to begin re-executing at a specified interval (in milliseconds).

A function that instructs the query to stop polling after a previous call to startPolling.

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.

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.

A reference to the internal ObservableQuery used by the hook.

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

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.

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

The default value is false.

A GraphQL document, often created with gql from the graphql-tag package, that contains a single mutation inside of it.

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.

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.

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.

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

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.

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.

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

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.

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.

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.

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

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

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.

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.

If true, the mutation's mutate function has been called.

The instance of Apollo Client that executed the mutation.

Can be useful for manually executing followup operations or writing data to the cache.

The data returned from your mutation. Can be undefined if ignoreResults is true.

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.

If true, the mutation is currently in flight.

A function that you can call to reset the mutation's result to its initial, uncalled state.

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

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

Specifies the ErrorPolicy to be used for this operation

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

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

If true, the hook will not cause the component to rerender. This is useful when you want to control the rendering of your component yourself with logic in the onData and onError callbacks.

Changing this to true when the hook already has data will reset the data to undefined.

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

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.

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

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

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

A GraphQL document, often created with gql from the graphql-tag package, that contains a single subscription inside of it.

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

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

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.

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

A runtime error with graphQLErrors and networkError properties

A boolean that indicates whether any initial data has been returned