Components

Launch Apollo Studio

Note: Official support for React Apollo render prop components ended in March 2020. This library is still included in the @apollo/client package, but it no longer receives feature updates or bug fixes.

Installation

The render prop library is included in the core @apollo/client package:

npm install @apollo/client

You then import the library's symbols from @apollo/client/react/components.

`Query`

Props

The Query component accepts the following props. query is required.

Name /
Type Description

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`.
`displayName` `string`	The name of your component to be displayed in the React Developer Tools. The default value is `Query`.
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`.

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.

`displayName`

string

The name of your component to be displayed in the React Developer Tools.

The default value is Query.

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

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.

Render prop function

The render prop function that you pass to the children prop of Query is called with an object (QueryResult) that has the following properties. This object contains your query result, plus some helpful functions for refetching, dynamic polling, and pagination.

Name /
Type Description

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` `(previousResult: TData, options: { variables: TVariables }) => TData`	A function that enables you to update the query's cached result without executing a followup GraphQL operation.

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

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

(previousResult: TData, options: { variables: TVariables }) => TData

A function that enables you to update the query's cached result without executing a followup GraphQL operation.

`Mutation`

The Mutation component accepts the following props. Only mutation is required.

Name /
Type Description

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 \| {}) => 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`.
`onError` `(error: ApolloError) => 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.
`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`.

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 | {}) => 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.

`onError`

(error: ApolloError) => 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.

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

Render prop function

The render prop function that you pass to the children prop of Mutation is called with the mutate function and an object with the mutation result. The mutate function is how you trigger the mutation from your UI. The object contains your mutation result, plus loading and error state.

Mutate function:

Name /
Type Description

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` `optimisticResponse` `refetchQueries` `update` `variables` 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.

`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
optimisticResponse
refetchQueries
update
variables

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

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.

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.

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
`onSubscriptionData`	(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`.
`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.

Render prop function

The render prop function that you pass to the children prop of Subscription is called with an object that has the following properties.

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

Components

Deprecated React Apollo render prop component API